Implement unambiguous keywords

[mattwynne]

As described in cucumber/common#768

[davidjgoss]

Cool, I'm in favour of this proposal.

We have an issue in cucumber-js which is that you can define a step with a generic function called defineStep which is on the public API, and the Given, When, and Then functions are just aliases of that. So at the moment it's kind of ambiguity all the way down, and we'll need to fix that for this to work.

What I'd propose in order to get this to a point where we have an on/off flag for unambiguous keywords is:

1. (ASAP) support: record step keyword, deprecate defineStep #2044
   • Start recording the keyword used to define steps
   • For defineStep, just record it as "Given" in the interim
   • Deprecate defineStep on the public API
2. (whenever)
   • Add the option to fail as ambiguous if the keyword doesn't match between source and step definition
3. (9.0.0 (in a couple months))
   • Remove defineStep from the public API

One thing we should discuss is how the option should be surfaced. We already have strict mode, I would see this as another facet of that but that would be a breaking change since strict mode is on by default. I do believe this is a good default for Cucumber, it's just how best to roll that out.

[charlierudolph]

For 2, I think could have an option --strict-keywords.

If we eventually merge this into strict, I'd think the following would be my eventual ideal (where strict is default for both)

• --no-strict-pending-steps / --strict-pending-steps
• --no-strict-keywords / --strict-keywords

Think it would be better with separate options flags so users can opt out of things they don't care about (but don't opt out of extra behavior they are okay with at the same time)

[davidjgoss]

@mattwynne I think this might be a good candidate for the new contributors ensemble. It's not super heavy in terms of complexity but would touch a lot of different parts of the codebase and give a good mapping of the architecture. What do you think? I'd be happy to draft a feature file so there's somewhere to start.

[iomedico-beyer]

I am against the removal of defineStep from the public API.

Your idea works nicely for the English language, but not for some other. In German, the sentence structure after Dann (German for Then) is different than after Und (German for And). Thus I cannot replace all German And with German Then. It just looks broken. As a workaround, I currently map German And to defineStep.

[iomedico-beyer]

While I still think defineStep should not be removed (see above), I like the idea of these optional two strict validation modes (to fail fast) - even more so since we recently converted all our tests to English. Any idea when this might be implemented?

[davidjgoss]

@iomedico-beyer thanks for highlighting that perspective on the German language.

At this point it looks unlikely we will enforce strict keywords, at least any time soon if ever. So we could keep defineStep and it would just have to throw if called with the strict option on.