Docs: the substring matching rule is the key mechanic and is not written down

[aslakhellesoy]

explanation/markup-is-yours says the matcher sees exactly what is written, and reference/examples says a paragraph becomes an example when "at least one sentence matches a step". Neither says how a sentence matches a step.

The mechanic is in matcher.js: the compiled Cucumber Expression has its ^/$ anchors stripped and is scanned for as a substring, and every non-overlapping match in the sentence becomes a step.

I only learned this by reading the source, and once I had, four separate behaviours I'd been treating as quirks turned out to be one rule:

• Why an example can read as prose at all. Ben checks out the basket, "ben@example.com" completes the payment, and the process order workflow is done. is three steps in one sentence. This is, to me, the best thing about writing Varar oaths — and I found it by accident. It deserves to be a headline, not an inference.
• Why narrative around a step works. Unable to choose between them, the visitor puts these shares in the basket: matches; the leading clause is just text the matcher skips past.
• Why an ordinary sentence can accidentally become an example. (Narrative prose containing a step becomes an example; nothing reports a paragraph that newly starts matching #120)
• Why a capitalised sentence-opening step silently fails. (A sentence that opens with a capitalised step silently stops matching (and can leave a passing example that asserts less) #118)

Related, and also undocumented as far as I can find: stripLeadingKeyword / keywords-data.js mean 586 Gherkin keywords in many languages are stripped from the front of a sentence. A, An, I, In, No, Do, E, Se and Ma are all in that list. It didn't bite me, but "a sentence beginning with the word No has that word removed before matching" is surprising enough to write down.

Suggestion

A short section in reference/examples — "How a sentence matches" — stating that matching is substring-based, case-sensitive, that multiple non-overlapping steps in one sentence all run in order, and that leading keywords are stripped. Three paragraphs would have saved me a source-reading session and most of #118.

The multi-step-per-sentence point in particular reads like a feature you'd want people to know about: it is the difference between an oath that reads like documentation and one that reads like a list of steps with the keywords filed off.

[aslakhellesoy]

Agreed, and this is going in first — it's the highest value-per-hour of the batch, and it's the mitigation for #118 and #120 that costs nothing.

The section you describe is the right one: matching is substring-based, case-sensitive, and every non-overlapping match in a sentence becomes a step, run in order. You're right that the multi-step-per-sentence behaviour deserves to be a headline rather than something found by accident — it is the difference between an oath that reads like documentation and one that reads like a list of steps with the keywords filed off. That sentence is going in more or less as you wrote it.

One correction: the keyword stripping no longer exists.

stripLeadingKeyword and keywords-data.js were deleted in 80ceb150; there is no src/keywords.ts any more, and nothing strips anything from the front of a sentence before matching today. What you read is a stale packages/core/dist/keywords.js — dist is gitignored, so an old build artifact was sitting in your working copy and outlived its source.

So no, a sentence beginning with No does not have that word removed. Good news, since it's surprising enough that I'd have had to document it. I'll leave the 586-keyword paragraph out of the new section entirely.

(If you have a checkout with that dist in it, git clean -xdf or a rebuild will clear it. Worth knowing generally when reading this repo — dist/ can be arbitrarily old.)

Also going into the same section, from #118: that a step can open a sentence if the expression uses alternation (The/the visitor checks out the basket), which is the answer to the case-sensitivity trap rather than a matcher change.