Skip to content

docs: Update 4.0 upgrade guide #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
acoulton merged 1 commit into from
Sep 28, 2026
Merged

docs: Update 4.0 upgrade guide #238

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 17 additions & 22 deletions releases/upgrading-to-4.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ For most projects, these are the main changes:
Attributes.
* **Cleanup:** All previously deprecated features and code have been removed.
* **New Parser Mode:** We now default to a newer parser compatibility mode
(:doc:`GHERKIN_32 </user_guide/gherkin/parser_mode>`).
(:doc:`GHERKIN_42 </user_guide/gherkin/parser_mode>`).

Step-by-step preparation
~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -36,8 +36,15 @@ Step-by-step preparation
usually handles this.
5. **Convert Annotations:** Use `Rector`_ with the ``->withAttributeSets(behat: true)`` rule to automatically change
`Behat annotations`_ into PHP Attributes.
6. **Check Deprecations:** Run your tests with ``--fail-on-deprecations`` and fix any warnings that appear.
7. **Test the New Parser:** Enable the :doc:`GHERKIN_32 parser mode </user_guide/gherkin/parser_mode>` and see if your
6. **Parameter Matching:** You may see deprecations if your step definition patterns capture a different number
of arguments to the function parameters. These will become an error in 4.0. Fix these by adding the missing
parameters to your function, or using non-capturing groups in your regex.
7. **PHPUnit assertions:** We no longer recommend using PHPUnit assertions in your Behat steps, as the
creator of PHPUnit has stated that this is not supported or covered by any backwards compatibility
promise. If your steps use PHPUnit assertions, add the `behat/phpunit-assertions-extension`_ for
improved support in 3.x. You will need this extension in 4.0, as the built-in support has been removed.
8. **Check other Deprecations:** Run your tests with ``--fail-on-deprecations`` and fix any warnings that appear.
9. **Test the New Parser:** Enable the :doc:`GHERKIN_42 parser mode </user_guide/gherkin/parser_mode>` and see if your
tests still run correctly. If you have issues, you can fix your feature files or use
``GherkinCompatibilityMode::LEGACY`` in your config. This mode will be removed in the future.

Expand All @@ -46,10 +53,6 @@ Ready to upgrade?

Once you've completed the steps above, update your ``composer.json`` to start using Behat 4.0!

.. caution::
While we are in the alpha phase, we recommend using:
``{"require": {"behat/behat": "4.0.0-alpha1@alpha"}}``.

.. note::
Don't forget to update your third-party extensions to versions that support Behat 4.0. If you find one that hasn't
been updated yet, consider helping out by submitting a Pull Request! The community's help makes the transition faster
Expand Down Expand Up @@ -80,28 +83,20 @@ Here are the key changes for all extension authors:
This ensures they are correctly handled by Behat's deprecation flags regardless of the user's runtime environment.
* **Event Changes:** The ``ScenarioLikeTested`` base event class has been removed. ``ScenarioTested`` and
``BackgroundTested`` are now separate. This may affect you if you maintain a formatter extension.
* **Transformations:** If you define your own step argument transformations, the ``ArgumentTransformer`` and
``SimpleArgumentTransformation`` interfaces have changed.
* **Pretty Behat output format:** The output of the Pretty formatter has changed slightly, and is no longer
guaranteed to be consistent between releases. If your extension has its own Behat features, and needs to
assert the result / output of a Behat run, we strongly recommend against one of the machine-readable
output formats e.g. ``json`` or ``junit``.

There are several other changes that might affect a minority of extension authors. See the full
`CHANGELOG`_ for details.

Planned changes before the final 4.0.0 release
----------------------------------------------

We plan to make two more significant changes before the final 4.0.0 release:

* **Parameter Matching:** We are reviewing how steps behave when the number of function parameters doesn't match the
step definition. This will likely trigger a deprecation or a failure. You can follow the progress in `#1691`_.
* **PHPUnit Assertions:** Support for rendering PHPUnit assertion failures will move to a standalone extension. While
tests will still pass or fail, the output will be less detailed without the extension. We no longer recommend using
PHPUnit for assertions within Behat steps, as the PHPUnit project has confirmed this is not supported. See
`#1746`_ for details.

We may make additional changes based on feedback from the community as more people begin to upgrade.

.. _`convert it to PHP`: https://docs.behat.org/en/v3.x/user_guide/configuration/yaml_configuration.html#converting-your-configuration
.. _`Rector`: https://getrector.com/documentation
.. _`Behat annotations`: https://docs.behat.org/en/v3.x/user_guide/annotations.html#existing-code
.. _`AddReturnTypeBasedOnParentClassMethodRector`: https://getrector.com/rule-detail/add-return-type-declaration-based-on-parent-class-method-rector
.. _`CHANGELOG`: https://github.com/Behat/Behat/blob/4.x/CHANGELOG.md
.. _`#1691`: https://github.com/Behat/Behat/issues/1691
.. _`#1746`: https://github.com/Behat/Behat/issues/1746
.. _`behat/phpunit-assertions-extension`: https://github.com/behat/PHPUnitAssertionsExtension
Loading