Why do Cucumber Expressions offer optional text like hour(s) and alternation like logs/records?

middlenice to knowfreq 30%

answer

one pattern, several natural wordings
parentheses here, slash there
neither one captures anything
in a regex that group costs an argument

basics

~20 s

Parentheses make text optional and a slash alternates the words around it, so one Cucumber Expression covers several wordings. The same parentheses in a regular expression would be a capture group demanding another method argument; in an expression they capture nothing.

solid answer

~40 s

They let one pattern absorb wording variation without reaching for a regex. Optional text is parenthesised: hour(s) matches hour and hours. Alternation is a slash between the words either side of it: logs/records matches either verb. Both can appear in one pattern — the planner logs/records {int} downtime hour(s) for turbine {word} binds to four wordings — and neither captures anything, so the method signature is unchanged. That is the reason they exist rather than a regex group: in a regular expression step definition every capture group becomes a method argument, so writing (s) there silently demands another parameter. The cost is reach: every alternation multiplies the sentences one definition claims, and two definitions claiming one line is reported as an ambiguous step.

They let one pattern absorb wording variation without reaching for a regex. Optional text is parenthesised: `hour(s)` matches `hour` and `hours`. Alternation is a slash between the words either side of it: `logs/records` matches either verb. Both can appear in one pattern — `the planner logs/records {int} downtime hour(s) for turbine {word}` binds to four wordings — and **neither captures anything**, so the method signature is unchanged. That is the reason they exist rather than a regex group: in a regular expression step definition every capture group becomes a method argument, so writing `(s)` there silently demands another parameter. The cost is reach: every alternation multiplies the sentences one definition claims, and two definitions claiming one line is reported as an ambiguous step.

code

java · 4 lines

java

@When("the planner logs/records {int} downtime hour(s) for turbine {word}")
public void logDowntime(int hours, String turbineId) {
    plan.recordDowntime(turbineId, hours);
}

go deeper

for a junior

Recognise the two marks when you read a step definition: parentheses mean that text is optional, a slash means either word will do. Neither one is a placeholder.

for a middle

Explain that both capture nothing, that alternation is bounded by whitespace, and that the same parentheses in a regular expression would be a capture group demanding an extra method parameter.

for a senior

Weigh the reach: each alternation multiplies the sentences a definition claims, and on a suite several teams edit that is a route to ambiguous steps. Know when to fix the Gherkin instead.

for a principal

Set the norm for how much wording variation the glue layer absorbs versus how much the feature files are expected to standardise, and make that reviewable rather than a matter of taste.

The two wording features

A Cucumber Expression is the readable pattern language a step definition can be written in, and it carries two features that exist purely so one pattern can absorb the small wording differences real scenarios contain.

Optional text is text in parentheses: hour(s) matches both hour and hours. The parenthesised characters may be present or absent, and nothing is captured either way — the method signature is untouched.

Alternation is a forward slash between alternatives: logs/records matches either word. The alternation binds to the whitespace-delimited words on each side of the slash, so it swaps a word (or an adjacent run of characters), not an arbitrary phrase. Again, nothing is captured.

Both can appear in the same pattern, and both can sit beside placeholders:

gherkin

When the planner logs 6 downtime hours for turbine T-142
When the planner records 1 downtime hour for turbine T-142

Both of those lines bind to the single expression the planner logs/records {int} downtime hour(s) for turbine {word}.

Why not just use a regex group

Because in a regular expression step definition, a group is not free. Every capture group supplies one argument to the step-definition method, in order. So the regex "equivalent" of the two features is not the obvious one:

Wording need	Cucumber Expression	Regular expression
Optional plural	`hour(s)`	`hours?` or a non-capturing group
Either of two verbs	`logs/records`	a non-capturing group with an alternation inside
Naive attempt	—	`(s)` — a capture group, so the method now needs another parameter

That last row is the whole point. Writing (s) in a regex adds a capture group, and the method must grow a parameter to receive it or the definition is wired wrongly. Writing (s) in a Cucumber Expression makes the letter optional and changes nothing else. The expression syntax gives the two things people actually reach for — an optional suffix and a choice of verb — without dragging the capturing machinery in behind them.

The rules that catch people out

