Open ciaranmcnulty opened 2 years ago
@Naktibalda any comments from a codeception POV?
@Naktibalda any comments from a codeception POV?
This is great idea. Codeception can't migrate to cucumber/gherkin
right away, but it can certainly support it as an optional dependency via this compatibility layer.
Another option for support would be to:
::isAvailable
method returning false, and make everything else a no-opRelease the real implementation as behat/gherkin 5.0 that explicitly requires cucumber/gherkin and PHP 8.1
Is that cleaner? Behat/Codeception could rely on ^4.9 || ^5.0
I think without breaking support for anyone?
I want to redo this on top of cucumber/common#254 when that's merged
This adds a compatibility layer that can be used when
cucumber/gherkin
is also installed, that uses that parser instead and then maps the result back to our 'regular' AST for Behat (and maybe Codeception?) to consume.This means that when parsing edge cases we will conform much more closely with the cucumber core implementations. It also means newer syntax items will be ignored / handled more cleanly rather than triggering odd parsing errors
To avoid bumping the minimum PHP version we support, this does not depend directly on
cucumber/gherkin
; instead there is a staticCucumberGherkinLoader::isAvailable()
method that can be called to see if the CucumberGherkinLoader can be used instead of the regular one, e.g.An alternative option to this would be to merge this into cucumber/gherkin 5.0.0 and let that require cucumber/gherkin (and PHP 8.1), then the version detection can move to Behat - I'm not sure that's warranted yet
Motivation
Moving to the cucumber parser entirely will reduce the maintenance effort on Behat, and unlock newer features we didn't support yet.
That's a big refactor though, and this goes someway towards it by enabling Behat to introduce the cucumber parser partially as an experimental feature (behind a config flag) to detect feature files in the wild that are unparsable, or parsed in unexpected ways.
Compatibility
Mapping notes
The majority of the mapping is simple from one tree to another, aside from a few places where the Behat AST doesn't support a feature:
Scenarios and Scenario Outlines
Cucumber no longer differentiates between these. To retain compatibility we map any Scenarios that have Examples attached as a Scenario Outline
Multi-line scenario/background/outline names
Cucumber sees this as Scenario with
name: 'Something awesome'
anddescription: 'Something amazing'
. For compatibility we map this as a multi-line scenario name (which cucumber does not support but Behat does) sotitle: "Something awesome\nSomething amazing"
Descriptions trimming
Cucumber preserves whitespaces in descriptions, Behat right and left-trims them based on how indented the previous keyword is. This logic is retained to be as like Behat as possible.
Rule support
Cucumber supports scenarios inside tagged Rules:
Because the Behat AST doesn't support Rule, this will be flattened into the same AST as this feature:
This will enable implementations to parse files with Rule, and to use tags from Rule keywords when filtering examples
Known incompatibilities
There will doubtless be incompatibilities in the wild, but most will be around 'odd' Gherkin. The following are known:
Comments at the end of Feature description no longer work
Cucumber has a bug about this so one of the test files has had to be excluded.
Backgrounds inside Rules do not work
There's no sensible way to map Background up into the Feature level and only have it apply to some scenarios, therefore we throw a parser error if it happens.
This syntax is discouraged by Cucumber anyhow