1. Project Overview & Quickstart (cucumber/cucumber-ruby) Copy Chapter

File: README.md Copy Chapter

Cucumber

Cucumber is a tool for running automated tests written in plain language. Because they're
written in plain language, they can be read by anyone on your team. Because they can be
read by anyone, you can use them to help improve communication, collaboration and trust on
your team.

This is the Ruby implementation of Cucumber. Cucumber is also available for JavaScript,
Java, and a lot of other languages. You can find a list of implementations here: https://cucumber.io/docs/installation/.

See CONTRIBUTING.md for info on contributing to Cucumber (issues, PRs, etc.).

Everyone interacting in this codebase and issue tracker is expected to follow the
Cucumber code of conduct.

Installation Copy Chapter

Cucumber for Ruby is a Ruby gem. Install it as you would install any gem: add
cucumber to your Gemfile:

gem 'cucumber'

then install it:

$ bundle

or install the gem directly:

$ gem install cucumber

Later in this document, bundler is considered being used so all commands are using
bundle exec. If this is not the case for you, execute cucumber directly, without
bundle exec.

Supported platforms Copy Section

• Ruby 4.0
• Ruby 3.4
• Ruby 3.3
• Ruby 3.2
• TruffleRuby 24.0.0+
• JRuby 10.0+ (with some limitations)

Ruby on Rails Copy Section

Using Ruby on Rails? You can use cucumber-rails to bring Cucumber into your Rails project.

Usage Copy Chapter

Initialization Copy Section

If you need to, initialize your features directory with

$ bundle exec cucumber --init

This will create the following directories and files if they do not exist already:

features
├── step_definitions
└── support
    └── env.rb

Create your specification Copy Section

Create a file named rule.feature in the features directory with:

# features/rule.feature

Feature: Rule Sample

  Rule: This is a rule

    Example: A passing example
      Given this will pass
      When I do an action
      Then some results should be there

    Example: A failing example
      Given this will fail
      When I do an action
      Then some results should be there

Automate your specification Copy Section

And a file named rule_steps.rb in features/step_definitions with:

# features/step_definitions/steps.rb

Given('this will pass') do
  @this_will_pass = true
end

Given('this will fail') do
  @this_will_pass = false
end

When('I do an action') do
  :no_op
end

Then("some results should be there") do
  expect(@this_will_pass).to be true
end

Run Cucumber Copy Section

$ bundle exec cucumber

To execute a single feature file:

$ bundle exec cucumber features/rule.feature

To execute a single example, indicates the line of the name of the example:

$ bundle exec cucumber features/rule.feature:5

To summarize the results on the standard output, and generate a HTML report on disk:

$ bundle exec cucumber --format summary --format html --out report.html

For more command line options

$ bundle exec cucumber --help

You can also find documentation on the command line possibilities in features/docs/cli.

Documentation and support Copy Chapter

• Getting started, writing features, step definitions, and more: https://cucumber.io/docs
• Ruby API Documentation: http://www.rubydoc.info/github/cucumber/cucumber-ruby/
• Community support forum: https://github.com/orgs/cucumber/discussions
• Discord: register for an account

Copyright Copy Chapter

Copyright (c) Cucumber and Contributors. See LICENSE for details.

File: docs/jruby-limitations.md Copy Chapter

Cucumber and JRuby limitations

cucumber can be executed on JRuby (tested with 10.0), although some of the features
are not available on this platform.

Defining steps with native languages Copy Chapter

There are currently three languages (Russian, Ukrainian and Uzbek) for which the step definition
can not be written in native language.

That means, for example, that you can not write the following code:

Допустим('я ввожу число {int}') do |число|
  calc.push(число)
end

Instead, you have to write (NB: both the gherkin term and the block variable(s) are in English):

Given('я ввожу число {int}') do |number|
  calc.push(number)
end

Of course, you can still write your feature files in a native language, for example, the following
feature file can be executed on JRuby:

