An Introduction to Cucumber: Behaviour-Driven Testing with Ruby and RSpec

Carol Mascarenhas
June 8, 2023

I’m really proud to be part of the Ruby and Ruby on Rails communities, known for their strong testing culture. This culture is driven by our focus on productivity and our dedication to ensure our code has extensive test coverage. It’s great that Ruby’s readability and expressiveness make it easy to write clear and maintainable tests.

Our community has also developed a variety of testing tools and libraries, including popular ones like RSpec, Capybara for browser automation, and FactoryBot for test data generation. Collaboration and community support are at the heart of our success, stimulating knowledge sharing and continuous learning. Together, we ensure the delivery of high-quality code applications.

Now, let’s explore another powerful tool for behaviour-driven testing: Cucumber. In this blog post, we’ll discover what Cucumber is, understand its importance, and learn how to get started with Cucumber using Ruby and RSpec.

What is Cucumber and Why is it Important?

Cucumber is a powerful and useful tool for behaviour-driven development (BDD). BDD is an approach to software development that focuses on describing and understanding how the software should behave from the user’s perspective. It promotes collaboration and communication among different team members like developers, QA engineers, and business analysts.

Using Cucumber, we can create specifications written in plain language. These specifications help everyone involved in the project understand what the software should do, which leads to better communication, fewer misunderstandings, and more effective testing.

These specifications are not just static documents, but live specifications that allow us to automate tests based on them. This ensures that our software meets the expected behaviour and requirements, making Cucumber a great tool for quality assurance and software development teams.

Let’s Begin with Cucumber in Ruby using RSpec:

To begin using Cucumber, we will utilise Ruby as our programming language and RSpec as our test framework. For browser automation, I prefer using Selenium. Although Cucumber can be used with various languages, I’ll demonstrate its power and simplicity when combined with Ruby and RSpec. So, let’s dive straight in!

Installing Cucumber:

To use Cucumber in your Ruby project, you need to include the ‘cucumber’ gem in your Gemfile.

source ''

gem 'rspec'
gem 'selenium-webdriver'
gem 'cucumber'

For Ruby on Rails projects, you should include the ‘cucumber-rails’ gem instead.

group :development, :test do
  gem "rspec-rails"
  gem 'cucumber-rails'
  gem 'selenium-webdriver'
  gem 'database_cleaner'

Run the bundle command to install the gem and its dependencies.

At the root directory of your project, execute the command cucumber --init. This will create a few folders within your project, setting up the necessary structure for Cucumber to function properly.

Writing Feature Files:

Feature files in Cucumber are written in the Gherkin language, which provides a structured format for describing the behaviour of your software. Gherkin uses keywords like Given, When, Then, And, and But to outline the different steps and conditions in your scenarios.

If you want to learn more about the Gherkin language and its syntax, you can find detailed information and examples in the official Cucumber documentation. The documentation provides comprehensive guides, tutorials, and reference materials to help you understand the concepts and best practices of writing Gherkin scenarios.

To get started with Gherkin, let’s see a “toy” real-life example of feature files:

Feature: User Login
  As a user
  I want to log into the system
  So that I can access my account

  Scenario: Successful login
    Given I am on the login page
    When I enter my username and password
    And I click the "Login" button
    Then I should be redirected to the home page
    And I should see a welcome message

The feature files are conventionally placed inside the “features” folder. This folder was automatically created when you initialised your project with Cucumber. These files have the “.feature” extension and can be named according to your preference.

Writing the Step Definitions:

After creating your feature file, the next step is to write the corresponding step definitions in RSpec, which will define the actions and assertions for each step in your feature. Step definitions are Ruby methods that are associated with the steps in your feature file.

To achieve this, we need to create a new Ruby file, for example login_steps.rb, to define your step definitions. In this file, you will use RSpec to specify the actions and assertions for each step.

For example, for the step “Given I am on the login page,” you would write a step definition like this:

Given("I am on the login page") do
  # Selenium WebDriver can be set up and initialized in the "Before" method. 'http://localhost:3000'
  expect(@driver.title).to eq('Login to Mypage')
  expect(@driver.page_source).to include('Log in with your details to continue')

Similarly, you’ll define step definitions for each step in your feature file, implementing the necessary code to satisfy the expected behaviour.

Writing step definitions in RSpec allows you to integrate Cucumber’s behaviour-driven approach with the powerful testing capabilities provided by RSpec, enabling you to create comprehensive and expressive tests for your application.


Cucumber provides a powerful approach to behaviour-driven testing. By writing feature files and implementing step definitions, we can automate tests that reflect business scenarios. Learning more about the Gherkin language and exploring additional references can help us become proficient in writing expressive and effective specifications.

Cucumber, Ruby, and RSpec make a great combination for behaviour-driven testing.

Other References:

Start automating your tests with Cucumber today and unlock the power of behaviour-driven development!