Syntax

Expressions match the entire input and are case sensitive. Ordinary text and whitespace match literally. Parameters capture arguments; optional groups and structural alternatives do not add arguments themselves.

Parameters

Named parameters also occupy positional slots. Each example shows captured params first as a positional array, then as a named object from values.params. String values are quoted; undefined marks an absent parameter.

Anonymous parameters

Put a type name in curly braces to capture a value by position, for example {int}, {string}, or {word}. See Built-in parameter types for the full list and conversions.

For example, {int} captures an integer:

Use {string} to capture a single- or double-quoted string. The surrounding quotes are removed from the captured value:

Named parameters with type

Add :name before the type in curly braces to give the captured value a name. The value remains available by position too.

For example, :count{int} captures an integer as count:

{
  count: 2
}

Named parameters without type

Untyped :name parameters default to {string} and require single or double quotes in the input. The transformer removes the surrounding quotes and unescapes \" and \'; it leaves other backslashes unchanged. Empty quoted strings are allowed. Quotes written explicitly in the expression are literal: ":page" requires an extra pair of literal quotes around the quoted parameter. There is no automatic number inference.

{
  page: "Settings"
}

Parameter names use ASCII letters, digits, _, and $, and cannot start with a digit. They are case sensitive and must be unique across the entire expression, including mutually exclusive branches. {page} looks up a registered type named page; it never declares a named parameter. Unknown types are errors.

Inline choice parameters

Put slash-separated literals inside curly braces to capture the selected text. No custom type registration is needed. Every branch must be nonempty; wrap the parameter in an optional group to allow absence.

{
  status: "approved"
}

Inline choice parameters can contain whole phrases. Spaces inside each branch are literal and need no escaping.

{
  action: "press and hold"
}

Arbitrary text

Use {} or :name{} to capture arbitrary text, including an empty string, without spanning newlines.

{
  message: "hello there"
}

This syntax is not recommended because matching is greedy and can make capture boundaries ambiguous. For example, I send {} to {} can split at a later to than intended. Prefer a specific parameter type.

Custom parameter types

Register a custom type to match and transform domain-specific values, then use its name in curly braces.

These examples use the Point transformer defined in Custom parameter types.

{
  point: { x: 3, y: -2 }
}

Built-in parameter types

These built-in types define which input is accepted and how it becomes a captured value.

Numeric patterns follow the tested Cucumber built-ins: floating-point types accept uppercase E exponents, but not lowercase e or trailing decimal points. Every built-in also supports the named form, such as :amount{float}.

Optional groups

Parentheses without a slash at their own nesting level make their contents optional.

Optional suffix

Wrap a suffix in parentheses to accept a word with or without that suffix. The optional text does not create a captured parameter.

Without the optional suffix:

With the optional suffix:

Optional text

Wrap text in parentheses to make it optional. Include its leading space inside the group so the space is optional too.

Without the optional text:

{
  page: "Settings"
}

With the optional text:

{
  page: "Settings"
}

Optional text with parameters

An optional group can contain parameters. When the group is absent, those parameters keep their positions and have undefined values.

Without an owner:

{
  item: "document",
  owner: undefined
}

With an owner:

{
  item: "document",
  owner: "Alice"
}

Nested optional text

Nest optional groups to make one phrase depend on another. Here, the workspace phrase can appear only when the owner phrase is present.

{
  item: "document",
  owner: "Alice",
  workspace: "Team"
}

Consecutive optional text

Place optional groups next to each other to allow either, both, or neither. Distinct literal prefixes make it clear which parameter each input value belongs to.

Neither optional group is present:

{
  message: undefined,
  recipient: undefined
}

Only the message is present:

{
  message: "Hello",
  recipient: undefined
}

Only the recipient is present:

{
  message: undefined,
  recipient: "Alice"
}

Both optional groups are present:

{
  message: "Hello",
  recipient: "Alice"
}

Put optional spaces inside the group. I create :item (as :owner) always requires a space after the item, even when the group is absent. Whitespace is never trimmed or normalized.

Absent parameters retain their positional slots and have undefined values and capture positions. Their transformers are not called. In a nested group, the inner text can appear only when its enclosing group appears.

[!CAUTION] Consecutive optionals use native greedy matching and backtracking. For I send( :message)( :recipient), input I send "Alice" fills message. For I send( :message)( :recipient confirmed), input I send "Alice" confirmed fills recipient instead. Distinguishing literal text, such as message and to in the examples, makes the intended assignment clear.

Alternatives

Use / to choose between words or phrases. Structural choices match text without capturing it; choices inside braces return the selected text. Branches are tried in source order, with backtracking when needed. | is ordinary literal text, not an alternative operator.

Single-word alternatives

Separate words with / to accept either spelling without capturing it as a parameter. Outside parentheses, alternatives are bounded by whitespace, parameters, or the expression edges. A space can be escaped to include it in a branch, for example click/tap\ on.

Paying by card:

Paying by cash:

Multi-word alternatives without escaping

Put slash-separated phrases in parentheses to require one of them. The selected phrase is not captured as a parameter. Spaces are literal and need no escaping. Only slashes at the current nesting level separate branches; slashes inside nested groups or braces do not affect the enclosing group.

With the click branch:

With the tap on branch:

With the press and hold branch:

Optional alternative

Include an empty branch anywhere in parenthesized alternatives to allow no text or one of the listed phrases: (/again), (again/), and (again//once more) are valid. An optional group with a single phrase, such as ( again), is shorthand for the equivalent alternative with an empty first branch: (/ again).

With the empty branch (no suffix):

{
  page: "Settings"
}

With the again suffix:

{
  page: "Settings"
}

Repeated empty branches are allowed. (/) and () match empty text without capturing parameters.

Alternatives with parameters

Each choice branch can declare its own parameters. Positional slots follow source order, and parameters in unselected branches remain undefined. Indexes never shift with the chosen branch.

The number branch captures count:

{
  count: 2,
  label: undefined
}

The label branch captures label:

{
  count: undefined,
  label: "two"
}

Escaping

Use a backslash to make special characters literal. Expression-language escapes support \\, \/, \:, \(, \), \{, \}, and whitespace. Other escapes and a trailing backslash are errors. Unmatched closing delimiters are errors too.

An unescaped colon starts a parameter only when followed by a valid name-start character. Colons in 12:30 and https: are already literal; URL slashes still need escaping. Inside braces, colons are literal, and literal parentheses or opening braces must be escaped. Braces cannot be nested.

For escaping expression strings in TypeScript, see Escaping in string literals.