# language: ru
Функционал: Сложение чисел
  Чтобы не складывать в уме
  Все, у кого с этим туго
  Хотят автоматическое сложение целых чисел

  Сценарий: Сложение двух целых чисел
    Допустим я ввожу число 50
    И затем ввожу число 70
    Если я нажимаю "+"
    То результатом должно быть число 120

In our CI system these languages are tested using the anglicised step definitions

File: docs/vscode-example-launch-configuration.md Copy Chapter

Pre-requisites Copy Chapter

Ruby Extension Copy Section

Install and configure the ruby extension

Use `debase` and `ruby-debug-ide` gems locally Copy Section

Make sure to use a Gemfile.local file with debase and ruby-debug-ide gems.

# Include the regular Gemfile
eval File.read('Gemfile')

group :development do
  gem 'debase', require: false
  gem 'ruby-debug-ide', require: false
end

Execute bundle config set --local gemfile Gemfile.local to use it per default,
then bundle install.

Sample launch.json Copy Chapter

The following launch.json - to be placed in the .vscode folder - allows to use
VSCode debugging features like breakpoints and watches.

/* Detailed source-code truncated for AI context efficiency. */

File: features/docs/writing_support_code/hooks/README.md Copy Chapter

Cucumber Hooks

Cucumber proposes several hooks to let you specify some code to be executed at
different stages of test execution, like before or after the execution of a
scenario.

Hooks are part of your support code.

They are executed in the following order:

• InstallPlugin
• BeforeAll
  • Per scenario:
    • Around
    • Before
      • Per step:
        • AfterStep
    • After
• AfterAll

You can define as many hooks as you want. If you have several hooks of the same
types - for example, several BeforeAll hooks - they will be all executed once.

Multiple hooks of the same type are executed in the order that they were defined.
If you wish to control this order, use manual requires in env.rb - This file is
loaded first - or migrate them all to one hooks.rb file.

Finaly, all hooks can be given a name to improve reporting and help debugging.

Note: Hooks names are only reported when using the message and the html formatters.

InstallPlugin Copy Chapter

InstallPlugin hook is dedicated to using plugins and is meant to
extend Cucumber. For example, it allows to dynamically change the configuration
before the execution of tests or to add some code that could impact the execution itself.

In addition to the configuration, InstallPlugin has access to some of the Cucumber
internals through a RegistryWrapper, defined in
lib/cucumber/glue/registry_wrapper.rb.

InstallPlugin do |configuration, registry|
  # configuration is an instance of Cucumber::Configuration defined in
  # lib/cucumber/configuration.rb
  #
  # registry is an instance of Cucumber::Glue::RegistryWrapper defined in
  # lib/cucumber/glue/registry_wrapper.rb
end

# named hook:

InstallPlugin(name: 'Installation of a plugin') do |configuration, registry|
  # The name is optional
end

You can see an example in the Cucumber Wire plugin.

BeforeAll and AfterAll Copy Chapter

BeforeAll is executed once before the execution of the first scenario. AfterAll
is executed once after the execution of the last scenario.

These two types of hooks have no parameters. Their purpose is to set-up and/or clean-up
your environment not related to Cucumber, like a database or a browser.

BeforeAll do
  # snip
end

AfterAll do
  # snip
end

# Named hooks:

BeforeAll(name: 'Name of the hook') do
  # snip
end

AfterAll(name: 'Name of the hook') do
  # snip
end

Around Copy Chapter

Note: Around is a legacy hook and its usage is discouraged in favor of
Before and After hooks.

Around is a special hook which allows you to have a block syntax. Its original
purpose was to support some databases with only block syntax for transactions.

Around do |scenario, block|
  SomeDatabase::begin_transaction do # this is just for illustration
    block.call
  end
end

# with a name:

Around(name: 'Name of the hook') do |scenario, block|
  # snip
end

Before and After Copy Chapter

