From f40c6d5c638fdc820ff12398bd314f89d7cd5ea3 Mon Sep 17 00:00:00 2001 From: Andrew Coulton Date: Fri, 25 Sep 2026 22:25:48 +0100 Subject: [PATCH 1/3] doc: Update GherkinCompatibilityMode documentation For the new mode, and to cover Rule and multiple step args support. --- user_guide/gherkin/parser_mode.rst | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/user_guide/gherkin/parser_mode.rst b/user_guide/gherkin/parser_mode.rst index 23885bb..1dbb1d9 100644 --- a/user_guide/gherkin/parser_mode.rst +++ b/user_guide/gherkin/parser_mode.rst @@ -12,11 +12,10 @@ To resolve this, we have added a ``GherkinCompatibilityMode`` setting to the par has two possible options: * ``GherkinCompatibilityMode::LEGACY`` - match our previous behaviour. This is the default in Behat 3.x. -* ``GherkinCompatibilityMode::GHERKIN_32`` - match the official parsers. This will become the default in Behat 4.0. - -.. caution:: - ``GherkinCompatibilityMode::GHERKIN_32`` is currently considered experimental. We expect that - there will be more changes to how the parser behaves in this mode before we mark it as stable. + but is not recommended for new projects. +* ``GherkinCompatibilityMode::GHERKIN_32`` - match the official parsers version >= 32.0 < 42.0 +* ``GherkinCompatibilityMode::GHERKIN_42`` - match the official parsers version >= 42.0. This is + the default in Behat 4.x. Configuring the parser mode --------------------------- @@ -159,6 +158,27 @@ In ``GHERKIN_32`` mode, if one of the elements listed above has multi-line text, left padding / indentation as the feature file. In legacy mode, we attempted to left-trim all lines to match the indentation of the keyword. +Rules +~~~~~ + +The Gherkin `Rule` keyword is not supported in ``LEGACY`` mode. Rule nodes will either be parsed as part of the feature +description, or cause a ParserException, depending on the nodes that come before them in the file. + +``GHERKIN_32`` mode introduces backwards-compatible support for Rules. Scenarios within Rules will be parsed, filtered, +and executed as expected with any caller. However, callers that have not been updated to support this feature will +receive a modified node tree with all Rule details stripped out. This will behave as though any Scenarios were a direct +child of the Feature - with any Rule Background steps repeated as the first steps of each Scenario. + +Steps with a DataTable **and** a DocString +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Historically, a step could only accept **either** a DataTable **or** a DocString. ``StepNode::getArguments()`` has +always been typed as returning an array but in practice could only return 0 or 1 elements. Therefore in ``LEGACY`` +and``GHERKIN_32`` mode, we throw a ParserException if a step has more than one multiline argument. + +In ``GHERKIN_42`` mode, a step with a DataTable **and** a DocString is valid. ``StepNode::getArguments()` will +return both nodes, in the order they appeared in the feature file. It is still not valid to have more than one +argument of any given type (e.g. two tables) - in this case we still throw a ParserException. .. _`behat/gherkin`: http://martinfowler.com/bliki/BusinessReadableDSL.html .. _`the official parsers provided by the Cucumber project`: https://github.com/cucumber/gherkin From 1358e8454d2ea70931ac0cbb77a2944fdd92e211 Mon Sep 17 00:00:00 2001 From: Andrew Coulton Date: Fri, 25 Sep 2026 22:39:54 +0100 Subject: [PATCH 2/3] fix RST syntax typos --- user_guide/gherkin/parser_mode.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/user_guide/gherkin/parser_mode.rst b/user_guide/gherkin/parser_mode.rst index 1dbb1d9..83a58d6 100644 --- a/user_guide/gherkin/parser_mode.rst +++ b/user_guide/gherkin/parser_mode.rst @@ -161,7 +161,7 @@ In ``GHERKIN_32`` mode, if one of the elements listed above has multi-line text, Rules ~~~~~ -The Gherkin `Rule` keyword is not supported in ``LEGACY`` mode. Rule nodes will either be parsed as part of the feature +The Gherkin ``Rule`` keyword is not supported in ``LEGACY`` mode. Rule nodes will either be parsed as part of the feature description, or cause a ParserException, depending on the nodes that come before them in the file. ``GHERKIN_32`` mode introduces backwards-compatible support for Rules. Scenarios within Rules will be parsed, filtered, @@ -174,9 +174,9 @@ Steps with a DataTable **and** a DocString Historically, a step could only accept **either** a DataTable **or** a DocString. ``StepNode::getArguments()`` has always been typed as returning an array but in practice could only return 0 or 1 elements. Therefore in ``LEGACY`` -and``GHERKIN_32`` mode, we throw a ParserException if a step has more than one multiline argument. +and ``GHERKIN_32`` mode, we throw a ParserException if a step has more than one multiline argument. -In ``GHERKIN_42`` mode, a step with a DataTable **and** a DocString is valid. ``StepNode::getArguments()` will +In ``GHERKIN_42`` mode, a step with a DataTable **and** a DocString is valid. ``StepNode::getArguments()`` will return both nodes, in the order they appeared in the feature file. It is still not valid to have more than one argument of any given type (e.g. two tables) - in this case we still throw a ParserException. From b0e642961872322be45e2fc09d05239b1316cce7 Mon Sep 17 00:00:00 2001 From: Andrew Coulton Date: Fri, 25 Sep 2026 22:40:46 +0100 Subject: [PATCH 3/3] fix line length --- user_guide/gherkin/parser_mode.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide/gherkin/parser_mode.rst b/user_guide/gherkin/parser_mode.rst index 83a58d6..2076bd4 100644 --- a/user_guide/gherkin/parser_mode.rst +++ b/user_guide/gherkin/parser_mode.rst @@ -161,8 +161,8 @@ In ``GHERKIN_32`` mode, if one of the elements listed above has multi-line text, Rules ~~~~~ -The Gherkin ``Rule`` keyword is not supported in ``LEGACY`` mode. Rule nodes will either be parsed as part of the feature -description, or cause a ParserException, depending on the nodes that come before them in the file. +The Gherkin ``Rule`` keyword is not supported in ``LEGACY`` mode. Rule nodes will either be parsed as part of the +feature description, or cause a ParserException, depending on the nodes that come before them in the file. ``GHERKIN_32`` mode introduces backwards-compatible support for Rules. Scenarios within Rules will be parsed, filtered, and executed as expected with any caller. However, callers that have not been updated to support this feature will