feature symfony#60955 [BrowserKit] Add PHPUnit constraints: BrowserHistoryIsOnFirstPage and BrowserHistoryIsOnLastPage (santysisi)

This PR was merged into the 7.4 branch.

Discussion
----------

[BrowserKit] Add PHPUnit constraints: `BrowserHistoryIsOnFirstPage` and `BrowserHistoryIsOnLastPage`

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | no
| License       | MIT

This PR introduces two new PHPUnit constraints to improve testing of browser navigation history state:

- `BrowserHistoryIsOnFirstPage`
- `BrowserHistoryIsOnLastPage`

These constraints allow asserting the current state of the `AbstractBrowser` history using the following new assertion methods:

```php
$this->assertBrowserHistoryIsOnFirstPage();
$this->assertBrowserHistoryIsNotOnFirstPage();
$this->assertBrowserHistoryIsOnLastPage();
$this->assertBrowserHistoryIsNotOnLastPage();
```

Commits
-------

76e80c1 [BrowserKit] Add PHPUnit constraints: `BrowserHistoryIsOnFirstPage` and `BrowserHistoryIsOnLastPage`

Author: fabpot

src/Symfony/Bundle/FrameworkBundle/Test/BrowserKitAssertionsTrait.php

@@ -16,6 +16,7 @@
 use PHPUnit\Framework\Constraint\LogicalNot;
 use PHPUnit\Framework\ExpectationFailedException;
 use Symfony\Component\BrowserKit\AbstractBrowser;
+use Symfony\Component\BrowserKit\History;
 use Symfony\Component\BrowserKit\Test\Constraint as BrowserKitConstraint;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
@@ -122,6 +123,38 @@ public static function assertBrowserNotHasCookie(string $name, string $path = '/
         self::assertThatForClient(new LogicalNot(new BrowserKitConstraint\BrowserHasCookie($name, $path, $domain)), $message);
     }
 
