Cucumber Reference

Cucumber can be used to implement automated tests based on scenarios described in your Gherkin feature files.

Step Arguments

In the example above Cucumber extracts the text 48 from the step, converts it to an int and passes it as an argument to the .

The number of parameters in the has to match the number of s in the expression. (If there is a mismatch, Cucumber will throw an error).

Data Tables


A step is analogous to a method call or function invocation.

For example:

Given I have 93 cucumbers in my belly

In this step, you’re “calling” the above step definition with one argument: the value 93.

Steps are declared in your files.

Matching steps

  1. Cucumber matches a step against a step definition’s Regexp
  2. Cucumber gathers any capture groups or variables
  3. Cucumber passes them to the step definition’s and executes it

Recall that step definitions start with a preposition or an adverb (Given, When, Then, And, But).

All step definitions are loaded (and defined) before Cucumber starts to execute the plain text in the feature file.

Once execution begins, for each step, Cucumber will look for a registered step definition with a matching Regexp. If it finds one, it will execute it, passing all capture groups and variables from the Regexp as arguments to the method or function.

The specific preposition/adverb used has no significance when Cucumber is registering or looking up step definitions.

Also, check out multiline step arguments for more info on how to pass entire tables or bigger strings to your step definitions.

Step Results

Each step can have one of the following results:


When Cucumber finds a matching step definition it will execute it. If the block in the step definition doesn’t raise an error, the step is marked as successful (green). Anything you return from a step definition has no significance whatsoever.


When Cucumber can’t find a matching step definition, the step gets marked as undefined (yellow), and all subsequent steps in the scenario are skipped. If you use --strict, this will cause Cucumber to exit with 1.


When a step definition’s method or function invokes the pending method, the step is marked as pending (yellow, as with undefined ones), indicating that you have work to do. If you use --strict, this will cause Cucumber to exit with 1.

Failed Steps

When a step definition’s method or function is executed and raises an error, the step is marked as failed (red). What you return from a step definition has no significance whatsoever.

Returning or false will not cause a step definition to fail.


Steps that follow undefined, pending, or failed steps are never executed, even if there is a matching step definition. These steps are marked as cyan.


Step definitions have to be unique for Cucumber to know what to execute. If you use ambiguous step definitions, telling you to fix the ambiguity.


Hooks are blocks of code that can run at various points in the Cucumber execution cycle. They are typically used for setup and teardown of the environment before and after each scenario.

Where a hook is defined has no impact on what scenarios or steps it is run for. If you want more fine-grained control, you can use tagged hooks.

Scenario hooks

Scenario hooks run for every scenario.


Before hooks run before the first step of each scenario.

Think twice before you use Before

Whatever happens in a Before hook is invisible to people who only read the features. You should consider using a background as a more explicit alternative, especially if the setup should be readable by non-technical people. Only use a Before hook for low-level logic such as starting a browser or deleting data from a database.


After hooks run after the last step of each scenario, even when steps are failed, undefined, pending, or skipped.

The scenario parameter is optional, but if you use it, you can inspect the status of the scenario.

if (scenario.isFailed()) {
    byte[] screenshot = webDriver.getScreenshotAs(OutputType.BYTES);
    scenario.embed(screenshot, "image/png");
TODO: See Ruby or Java example
# Available scenario methods: #failed?, #passed?, and #exception
if scenario.failed?
  path = "html-report/#{scenario.__id__}.html"
  embed(path, "image/png")
After do |s|
  # Tell Cucumber to quit after this scenario is done - if it failed.
  Cucumber.wants_to_quit = true if s.failed?


Around('@fast') do |scenario, block|
  Timeout.timeout(0.5) do

Step hooks



Tagged hooks

Hooks can be conditionally selected for execution based on the tags of the scenario. To run a particular hook only for certain scenarios, you can associate a Hook with a tag expression.

See more documentation on tags.

Global Hooks

my_heavy_object =

at_exit do

Running a hook only once


AfterConfiguration do |config|
  puts "Features dwell in #{config.feature_dirs}"


Tags are a great way to organise your features and scenarios. Consider this example:

Feature: Verify billing

  Scenario: Missing product description
    Given hello

  Scenario: Several products
    Given hello

A feature or scenario or can have as many tags as you like. Just separate them with spaces:

@billing @bicker @annoy
Feature: Verify billing

Tags can be placed above the following Gherkin elements:

  • Feature
  • Scenario
  • Scenario Outline
  • Examples

It is not possible to place tags above Background or steps (Given, When, Then, And and But).

Tag Inheritance

Tags are inherited by child elements.

Tags that are placed above a Feature will be inherited by Scenario, Scenario Outline, or Examples.

Tags that are placed above a Scenario Outline will be inherited by Examples.

Running a subset of scenarios

You can tell Cucumber to only run scenarios with a particular tag:

Filtering by line

Another way to run a subset of scenarios is to use the file.feature:line pattern or the --scenario option.

Using tags for documentation

Your imagination is the only limitation when it comes to using tags for documentation.

Tags can refer to IDs in external systems such as requirement management tools, issue trackers or test management tools:

@BJ-x98.77 @BJ-z12.33
Feature: Convert transaction

You can use a custom Cucumber reporting plugin that will turn tags into links pointing to documents in your external tool.

Development Process

Another creative way to use tags is to keep track of where in the development process a certain feature is:

Feature: Index projects

Running Cucumber

Cucumber is a It is launched by running

It is possible to configure how Cucumber should run features.

From the command line

The most common option is to run Cucumber from the command line.

By default, Cucumber will treat anything ending in under the root directory as a step definition file.

Thus, a step contained in can be used in a feature file contained in , provided that:

  • Cucumber is invoked on a root directory common to both (./features, in this example); OR
  • explicitly required on the command line

You can also run features using a build tool or an IDE.



Cucumber provides several options that can be passed to on the command-line.

List configuration options

You can list the options available for the Cucumber version you are using.

You can also use tags to specify what to run.

You can help us improve this documentation. Edit this page.