Before is executed before each test case. After is executed after each test case.
They both have the test case being executed as a parameter. Within the After hook,
the status of the test case is also available.

Before do |test_case|
  log test_case.name
end

After do |test_case|
  log test_case.failed?
  log test_case.status
end

# With names:

Before(name: 'Name of the hook') do |test_case|
  # snip
end

After(name: 'Name of the hook') do |test_case|
  # snip
end

AfterStep Copy Chapter

AfterStep is executed after each step of a test. If steps are not executed due
to a previous failure, AfterStep won't be executed either.

AfterStep do |result, test_step|
  log test_step.inspect # test_step is a Cucumber::Core::Test::Step
  log result.inspect # result is a Cucumber::Core::Test::Result
end

# with a name:

AfterStep(name: 'Named hook') do |result, test_step|
  # snip
end

File: features/docs/README.md Copy Chapter

Cucumber for Ruby Copy Chapter

Cucumber is a tool for running automated tests written in plain language. Because they're
written in plain language, they can be read by anyone on your team. Because they can be
read by anyone, you can use them to help improve communication, collaboration and trust on
your team.

Code of Conduct Copy Chapter

Everyone interacting in this codebase and issue tracker is expected to follow the Cucumber code of conduct.

Copyright Copy Chapter

Copyright (c) Cucumber Ltd. and Contributors. See LICENSE for details.

2. Official Technical Reference & Guides (cucumber/docs) Copy Chapter

File: README.md Copy Chapter

Cucumber Documentation

🚨 This repository is archived. the Cucumber documentation is now at https://github.com/cucumber/website. 🚨

Contributing Content Copy Chapter

For small edits, the recommended way to contribute is via GitHub.
Each page in the documentation will have an Edit link for this purpose.

Working locally Copy Chapter

For bigger modifications, the recommended workflow is to edit the documentation
locally on your machine, and seeing the results in a web browser.

This involves getting the source code and building the documentation yourself.

Get the source code

git clone https://github.com/cucumber/docs
cd docs

View the site Copy Section

The website is built with several tools that are distributed as a Docker image.

Install Docker if you don't already have
it on your machine.

Build and serve the website:

./docker_shell.sh

Open a browser:

http://localhost:1313

Changes to the contents will be automatically updated in the browser.

Try editing one of the pages under content and see for yourself!

Build the site and check links Copy Section

When you are done editing, build the site and check links:

./docker_shell.sh make clean
./docker_shell.sh make
./docker_shell.sh make htmlproofer

By default, external links are only checked in CI (because it takes a while).
To check external links locally:

CI=true ./docker_shell.sh make htmlproofer

Links that are broken should be removed or replaced, even if they are only
temporarily broken. The reason for this is that broken links negatively affect
search engine rankings.

Modify theme Copy Section

See the theme README

Architecture Copy Chapter

The site is built with Hugo, a fast static site generator.

We have a custom-built theme for the site in themes/cucumber-hugo. This theme
is based on Bulma - a lightweight CSS framework.

The online site is rebuild automatically whenever the git repository receives
new commits, either via a git push, or by modifying contents in the CMS.

The Netlify CMS saves contents straight to GitHub
using the GitHub API.

Continuous Deployment Copy Chapter

GitHub will notify Netlify for every git push thanks to a webhook.

Netlify will then build the site and
deploy it if the build is successful.

The build will check for broken links and other problems. Internal and external links are checked by HTMLProofer.
Occasionally, the build will fail due to external links being unavailable or giving a timeout. When that happens, please check if these external links are available and if so, 'Retry build' on Netlify.

You can discuss the documentation in the Community Discord.

File: content/_todo/step-reuse.md Copy Chapter

source: https://github.com/cucumber/cucumber/wiki/Step-Definitions/ source: https://github.com/cucumber/cucumber/wiki/Hooks/ source: https://github.com/cucumber/cucumber/wiki/Tags/ title: Cucumber Reference Copy Chapter

