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

Step Arguments

In the example given in step definitions, 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

Data tables from Gherkin can be accessed by using the DataTable object as the last parameter in a step definition. This conversion can be done either by Cucumber or manually.

List<List<String>> table
List<Map<String, String>> table
Map<String, String> table
Map<String, List<String>> table
Map<String, Map<String, String>> table

The simplest way to pass a to a step definition is to use a data table:

Given the following animals:
  | cow   |
  | horse |
  | sheep |

Declare the argument as a , but don’t define any s in the expression:

In this case, the DataTable is automatically flattened to a by Cucumber (using DataTable.asList(String.class)) before invoking the step definition.


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 s 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 s and variables from the Regexp as arguments to the .

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.


When a step definition’s invokes the pending , the step is marked as pending (yellow, as with undefined ones), indicating that you have work to do.

Failed Steps

When a step definition’s 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 skipped (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 conditional 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 the step result is failed, undefined, pending, or skipped.

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

For example, you can take a screenshot with for failed scenarios and embed them in Cucumber’s report.

See the browser automation page for an example on how to do so.


Step hooks



Conditional 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

Global hooks will run once before any scenario is run or after all scenario have been run.


BeforeAll run before any scenario is run.


AfterAll run after all scenarios have been executed.



AfterConfiguration has been deprecated in favor of BeforeAll and InstallPlugin depending on your needs.


Tags are a great way to organise your features and scenarios.

They can be used for two purposes:

Consider the following example:

Feature: Verify billing

  Scenario: Missing product description
    Given hello

  Scenario: Several products
    Given hello

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

@billing @bicker @annoy
Feature: Verify billing

Tags can be placed above the following Gherkin elements:

  • Feature
  • Scenario
  • Scenario Outline
  • Examples

In Scenario Outline, you can use tags on different example like below:

Scenario Outline: Steps will run conditionally if tagged
  Given user is logged in
  When user clicks <link>
  Then user will be logged out

    | link                  |
    | logout link on mobile |

    | link                   |
    | logout link on desktop |

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:

Ignoring a subset of scenarios

You can tell Cucumber to ignore 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.

Tag expressions

A tag expression is an infix boolean expression. Below are some examples:

Expression Description
@fast Scenarios tagged with @fast
@wip and not @slow Scenarios tagged with @wip that aren’t also tagged with @slow
@smoke and @fast Scenarios tagged with both @smoke and @fast
@gui or @database Scenarios tagged with either @gui or @database

For even more advanced tag expressions you can use parenthesis for clarity, or to change operator precedence:

(@smoke or @ui) and (not @slow)

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

It is possible to configure how Cucumber should run features.

From the command line

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

JUnit 5

JUnit 4


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.