In this quick tutorial you will learn how to:

  • Install Cucumber
  • Write your first Scenario using the Gherkin syntax
  • Write your first step definition in
  • Run Cucumber
  • Learn the basic workflow of Behaviour-Driven Development (BDD)

We’ll use Cucumber to develop a small library that can figure out whether it’s Friday yet.

Please be aware that this tutorial assumes that you have a:

  • Some experience using a terminal
  • Some experience using a text editor

Before we begin, you will need the following:

Create an empty Cucumber project

You now have a small project with Cucumber installed.

Verify Cucumber installation

To make sure everything works together correctly, let’s run Cucumber.

You should see something like the following:

Cucumber’s output is telling us that it didn’t find anything to run.

Write a Scenario

When we do Behaviour-Driven Development with Cucumber we use concrete examples to specify what we want the software to do. Scenarios are written before production code. They start their life as an executable specification. As the production code emerges, scenarios take on a role as living documentation and automated tests.

Example Mapping

Try running an Example Mapping workshop in your team to design examples together.

In Cucumber, an example is called a scenario. Scenarios are defined in .feature files, which are stored in the directory (or a subdirectory).

One concrete example would be that Sunday isn’t Friday.

Create an empty file called with the following content:

Feature: Is it Friday yet?
  Everybody wants to know when it's Friday

  Scenario: Sunday isn't Friday
    Given today is Sunday
    When I ask whether it's Friday yet
    Then I should be told "Nope"

The first line of this file starts with the keyword Feature: followed by a name. It’s a good idea to use a name similar to the file name.

The second line is a brief description of the feature. Cucumber does not execute this line because it’s documentation.

The fourth line, Scenario: Sunday is not Friday is a scenario, which is a concrete example illustrating how the software should behave.

The last three lines starting with Given, When and Then are the steps of our scenario. This is what Cucumber will execute.

See scenario reported as undefined

Now that we have a scenario, we can ask Cucumber to execute it.

Cucumber is telling us we have one undefined scenario and three undefined steps. It’s also suggesting some snippets of code that we can use to define these steps:

Copy each of the three snippets for the undefined steps and paste them into .

See scenario reported as pending

Run Cucumber again. This time the output is a little different:

Cucumber found our step definitions and executed them. They are currently marked as pending, which means we need to make them do something useful.

See scenario reported as failing

The next step is to do what the comments in the step definitions is telling us to do:

Write code here that turns the phrase above into concrete actions

Try to use the same words in the code as in the steps.

Ubiquitous Language

If the words in your steps originated from conversations during an Example Mapping session, you’re building a Ubiquitous Language, which we believe is a great way to make your production code and tests more understandable and easier to maintain.

Change your step definition code to this:

Run Cucumber again:

That’s progress! The first two steps are passing, but the last one is failing.

See scenario reported as passing

Let’s do the minimum we need to make the scenario pass. In this case, that means making our return Nope:

Run Cucumber again:

Congratulations! You’ve got your first green Cucumber scenario.

Add another failing test

The next thing to test for would be that we also get the correct result when it is Friday.

Update the is_it_friday_yet.feature file:

Feature: Is it Friday yet?
  Everybody wants to know when it's Friday

  Scenario: Sunday isn't Friday
    Given today is Sunday
    When I ask whether it's Friday yet
    Then I should be told "Nope"

  Scenario: Friday is Friday
    Given today is Friday
    When I ask whether it's Friday yet
    Then I should be told "TGIF"

We’ll need to add a step definition to set today to “Friday”:

When we run this test, it will fail.

That is because we haven’t implemented the logic yet! Let’s do that next.

Make it pass

We should update our statement to actually evaluate whether or not today is equal to "Friday".

Run Cucumber again:

Using variables and examples

So, we all know that there are more days in the week than just Sunday and Friday. Let’s update our scenario to use variables and evaluate more possibilities. We’ll use variables and examples to evaluate Friday, Sunday, and anything else!

Update the is_it_friday_yet.feature file. Notice how we go from Scenario to Scenario Outline when we start using multiple Examples.

Feature: Is it Friday yet?
  Everybody wants to know when it's Friday

  Scenario Outline: Today is or is not Friday
    Given today is "<day>"
    When I ask whether it's Friday yet
    Then I should be told "<answer>"

    | day            | answer |
    | Friday         | TGIF   |
    | Sunday         | Nope   |
    | anything else! | Nope   |

We need to replace the step definitions for today is Sunday and today is Friday with one step definition that takes the value of <day> as a String. Update the file as follows:

Run Cucumber again:


Now that we have working code, we should do some refactoring:

  • We should move the isItFriday out from the test code into production code.

  • We could at some point extract helper methods from our step definition, for we use in several places.


In this brief tutorial you’ve seen how to install Cucumber, how to follow the BDD process to develop a , and how to use that to evaluate multiple scenarios!

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