Reusable step definitions

TODO: Describe how to use output parameters to make step definitions reusable

Reusable helper methods

TODO: Describe how to extract helper methods that can be used from steps

File: content/docs/tools/_index.md Copy Chapter

title: Tools subtitle: Simplify your work with Cucumber power tools weight: 1180 menu: main iconClass: far fa-tools Copy Chapter

File: content/docs/tools/general.md Copy Chapter

title: Tools subtitle: "Editors, IDEs and build tools" weight: 1000 Copy Chapter

Using Cucumber in your project is more manageable with the right tools.

Editors

Most popular text editors support Gherkin syntax highlighting.

Some IDEs also have advanced support for Cucumber, such as running Cucumber
from within the IDE, displaying results, navigating between Gherkin steps and
step definitions and so on.

Atom Copy Chapter

Atom is a text editor for macOS, Windows or Linux.

It offers several packages you can use with Cucumber.

TextMate Copy Chapter

TextMate is a text editor for macOS.
See the Cucumber.tmbundle documentation.

Visual Studio Code Copy Chapter

Visual Studio Code is a code editor for Windows, Linux, or macOS.

You can use it with a Cucumber (Gherkin) plugin.

Nova Copy Chapter

Nova is a text editor for macOS.

See the Cucumber extension for Gherkin language support.

IDEs

• Java IDEs
• Ruby IDEs
• CukeTest is a Gherkin editor and Cucumber.js development tool.
• testjam.io is an online IDE for running and sharing Cucumber.js snippets.

Build Tools

You can run Cucumber using build tools, rather than from the command line.

• Java build tools
• Ruby build tools

File: content/docs/tools/java.md Copy Chapter

title: Java Tools weight: 1100 Copy Chapter

This page describes tools commonly used with Java.

IDEs

IntelliJ IDEA Copy Chapter

• IntelliJ IDEA has the IntelliJ IDEA Cucumber for Java plugin

You can find more information on using Cucumber with IntelliJ IDEA in the IntelliJ IDEA Cucumber help pages

Eclipse Copy Chapter

• Eclipse has the Cucumber Eclipse plugin

Build tools

The most widely used build tools for Java are Maven and Gradle.

Maven Copy Chapter

To run Cucumber with Maven, make sure that:

• Maven is installed
• The environment variable MAVEN_HOME is correctly configured
• The IDE is configured with the latest Maven installation

Clone the cucumber-java-skeleton to get started.

Gradle Copy Chapter

To run Cucumber with Gradle, make sure that:

• Gradle is installed
• The environment variable GRADLE_HOME is correctly configured
• The IDE is configured with the latest Gradle installation

Clone the cucumber-java-skeleton to get started.

File: content/docs/tools/javascript.md Copy Chapter

title: JavaScript Tools weight: 1200 Copy Chapter

This page describes tools commonly used with JavaScript.

Build tools

The most widely used build tools for JavaScript are npm and Yarn.

npm Copy Chapter

To use Cucumber with npm, make sure that:

• npm is installed

Cucumber.js is available as an npm module.

Add cucumber as a development dependency:

# NPM
npm install --save-dev @cucumber/cucumber

Yarn Copy Chapter

To run Cucumber with Yarn, make sure that:

• Yarn is installed

Add cucumber as a development dependency:

# Yarn
yarn add --dev @cucumber/cucumber

File: content/docs/tools/related-tools.md Copy Chapter

title: Related tools subtitle: Third-party tools weight: 1400 Copy Chapter

People have written tools on top of Cucumber. These are the known third-party tools that work together with Cucumber:

File: content/docs/tools/ruby.md Copy Chapter

title: Ruby Tools weight: 1300 Copy Chapter

This page describes tools for a Ruby or Ruby on Rails environment.

IDEs

RubyMine Copy Chapter

RubyMine is a Ruby and Rails IDE.

Build tools

