Cucumber uses expressions to link a Gherkin Step to a Step Definition. You can use Regular Expressions or Cucumber Expressions.

Cucumber Expressions offer similar functionality to Regular Expressions, with a syntax that is more human to read and write. Cucumber Expressions are also extensible with parameter types.

By default, Cucumber will assume you are using Cucumber Expressions. To use Regular Expressions, add anchors (starting with ^ and ending with $) or forward slashes (/). For more information, see Cucumber Expression - Java Heuristics.

Introduction

Let's write a Cucumber Expression that matches the following Gherkin step (the Given keyword has been removed here, as it's not part of the match).

I have 42 cucumbers in my belly

The simplest Cucumber Expression that matches that text would be the text itself, but we can also write a more generic expression, with an int output parameter:

I have {int} cucumbers in my belly

When the text is matched against that expression, the number 42 is extracted from the {int} output parameter and passed as an argument to the step definition.

The following text would not match the expression:

I have 42.5 cucumbers in my belly

This is because 42.5 has a decimal part, and doesn't fit into an int. Let's change the output parameter to float instead:

I have {float} cucumbers in my belly

Now the expression will match the text, and the float 42.5 is extracted.

Parameter types

Text between curly braces reference a parameter type. Cucumber comes with the following built-in parameter types:

Custom Parameter types

Cucumber Expressions can be extended so they automatically convert output parameters to your own types. Consider this Cucumber Expression:

I have a {color} ball

If we want the {color} output parameter to be converted to a Color object, we can define a custom parameter type in Cucumber's configuration.

@ParameterType("red|blue|yellow")  // regexp
public Color color(String color){  // type, name (from method)
    return new Color(color);       // transformer function
}

@ParameterType("red|blue|yellow")   // regexp
fun color(color: String): Color {   // name (from method), type
    return Color(color)             // transformer function
}                                    

ParameterType("color", "red|blue|yellow") { color: String => // name, regexp
    Color(color)                                             // transformer function, type
}                                    

const { defineParameterType } = require('cucumber')

defineParameterType({ 
    name: 'color',
    regexp: /red|blue|yellow/,
    transformer: s => new Color(s)
})

ParameterType(
  name:        'color',
  regexp:      /red|blue|yellow/,
  type:        Color,
  transformer: ->(s) { Color.new(s) }
)

The table below explains the various arguments you can pass when defining a parameter type.

Optional text

It's grammatically incorrect to say 1 cucumbers, so we should make the plural s optional. That can be done by surrounding the optional text with parentheses:

I have {int} cucumber(s) in my belly

That expression would match this text:

I have 1 cucumber in my belly

It would also match this text:

I have 42 cucumbers in my belly

In Regular Expressions, parentheses indicate a capture group, but in Cucumber Expressions they mean optional text.

Alternative text

Sometimes you want to relax your language, to make it flow better. For example:

I have {int} cucumber(s) in my belly/stomach

This would match either of those texts:

I have 42 cucumbers in my belly
I have 42 cucumbers in my stomach

Alternative text only works when there is no whitespace between the alternative parts.

Escaping

If you ever need to match () or {} literally, you can escape the opening ( or { with a backslash:

I have {int} \{what} cucumber(s) in my belly \(amazing!)

This expression would match the following examples:

I have 1 {what} cucumber in my belly (amazing!)
I have 42 {what} cucumbers in my belly (amazing!)

You may have to escape the \ character itself with another \, depending on your programming language. For example, in Java, you have to use escape character \ with another backslash.

I have {int} \\{what} cucumber(s) in my belly \\(amazing!)

Then this expression would match the following example:

I have 1 \{what} cucumber in my belly \(amazing!)
I have 42 \{what} cucumbers in my belly \(amazing!)

There is currently no way to escape a / character - it will always be interpreted as alternative text.