Cucumber Reference

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 πŸ”—︎

Steps πŸ”—︎

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:

Success πŸ”—︎

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.

Undefined πŸ”—︎

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.

Pending πŸ”—︎

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.

Skipped πŸ”—︎

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.

Ambiguous πŸ”—︎

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 πŸ”—︎

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 πŸ”—︎

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 πŸ”—︎

After hooks run after the last step of each scenario, even when steps are 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.

After do |s|
  # Tell Cucumber to quit after this scenario is done - if it failed.
  Cucumber.wants_to_quit = true if s.failed?

Around πŸ”—︎

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

Step hooks πŸ”—︎

BeforeStep πŸ”—︎

AfterStep πŸ”—︎

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 πŸ”—︎

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

Tags πŸ”—︎

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 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:

Ignoring a subset of scenarios πŸ”—︎

You can tell Cucumber to ignore scenarios with a particular tag:

Using JUnit runner class:

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 simply 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 πŸ”—︎

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.

JUnit πŸ”—︎

Options πŸ”—︎

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.