This release introduces a number of breaking changes. We have tried to limit the impact of these on end-users – most are in code that we expect is only referenced internally. There are some unavoidable changes that will affect end-users and extension authors, but we expect you will be able to apply the vast majority of updates using automated tools. See https://docs.behat.org/en/v4.x/releases/upgrading-to-4.0.html for advice on upgrading.

For end-users, this is essentially a stable release, ready to use in your CI. The only reason for shipping as an alpha first is to allow extension authors to add support for Behat 4.x and feed back on any issues before we finalise 4.0.0.

We expect there will be a small number of breaking changes between 4.0.0-alpha1 and 4.0.0. See https://docs.behat.org/en/v4.x/releases/upgrading-to-4.0.html for details.

Behat has no corporate backing - the 4.0 release has taken a huge effort from the volunteer maintainers over the last 9 months. If you use Behat for work, please consider showing your appreciation by supporting the project - even small contributions make a big difference.

Changed

• Future 4.x releases will not guarantee backwards compatibility except for code that is explicitly marked as being part of our public API. See https://docs.behat.org/en/v4.x/releases/backwards-compatibility.html for details.
• Drop support for using @annotations to define steps, hooks, and transformations by @carlos-granados in #1790
• Drop support for YAML config and finding files in config dir by @carlos-granados in #1791
• Drop support for configuring extensions using short names by @carlos-granados in #1793
• Use GherkinCompatibilityMode::GHERKIN_32 by default by @acoulton in #1812
• Extension interface should not extend third-party interface by @acoulton in #1796
• Remove ScenarioLikeTested in favour of separate events by @acoulton in #1834
• Add strict parameter, property and return types throughout the codebase
  By @acoulton in #1820, #1822, #1824, and #1831
  And by @stof in #1837, #1836, #1839 and #1838.
• Use explicit type for late-bound Context callable methods by @acoulton in #1854
• Define a mandatory constructor for SimpleArgumentTransformation implementations by @acoulton in #1854
• Drop deprecated constants, methods, constructor parameters and similar code.
  By @acoulton in #1694
  and by @carlos-granados in #1814

Added

• Support Symfony 8 by @Kocal in #1687 and @acoulton in #1758

Internal

NOTE: this includes breaking changes to some classes that are not considered part of the public API from 4.0 onwards.

• Move StopOnFailureController to Testwork\Tester\Cli namespace by @carlos-granados in #1809
• Finalise all non-API classes that are not extended by @acoulton in #1815

Added

• Support GHERKIN_32 parsing mode in pretty formatter by @acoulton in #1842

Fixed

• Only print between Step keyword & text if correct for language by @acoulton in #1845
• JSON formatter should support GHERKIN_32 mode by @acoulton in #1847
• Unexpected uses / creation of RuntimeCallee callables by @acoulton in #1853
• Handle empty argument lists when converting Context config to PHP by @acoulton in #1849

Internal

• Fail on Behat deprecations in CI by @acoulton in #1833
• Add runtime deprecations for ScenarioLikeTested interface by @acoulton in #1832
• Add a scenario covering the behavior of invalid gherkin files by @stof in #1840
• Prove JUnit scenario description handling in gherkin compat modes by @acoulton in #1843
• Run features in gherkin-32 and legacy compatibility modes by @acoulton in #1848

Fixed

• Callee description can be null by @acoulton in #1821
• Always populate language in TranslatedDefinition by @acoulton in #1826
• Return type on ScenarioLikeTested, and add strict returns to final events by @acoulton in #1816
• Type hinting / safety of TableColumnTransformation by @acoulton in #1823
• Incorrect not-null string phpdoc typehints by @acoulton in #1825

Internal

• Add more backwards-compatible strict types to private / final properties, method parameters, and method returns
  By @acoulton in #1817 and #1818
• Ignore PHPUnit security advisory related to PHP ini Argument injection
  PKSA-5jz8-6tcw-pbk4 has minimal impact in our CI environment.
  Contributors installing dev dependencies locally should be aware of the potential risk if an attacker can gain write
  access to phpunit.xml or shell execution.
  By @acoulton in #1827

Changed

• Explicitly mark up interfaces, classes & methods that we consider to be the public API.
  This will not affect our backwards compatibility guarantees for the 3.x series, but from 4.0 onwards we will only guarantee BC for code that is explicitly marked as being part of the API.
  By @acoulton in #1807
• Move gherkin configuration to dedicated GherkinOptions config object. The previous API for setting filters by calling ->withFilters() on Profile is deprecated and will be removed in 4.0.
  By @acoulton in #1798
• Make Extension::process() explicit in the Extension interface & document Extension dependencies.
  Clarifies that extensions should declare their own dependencies on any symfony packages they interact with directly.
  By @acoulton in #1795 and #1804
• Drop PHP 8.1 support by @carlos-granados in #1782

Added

• Support configuring GherkinCompatibilityMode to control how Gherkin files are parsed.
  The default mode behaves identically to legacy parser behaviour. The opt-in experimental gherkin-32 mode parses equivalent to the official cucumber/gherkin parsers. We expect to make gherkin-32 the default in the 4.0 release.
  See the documentation for more details.
  By @acoulton in #1799
