10 Minute Tutorial

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.

Before we begin, you will need the following:

Create an empty Cucumber project

You now have a simple 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 contents:

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, it’s just 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 is a great way to make your production code and test easier to understand and 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 simplest possible thing to make the scenario pass. In this case, that’s simply to make our function return Nope:

Run Cucumber again:

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


In this brief tutorial you’ve seen how to install Cucumber, and how to follow the BDD process to develop a very simple function. The next natural steps would be:

  • Move the function out from the test code into production code (refactoring)
  • Write another scenario - Friday is Friday perhaps?
  • Follow the same process as outlined above, until both scenarios are green

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