Getting started with cucumber

Remarks#

About Cucumber

Cucumber is a tool which runs executable specifications of software. Specifications, called “features”, are written in structured natural language. Cucumber executes a feature by mapping each of its steps to a “step definition” written in the programming language supported by that implementation of Cucumber. Cucumber is implemented in many programming languages including Ruby (the original), Java and Javascript. It is also translated into many human languages.

Cucumber was written to support the agile methodology called Behavior-Driven Development (BDD). In BDD, one begins development outside-in by writing acceptance tests which describe the software’s functionality from the user’s point of view (rather than from a programmer’s point of view such as in unit tests). Cucumber features serve as these acceptance tests.

In general, Cucumber features are human-readable documentation which is also an executable test suite, meaning that documentation and tests always agree. Cucumber is useful in communicating with non-programmer stakeholders about documentation and tests. It also allows programmers to write tests at a conceptual level without irrelevant programming-language concerns.

Cucumber is most often used to specify and test web applications, using a browser driver such as Selenium or PhantomJS. However, it can be used with any software that can be executed and whose state or results can be determined from the programming language that a Cucumber implementation supports.

Other documentation

Official documentation is at https://cucumber.io/docs. Documentation generated from the Cucumber features which describe Cucumber implementations is at

• JavaScript: https://relishapp.com/cucumber/cucumber-js/docs
• Ruby: https://relishapp.com/cucumber/cucumber/docs

https://relishapp.com/explore includes some other Cucumber-related tools and examples, although not, unfortunately, Cucumber-JVM.

This topic

This topic should only give a few examples which introduce the reader to Cucumber concepts. Other sections will give complete examples of installation, command-line and IDE usage, features, step definitions, etc.

A Cucumber feature

Cucumber uses Gherkin syntax to describe your software’s behaviors in structured natural language.

As such Cucumber is not a test framework (a common misunderstanding), but a system documentation framework, not very different from others like Use Case Scenario. The common misunderstanding is due to the fact Cucumber documentation can be automated in order to ensure it reflects the real system behavior.

A Cucumber documentation suite is composed of Features, each describing a feature of your software, written in Gherkin and hosted in its own file. By organizing those files into a directory structure you can group and organize features:

• banking/
  • withdrawal.feature
  • atm.feature
  • personal-loan.feature
• trading/
  • portfolio.feature
  • intraday.feature
• mortgage/
  • evaluation.feature
  • accounting.feature

Each Feature is a plain text file composed by an optional, unstructured, purely informational introductory section and one or more Scenarios, each one representing a usage condition or use case.

Example:

Feature: Documentation
As a StackOverflow user or visitor
I want to access the documentation section
    
    Scenario: search documentation on Stack Overflow
        Given I am on StackOverflow
        And I go to the Documentation section
        When I search for "cucumber"
        And I follow the link to "cucumber"
        Then I should see documentation for "cucumber"

Each line beginning with Given, When, And, But or Then is called a Step. Any step can begin with any of those words regardless of order, but it is conventional to use them in the most natural way possible.

Features can also be organized via Tags, annotations the editor can put on a Feature or a Scenario to further categorize it.

Executability of a Feature is achieved via glue code which can be written in many different languages (Java, Ruby, Scala, C/C++): each Step is matched against the glue code in order to identify Step Definitions (commonly abbreviated to StepDef) via regular expressions.

Every Step can have only one associated Step Definition.

When a Feature is executed each composing Scenario is executed, meaning each StepDef matching the Steps in every Scenario gets executed.

Pure Ruby Installation

To install Cucumber for use with Ruby simply use the command

gem install cucumber

Alternatively, if you are using bundler, you can add the following line to your Gemfile

gem 'cucumber'

And then run bundler

bundle install

[I think this belongs in its own topic, Installation. I created that topic and copied this example there. When that topic is approved I’ll move this there and delete the copy.]

A Cucumber step definition in Ruby

In features/step_definitions/documentation.rb:

When /^I go to the "([^"]+)" documentation$/ do |section|
  path_part =
    case section
      when "Documentation"
        "documentation"
      else
        raise "Unknown documentation section: #{section}"
    end
  visit "/documentation/#{path_part}/topics"
end

Then /^I should see the "([^"]+) documentation"$/ do |section|
  expect(page).to have_css('h2.doctag_title a', text: section)
end

These steps exercise a web application. They are about as simple as they can be while still being practical.

Each step begins with a Gherkin keyword, which in a step definition file is a method which registers a step with Cucumber. The step-defining method takes a regular expression, which matches a line in a scenario, and a block, which is executed when the scenario gets to a matching line. Capture groups in the regular expression are passed to the block as block parameters.

The When step has a simple, in-line example of going from a human-readable reference to a page (“Documentation”) to a URL. Real Cucumber suites usually put this logic in a separate method. The visit method is provided by Capybara. Capybara is not required to use Cucumber, although it is very commonly used with it. visit tells the browser controlled by Capybara to visit the given URL.

The Then step shows how the content of a page can be tested. expect/to is provided by RSpec (again, not required by Cucumber but very commonly used with it). have_css is provided by Capybara. The expectation is that the given CSS selector matches an element on the page which contains the given text. Note that this expectation would fail if the browser request had failed.

For more examples, see the “Step definition” topic.