• Add deprecation collector to capture and print Behat deprecations.
  Users can opt-in to display and/or fail on deprecations using the methods on the TesterOptions config object.
  Extension developers can log their own runtime deprecations by calling DeprecationCollector::trigger().
  By @carlos-granados in #1794

Internal

• Add backwards-compatible strict types to private / final properties, method parameters, and method returns. By @acoulton in #1779 and #1808
• Update all test files to use attributes instead of annotations by @carlos-granados in #1777
• Normalize PHP file line numbers in test output to avoid fragile tests by @carlos-granados in #1783
• Apply coding style fixes by @carlos-granados in #1786
• Reorganize FeatureContext and add PHP types by @carlos-granados in #1789
• Add runtime deprecation messages when using deprecated classes / methods by @carlos-granados in #1805
• Run Behat's own features in gherkin-32 parsing mode by @acoulton in #1801
• Cast key to string for array_key_exists by @barryswaisland-eagleeye in #1806
• Improve type-safety of regex string replacement operations by @acoulton in #1778
• Use first-class callables for internal callbacks by @acoulton in #1780

Changed

• Add initial backwards-compatible return types to final classes, final methods and private methods. These changes should not impact end-users or extension authors.
  This is work towards the upcoming 4.0.0 release, which will add support for symfony8 and introduce strict types throughout.
  By @acoulton in #1763

Changed

• Add backwards-compatible return types ahead of symfony8 by @Kocal (cherry-picked by @acoulton) in #1702
• Rename the default branch from master to 3.x and remove the dev-master composer branch alias by @acoulton in #1708

Added

• Add printSkippedSteps option to pretty formatter (true by default) by @carlos-granados in #1705
• Accept multiple path arguments on CLI
  This PR was originally contributed to a 4.x branch which was then abandoned. The feature was later implemented in 3.x by a different contributor, but we wanted to also credit the previous work done. The only actual change in this release is an internal (backwards compatible) change to the use of WrongPathsException. By @adrienbrault in #1397 and merged back to 3.x by @acoulton in #1693

Fixed

• Improve performance by caching definition translations by @carlos-granados in #1706
• Resolve deprecation with symfony/console > 7.4.0, fix phpstan by @acoulton in #1757

Internal

• Add funding links - please consider supporting Behat development! by @acoulton in #1704
• Fix static analysis in PHP 8.5 by @carlos-granados in #1719
• Fix phpunit configuration by @carlos-granados in #1716
• Replace friendsofphp/php-cs-fixer by php-cs-fixer/shim by @Kocal (cherry-picked by @acoulton) #1701
• Add automated check for BC breaks in CI by @acoulton in #1762
• Refactor feature files and improve coverage of --rerun and --rerun-only
  by @carlos-granados in #1770, #1764, #1766, and #1771
• Refactor all feature files to use test fixtures instead of inline strings by @carlos-granados in #1707, #1709, #1711, #1713, #1714, #1710, #1715, #1717, #1720, #1721, #1722, #1723, #1724, #1725, #1726, #1729, #1727, #1728, #1730, #1731, #1734, #1735, #1736, #1737, #1738, #1740, #1739, #1741, #1742, #1750, #1751, #1752, #1755, #1753, #1760, #1761, #1756, #1767, #1765, #1769, #1768, #1773, and #1774

Changed

• Use the exit code 130 on SIGINT by @andrewnicols in #1686

Added

• Add support for PHP 8.5 by @acoulton in #1689

Internal

• Prepare the pretty printer for future changes in the Gherkin parser by @stof in #1690
• Add tests proving that multiple Examples tables are supported by @acoulton in #1696

Changed

• Support configuring how file paths are rendered by the JUnit formatter (relative or absolute, removing a prefix, etc). Previously, the JUnit formatter would print an absolute path unless the file was beneath the current working
  directory.
  The new default is to print paths relative to the Behat base directory - in most cases this will also be the current working directory and therefore the result will be the same. However, in some cases the reported file paths will change so you may wish to review the configuration e.g. if your tooling aggregates build results over time.
  By @carlos-granados in #1677

Added

• Implement JSON formatter by @carlos-granados in #1674, #1680, #1681, #1677 and #1684.
• Add feature file attribute on <testsuite> nodes in the JUnit formatters by @carlos-granados in #1680
• Add timer option to disable reporting execution times in the JUnit formatter by @carlos-granados in #1681

Fixed

• error_reporting in the Behat configuration should take precedence over system defaults by @carlos-granados in #1675
• Ensure runtime assertions are checked during --convert-config by @carlos-granados in #1679
• Include consistent index & placeholders for Example names in JUnit by @acoulton in [#1682]#1682)
  based on work previously done by @uuf6429.

Internal

• Add AGENTS.md file with instructions for AI agents by @carlos-granados in #1672
• Fix php version constraint in composer.json by @carlos-granados in #1678

Added

• Add short_summary formatter option by @carlos-granados in #1664

Fixed

• Provide more context when failing with unexpected multiline args by @acoulton in #1668

Internal

• Remove PHP 8 error conversion by @carlos-granados in #1665
• Apply Rector rules to use PHP 8.1 language features by @carlos-granados in #1666

Fixed

• Fix rendering editorUrl links in console output by @carlos-granados in #1661