Cucumber can be run in several ways.
Be aware that rake cucumber, cucumber features, and autotest with ENV AUTOFEATURE=true do not necessarily produce
the same results given the same features and step definitions.

Rake Copy Chapter

Running rake cucumber from the command line provides the simplest method to run Cucumber tests.

Using Rake requires a Rakefile with a features task definition. For example:

require 'rubygems'
require 'cucumber'
require 'cucumber/rake/task'

Cucumber::Rake::Task.new(:features) do |t|
  t.cucumber_opts = "--format pretty" # Any valid command line option can go here.
end

This will run all the Features with the pretty formatter.

Note, how we use the cucumber_opts accessor to define our arguments passed to Cucumber.

If you are using Ruby on Rails, this task is defined for you already.

Now you can run Cucumber with Rake:

rake features

The rake script provided with Cucumber performs much of the background magic required to get the test database and requisite
libraries properly loaded.
In fact, an important habit to acquire is to run Cucumber as a rake task immediately after performing a migration.
This ensures that the test database schema is kept in sync with the development database schema.
You can achieve the same effect by running rake db:test:prepare before your first Cucumber run following a migration
but developing the habit of running rake cucumber or rake cucumber:wip is probably the better course.

The Cucumber Rake task recognises the @wip Tag, so rake cucumber:wip will run only those scenarios tagged with @wip.

For example, given a feature file containing:

Feature: .  .  .

  Scenario: A

  @wip
  Scenario: B

  Scenario: C

Then running the command rake cucumber:wip will run the Steps contained inside Scenario B only,
while running rake cucumber:ok will run the Steps within all Scenarios other than B.

Using Profiles in Rake Tasks Copy Section

For complex Feature runs that are tested often, it is nice to save the command line arguments as Cucumber profiles.

Once you have some profiles defined, you can use them in your Rake tasks, like so:

require 'rubygems'
require 'cucumber'
require 'cucumber/rake/task'

namespace :features do
  Cucumber::Rake::Task.new(:non_js) do |t|
    t.profile = "webrat"
  end

  Cucumber::Rake::Task.new(:selenium) do |t|
    t.profile = "selenium"
  end
end

Guarding Your production machines From Cucumber Copy Section

Since Rake tasks are used on development and productions systems, it is generally a good idea to place a guard around your Cucumber task so your productions boxes don't need to install Cucumber.

Below is an example of how to do this. This example is the Rake task that Cucumber generates for Rails projects, but the same idea applies to any project using Cucumber and Rake:

require 'rubygems'

begin
  require 'cucumber'
  require 'cucumber/rake/task'

  Cucumber::Rake::Task.new(:features) do |t|
    t.cucumber_opts = "--format pretty"
  end

  task features: 'db:test:prepare'
rescue LoadError
  desc 'Cucumber rake task not available'
  task :features do
    abort 'Cucumber rake task is not available. Be sure to install cucumber as a gem or plugin'
  end
end

Ruby on Rails Copy Chapter

cucumber-rails Copy Section

cucumber-rails is a RubyGem which
brings Ruby on Rails Generators for Cucumber with special support for Capybara
and DatabaseCleaner.

Installing

The cucumber:install generator sets up Cucumber in your Rails project. It
generates the necessary files in the features/ directory. After
running this generator you will also get a new rake task called cucumber.

For more details, see rails generate cucumber:install --help.

Usage

By default, cucumber-rails runs DatabaseCleaner.start and
DatabaseCleaner.clean before and after your Cucumber scenarios. This default
behavior can be disabled. See the
cucumber-rails README for details.

Resources

To learn more of the tools being integrated and assisted by cucumber-rails,
see the READMEs of
DatabaseCleaner and
Capybara.

File: content/docs/terms/_index.md Copy Chapter

title: Terminology menu: main collapseChildren: true iconClass: far fa-book Copy Chapter

There's loads of new terminology and jargon to learn as you learn about Cucumber and BDD. Here you'll find definitions of the common terms.