Add moveForward() to navigate forward in history

Mirror of moveBack(): walks the BrowserKit history pointer forward N steps
and replays the request with changeHistory = false, matching Symfony's
native AbstractBrowser::forward(). Symfony exposes both back() and forward()
with identical semantics, so InnerBrowser now offers the symmetric pair.

This is purely additive (new public method) and is only usable now that
moveBack() preserves the forward history entries instead of discarding them.

Tests: testMoveForwardOneStep, testMoveForwardTwoSteps and
testMoveForwardThrowsExceptionIfNumberOfStepsIsInvalid. The forward tests
also assert that moveBack() kept the forward stack intact.

Author: Aaron Gustavo Nieves

src/Codeception/Lib/InnerBrowser.php

@@ -2015,6 +2015,46 @@ public function moveBack(int $numberOfSteps = 1): void
         );
     }
 
+    /**
+     * Moves forward in history.
+     *
+     * @param int $numberOfSteps (default value 1)
+     */
+    public function moveForward(int $numberOfSteps = 1): void
+    {
+        $request = null;
+        if (!is_int($numberOfSteps) || $numberOfSteps < 1) {
+            throw new InvalidArgumentException('numberOfSteps must be positive integer');
+        }
+
+        try {
+            $history = $this->getRunningClient()->getHistory();
+            for ($i = $numberOfSteps; $i > 0; --$i) {
+                $request = $history->forward();
+            }
+        } catch (LogicException $exception) {
+            throw new InvalidArgumentException(
+                sprintf(
+                'numberOfSteps is set to %d, but there are only %d forward steps in the history',
+                $numberOfSteps,
+                $numberOfSteps - $i
+            ), $exception->getCode(), $exception);
+        }
+
+        // Replay the next request without appending to the history, so the
+        // browser history pointer moves forward (like a real Forward button)
+        // instead of pushing a new entry.
+        $this->_loadPage(
+            $request->getMethod(),
+            $request->getUri(),
+            $request->getParameters(),
+            $request->getFiles(),
+            $request->getServer(),
+            $request->getContent(),
+            false
+        );
+    }
+
     protected function debugCookieJar(): void
     {
         $cookies = $this->client->getCookieJar()->all();

tests/unit/Codeception/Module/FrameworksTest.php

@@ -100,6 +100,50 @@ public function testMoveBackThrowsExceptionIfNumberOfStepsIsInvalid()
         }
     }
 
+    public function testMoveForwardOneStep()
+    {
+        $this->module->amOnPage('/iframe');
+        $this->module->amOnPage('/info');
+        $this->module->amOnPage('/');
+        $this->module->moveBack(2);
+        $this->module->seeCurrentUrlEquals('/iframe');
+        $this->module->moveForward();
+        $this->module->seeCurrentUrlEquals('/info');
+        $this->module->moveForward();
+        $this->module->seeCurrentUrlEquals('/');
+    }
+
+    public function testMoveForwardTwoSteps()
+    {
+        $this->module->amOnPage('/iframe');
+        $this->module->amOnPage('/info');
+        $this->module->amOnPage('/');
+        $this->module->moveBack(2);
+        $this->module->seeCurrentUrlEquals('/iframe');
+        $this->module->moveForward(2);
+        $this->module->seeCurrentUrlEquals('/');
+    }
+
+    public function testMoveForwardThrowsExceptionIfNumberOfStepsIsInvalid()
+    {
+        $this->module->amOnPage('/iframe');
+        $this->module->amOnPage('/');
+        $this->module->moveBack();
+        $this->module->seeCurrentUrlEquals('/iframe');
+
+        $invalidValues = [0, -5, 1.5, 'a', 3];
+        foreach ($invalidValues as $invalidValue) {
+            try {
+                $this->module->moveForward($invalidValue);
+                $this->fail('Expected to get exception here');
+            } catch (InvalidArgumentException $exception) {
+                codecept_debug('Exception: ' . $exception->getMessage());
+            } catch (TypeError $error) {
+                codecept_debug('Error: ' . $error->getMessage());
+            }
+        }
+    }
+
     public function testCreateSnapshotOnFail()
     {
         $container = Stub::make(ModuleContainer::class);