+    public static function assertBrowserHistoryIsOnFirstPage(string $message = ''): void
+    {
+        if (!method_exists(History::class, 'isFirstPage')) {
+            throw new \LogicException('The `assertBrowserHistoryIsOnFirstPage` method requires symfony/browser-kit >= 7.4.');
+        }
+        self::assertThatForClient(new BrowserKitConstraint\BrowserHistoryIsOnFirstPage(), $message);
+    }
+
+    public static function assertBrowserHistoryIsNotOnFirstPage(string $message = ''): void
+    {
+        if (!method_exists(History::class, 'isFirstPage')) {
+            throw new \LogicException('The `assertBrowserHistoryIsNotOnFirstPage` method requires symfony/browser-kit >= 7.4.');
+        }
+        self::assertThatForClient(new LogicalNot(new BrowserKitConstraint\BrowserHistoryIsOnFirstPage()), $message);
+    }
+
+    public static function assertBrowserHistoryIsOnLastPage(string $message = ''): void
+    {
+        if (!method_exists(History::class, 'isLastPage')) {
+            throw new \LogicException('The `assertBrowserHistoryIsOnLastPage` method requires symfony/browser-kit >= 7.4.');
+        }
+        self::assertThatForClient(new BrowserKitConstraint\BrowserHistoryIsOnLastPage(), $message);
+    }
+
+    public static function assertBrowserHistoryIsNotOnLastPage(string $message = ''): void
+    {
+        if (!method_exists(History::class, 'isLastPage')) {
+            throw new \LogicException('The `assertBrowserHistoryIsNotOnLastPage` method requires symfony/browser-kit >= 7.4.');
+        }
+        self::assertThatForClient(new LogicalNot(new BrowserKitConstraint\BrowserHistoryIsOnLastPage()), $message);
+    }
+
     public static function assertBrowserCookieValueSame(string $name, string $expectedValue, bool $raw = false, string $path = '/', ?string $domain = null, string $message = ''): void
     {
         self::assertThatForClient(LogicalAnd::fromConstraints(

src/Symfony/Bundle/FrameworkBundle/Tests/Test/WebTestCaseTest.php

@@ -13,12 +13,14 @@
 
 use PHPUnit\Framework\AssertionFailedError;
 use PHPUnit\Framework\ExpectationFailedException;
+use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
 use Symfony\Bundle\FrameworkBundle\KernelBrowser;
 use Symfony\Bundle\FrameworkBundle\Test\WebTestAssertionsTrait;
 use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
 use Symfony\Component\BrowserKit\Cookie;
 use Symfony\Component\BrowserKit\CookieJar;
+use Symfony\Component\BrowserKit\History;
 use Symfony\Component\DomCrawler\Crawler;
 use Symfony\Component\HttpFoundation\Cookie as HttpFoundationCookie;
 use Symfony\Component\HttpFoundation\Request;
@@ -190,6 +192,50 @@ public function testAssertBrowserCookieValueSame()
         $this->getClientTester()->assertBrowserCookieValueSame('foo', 'babar', false, '/path');
     }
 
+    /**
+     * @requires function \Symfony\Component\BrowserKit\History::isFirstPage
+     */
+    public function testAssertBrowserHistoryIsOnFirstPage()
+    {
+        $this->createHistoryTester('isFirstPage', true)->assertBrowserHistoryIsOnFirstPage();
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('Failed asserting that the Browser history is on the first page.');
+        $this->createHistoryTester('isFirstPage', false)->assertBrowserHistoryIsOnFirstPage();
+    }
+
+    /**
+     * @requires function \Symfony\Component\BrowserKit\History::isFirstPage
+     */
+    public function testAssertBrowserHistoryIsNotOnFirstPage()
+    {
+        $this->createHistoryTester('isFirstPage', false)->assertBrowserHistoryIsNotOnFirstPage();
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('Failed asserting that the Browser history is not on the first page.');
+        $this->createHistoryTester('isFirstPage', true)->assertBrowserHistoryIsNotOnFirstPage();
+    }
+
+    /**
+     * @requires function \Symfony\Component\BrowserKit\History::isLastPage
+     */
+    public function testAssertBrowserHistoryIsOnLastPage()
+    {
+        $this->createHistoryTester('isLastPage', true)->assertBrowserHistoryIsOnLastPage();
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('Failed asserting that the Browser history is on the last page.');
+        $this->createHistoryTester('isLastPage', false)->assertBrowserHistoryIsOnLastPage();
+    }
+
+    /**
+     * @requires function \Symfony\Component\BrowserKit\History::isLastPage
+     */
+    public function testAssertBrowserHistoryIsNotOnLastPage()
+    {
+        $this->createHistoryTester('isLastPage', false)->assertBrowserHistoryIsNotOnLastPage();
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('Failed asserting that the Browser history is not on the last page.');
+        $this->createHistoryTester('isLastPage', true)->assertBrowserHistoryIsNotOnLastPage();
+    }
+
     public function testAssertSelectorExists()
     {
         $this->getCrawlerTester(new Crawler('<html><body><h1>'))->assertSelectorExists('body > h1');
@@ -386,6 +432,19 @@ private function getRequestTester(): WebTestCase
         return $this->getTester($client);
     }
 
+    private function createHistoryTester(string $method, bool $returnValue): WebTestCase
+    {
+        /** @var KernelBrowser&MockObject $client */
+        $client = $this->createMock(KernelBrowser::class);
+        /** @var History&MockObject $history */
+        $history = $this->createMock(History::class);
+
+        $history->method($method)->willReturn($returnValue);
+        $client->method('getHistory')->willReturn($history);
+
+        return $this->getTester($client);
+    }
+
     private function getTester(KernelBrowser $client): WebTestCase
     {
         $tester = new class(method_exists($this, 'name') ? $this->name() : $this->getName()) extends WebTestCase {

src/Symfony/Component/BrowserKit/CHANGELOG.md

@@ -5,6 +5,7 @@ CHANGELOG
 ---
 
  * Add `isFirstPage()` and `isLastPage()` methods to the History class for checking navigation boundaries
+ * Add PHPUnit constraints: `BrowserHistoryIsOnFirstPage` and `BrowserHistoryIsOnLastPage`
 
 6.4
 ---

src/Symfony/Component/BrowserKit/Test/Constraint/BrowserHistoryIsOnFirstPage.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\BrowserKit\Test\Constraint;
+
+use PHPUnit\Framework\Constraint\Constraint;
+use Symfony\Component\BrowserKit\AbstractBrowser;
+
+final class BrowserHistoryIsOnFirstPage extends Constraint
+{
+    public function toString(): string
+    {
+        return 'is on the first page';
+    }
+
+    protected function matches($other): bool
+    {
+        if (!$other instanceof AbstractBrowser) {
+            throw new \LogicException('Can only test on an AbstractBrowser instance.');
+        }
+
+        return $other->getHistory()->isFirstPage();
+    }
+
+    protected function failureDescription($other): string
+    {
+        return 'the Browser history '.$this->toString();
+    }
+}

src/Symfony/Component/BrowserKit/Test/Constraint/BrowserHistoryIsOnLastPage.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\BrowserKit\Test\Constraint;
+
+use PHPUnit\Framework\Constraint\Constraint;
+use Symfony\Component\BrowserKit\AbstractBrowser;
+
+final class BrowserHistoryIsOnLastPage extends Constraint
+{
+    public function toString(): string
+    {
+        return 'is on the last page';
+    }
+
+    protected function matches($other): bool
+    {
+        if (!$other instanceof AbstractBrowser) {
+            throw new \LogicException('Can only test on an AbstractBrowser instance.');
+        }
+
+        return $other->getHistory()->isLastPage();
+    }
+
+    protected function failureDescription($other): string
+    {
+        return 'the Browser history '.$this->toString();
+    }
+}