From fbb94e47357a621a072e1073eff188921dc5b909 Mon Sep 17 00:00:00 2001
From: Lorenzo <loru88@gmail.com>
Date: Tue, 30 Sep 2025 18:06:49 +0000
Subject: [PATCH] update to tell PHPUnit assertions stopped working

resolve Behat/Behat#1618
---
 quick_start.rst      | 51 ++++++++++++++++++++-----------------------
 useful_resources.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 27 deletions(-)

diff --git a/quick_start.rst b/quick_start.rst
index 2cb8090..3a77343 100644
--- a/quick_start.rst
+++ b/quick_start.rst
@@ -455,21 +455,32 @@ code we could come up with to fulfil our scenario. Something like this:
          #[Then('I should have :arg1 product(s) in the basket')]
         public function iShouldHaveProductInTheBasket($count)
         {
-            // Normally you would import this class - we are using the fully qualified name
-            // to highlight that Behat does not come with an assertion tool (see note below).
-            \PHPUnit\Framework\Assert::assertCount(
-                intval($count),
-                $this->basket
-            );
+            if (count($this->basket) !== intval($count)) {
+                throw new \Exception(
+                    sprintf(
+                        'The basket should have %d item(s), but it has %d.',
+                        intval($count),
+                        count($this->basket)
+                    )
+                );
+            }
         }
 
          #[Then('the overall basket price should be £:arg1')]
         public function theOverallBasketPriceShouldBePs($price)
         {
-            \PHPUnit\Framework\Assert::assertSame(
-                floatval($price),
-                $this->basket->getTotalPrice()
-            );
+            $expectedPrice = floatval($price);
+            $actualPrice = $this->basket->getTotalPrice();
+
+            if ($expectedPrice !== $actualPrice) {
+                throw new \Exception(
+                    sprintf(
+                        'Expected basket total price to be %s, but got %s.',
+                        $expectedPrice,
+                        $actualPrice
+                    )
+                );
+            }
         }
     }
 
@@ -477,27 +488,13 @@ As you can see, in order to test and implement our application, we introduced 2
 ``Shelf`` and ``Basket``. The first is responsible for storing products and their prices,
 the second is responsible for the representation of our customer basket. Through appropriate step
 definitions we declare products' prices and add products to the basket. We then compare the
-state of our ``Basket`` object with our expectations using PHPUnit assertions.
+state of our ``Basket`` object with our expectations and throw exception if the expectations aren't met.
 
 .. note::
 
     Behat doesn't come with its own assertion tool, but you can use any proper assertion
-    tool out there. A proper assertion tool is a library whose assertions throw
-    exceptions on failure. For example, if you're familiar with PHPUnit you can use
-    its assertions in Behat by installing it via composer:
-
-    .. code-block:: bash
-
-        $ php composer.phar require --dev phpunit/phpunit
-
-    and then by simply using assertions in your steps:
-
-    .. code-block:: php
-
-        \PHPUnit\Framework\Assert::assertCount(
-            intval($count),
-            $this->basket
-        );
+    tool out there.
+    Learn more in the paragraph :ref:`assertion-tools`
 
 Now try to execute your feature tests:
 
diff --git a/useful_resources.rst b/useful_resources.rst
index 4fe2abd..bad35c8 100644
--- a/useful_resources.rst
+++ b/useful_resources.rst
@@ -18,6 +18,58 @@ Integrating Behat with PHPStorm
 More information on integrating Behat with PHPStorm can be found in this
 `blog post`_.
 
+.. _assertion-tools:
+
+Assertion tools
+---------------
+
+A proper assertion tool is a library whose assertions throw exceptions on failure.
+
+For example a list of the most known:
+
+- https://github.com/webmozarts/assert
+- https://github.com/beberlei/assert
+- https://github.com/zenstruck/assert
+
+.. caution::
+    If you are familiar with PHPUnit, you can use its assertion library
+
+    .. code-block:: bash
+
+        $ php composer.phar require --dev phpunit/phpunit
+
+    and then by simply using assertions in your steps:
+
+    .. code-block:: php
+
+        \PHPUnit\Framework\Assert::assertCount(
+            intval($count),
+            $this->basket
+        );
+
+    **However, using PHPUnit for assertions no longer works with PHP 11.3.0 and later**.
+
+    This is due to a change in how PHPUnit's internal components are initialized.
+    A direct alternative that provides a complete object and array comparison is not readily available.
+
+    Learn more at https://github.com/Behat/Behat/issues/1618.
+
+    However, a workaround exists by modifying the PHPUnit bootstrap file (in Symfony is usually at `tests/bootstrap.php`)
+    to explicitly initialize the PHPUnit configuration when running Behat.
+    This involves adding the following lines to your bootstrap file:
+
+    .. code-block:: php
+
+        if (defined('BEHAT_BIN_PATH')) {
+            (new \PHPUnit\TextUI\Configuration\Builder())->build([]);
+        }
+
+    This is a hack that forces PHPUnit to load the necessary components.
+    The downside is that it creates a tight coupling between your project and PHPUnit's internal non-public API
+    and it forces the entire PHPUnit framework to be bootstrapped along with Behat, which results in a larger memory footprint.
+    This makes the workaround brittle and prone to breaking with future updates.
+
+
 Behat cheat sheet
 -----------------