Optional text and alternation capture nothing. They never add a method argument, and you cannot find out from inside the step body which wording was used. If the difference in wording carries a difference in meaning, it belongs in a placeholder, not in an alternation.
Alternation is bounded by whitespace. It swaps the words either side of the slash; it is not a general "either this phrase or that phrase" construct.
Reserved characters need escaping. Because (, / and { have meaning in the syntax, a step whose text genuinely contains one of them must escape it with a backslash, or the pattern will not mean what it reads like.
Neither feature is a matching relaxation. Everything outside the optional or alternated part still has to be present in the step line, exactly.
They compose. One pattern may carry several of each alongside placeholders, which is convenient and is also how a pattern's reach grows faster than its author expects.

When they turn into a liability

On a 63-scenario wind-farm maintenance planner feature set that two teams both edit, these features are also how a step definition quietly grows a wider net than its author intended:

Each alternation multiplies the sentences one definition claims. A pattern with three alternations covers eight wordings, and one of those eight may be a sentence the other team wrote a definition for.
When two definitions both match a line, the run reports the step as ambiguous and stops — a good outcome, because the alternative is silently running the wrong glue.
Alternation used to paper over inconsistent phrasing hides a Gherkin problem. If half the scenarios say logs and half say records, the cheaper fix is usually to agree on one verb in the feature files rather than to teach every step definition both.

The healthy use is narrow: pluralisation, an article, a tense the language forces on you. The unhealthy use is a definition trying to be the one pattern that matches everything anybody might write, which is how a shared suite ends up with ambiguous steps that neither team can explain.

A useful review question, then, is not "does this pattern work?" but "how many sentences does this pattern now claim?". Count the alternations, double for each one, and check that none of the resulting wordings belongs to somebody else's definition. That is a thirty-second check, and it is much cheaper than diagnosing an ambiguous step weeks later in a suite nobody remembers writing.

## The two wording features A **Cucumber Expression** is the readable pattern language a step definition can be written in, and it carries two features that exist purely so one pattern can absorb the small wording differences real scenarios contain. **Optional text** is text in parentheses: `hour(s)` matches both `hour` and `hours`. The parenthesised characters may be present or absent, and nothing is captured either way — the method signature is untouched. **Alternation** is a forward slash between alternatives: `logs/records` matches either word. The alternation binds to the whitespace-delimited words on each side of the slash, so it swaps a word (or an adjacent run of characters), not an arbitrary phrase. Again, nothing is captured. Both can appear in the same pattern, and both can sit beside placeholders: ```gherkin When the planner logs 6 downtime hours for turbine T-142 When the planner records 1 downtime hour for turbine T-142 ``` Both of those lines bind to the single expression `the planner logs/records {int} downtime hour(s) for turbine {word}`. ## Why not just use a regex group Because in a **regular expression** step definition, a group is not free. Every capture group supplies one argument to the step-definition method, in order. So the regex "equivalent" of the two features is not the obvious one: | Wording need | Cucumber Expression | Regular expression | |---|---|---| | Optional plural | `hour(s)` | `hours?` or a non-capturing group | | Either of two verbs | `logs/records` | a non-capturing group with an alternation inside | | Naive attempt | — | `(s)` — a capture group, so the method now needs another parameter | That last row is the whole point. Writing `(s)` in a regex adds a capture group, and the method must grow a parameter to receive it or the definition is wired wrongly. Writing `(s)` in a Cucumber Expression makes the letter optional and changes nothing else. The expression syntax gives the two things people actually reach for — an optional suffix and a choice of verb — without dragging the capturing machinery in behind them. ## The rules that catch people out - **Optional text and alternation capture nothing.** They never add a method argument, and you cannot find out from inside the step body which wording was used. If the difference in wording carries a difference in meaning, it belongs in a placeholder, not in an alternation. - **Alternation is bounded by whitespace.** It swaps the words either side of the slash; it is not a general "either this phrase or that phrase" construct. - **Reserved characters need escaping.** Because `(`, `/` and `{` have meaning in the syntax, a step whose text genuinely contains one of them must escape it with a backslash, or the pattern will not mean what it reads like. - **Neither feature is a matching relaxation.** Everything outside the optional or alternated part still has to be present in the step line, exactly. - **They compose.** One pattern may carry several of each alongside placeholders, which is convenient and is also how a pattern's reach grows faster than its author expects. ## When they turn into a liability On a 63-scenario wind-farm maintenance planner feature set that two teams both edit, these features are also how a step definition quietly grows a wider net than its author intended: 1. Each alternation multiplies the sentences one definition claims. A pattern with three alternations covers eight wordings, and one of those eight may be a sentence the other team wrote a definition for. 2. When two definitions both match a line, the run reports the step as **ambiguous** and stops — a good outcome, because the alternative is silently running the wrong glue. 3. Alternation used to paper over inconsistent phrasing hides a Gherkin problem. If half the scenarios say `logs` and half say `records`, the cheaper fix is usually to agree on one verb in the feature files rather than to teach every step definition both. The healthy use is narrow: pluralisation, an article, a tense the language forces on you. The unhealthy use is a definition trying to be the one pattern that matches everything anybody might write, which is how a shared suite ends up with ambiguous steps that neither team can explain. A useful review question, then, is not "does this pattern work?" but "how many sentences does this pattern now claim?". Count the alternations, double for each one, and check that none of the resulting wordings belongs to somebody else's definition. That is a thirty-second check, and it is much cheaper than diagnosing an ambiguous step weeks later in a suite nobody remembers writing.

Can the step body find out which alternative the scenario actually used?
No. Optional text and alternation capture nothing, so the method receives the same arguments either way. If the difference in wording carries a difference in behaviour, it must be a placeholder — a parameter type that captures the varying word — or two separate step definitions. Using alternation to hide a real behavioural difference is how a step definition ends up branching on state it was never given.
When would you fix the feature files rather than add an alternation?
When the variation is accidental. If half the scenarios say `logs` and half say `records` for the same act, the cheaper fix is to agree on one verb in the Gherkin, because every alternation widens the set of sentences a definition claims and moves the suite closer to ambiguous matches. Reserve alternation for variation the language forces on you, such as a plural or an article.

saying these in an interview costs you the question

Thinks optional text passes the optional characters as an argument
Believes alternation can swap whole phrases across whitespace
Says parentheses behave identically in an expression and a regex
Uses alternation to paper over inconsistent Gherkin phrasing
Assumes a wider pattern is always safer than a narrow one

Why do Cucumber Expressions offer optional text like hour(s) and alternation like logs/records?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

The two wording features

Why not just use a regex group

The rules that catch people out

When they turn into a liability

▾common follow-ups2 questions

▾red flags5 flags

The two wording features

Why not just use a regex group

The rules that catch people out

When they turn into a liability

answer

go deeper