cucumber

What is cucumber?

Cucumber is a tool for running automated tests written in plain language. It allows you to write tests that anyone can understand, regardless of their technical knowledge. Cucumber supports Behavior Driven Development (BDD) and is used to bridge the communication gap between stakeholders and developers.

What are cucumber's main functionalities?

Writing Features in Gherkin

Cucumber uses Gherkin syntax to define test scenarios in plain language. This makes it easy for non-technical stakeholders to understand and contribute to the test cases.

Feature: User login
  Scenario: Successful login
    Given the user is on the login page
    When the user enters valid credentials
    Then the user should be redirected to the dashboard

Step Definitions

Step definitions are the actual code implementations of the steps defined in Gherkin. They link the plain language steps to executable code.

const { Given, When, Then } = require('@cucumber/cucumber');

Given('the user is on the login page', function () {
  // code to navigate to login page
});

When('the user enters valid credentials', function () {
  // code to enter credentials
});

Then('the user should be redirected to the dashboard', function () {
  // code to check redirection
});

Hooks

Hooks allow you to run code before and after each scenario. This is useful for setting up and tearing down test environments.

const { Before, After } = require('@cucumber/cucumber');

Before(function () {
  // code to run before each scenario
});

After(function () {
  // code to run after each scenario
});

Data Tables

Data tables allow you to run the same scenario with multiple sets of data. This is useful for testing different input combinations.

Feature: User login
  Scenario Outline: Successful login with multiple users
    Given the user is on the login page
    When the user enters <username> and <password>
    Then the user should be redirected to the dashboard

    Examples:
      | username | password |
      | user1    | pass1    |
      | user2    | pass2    |

Other packages similar to cucumber

jest-cucumber

jest-cucumber is a library that allows you to use Cucumber's Gherkin syntax with Jest. It provides a way to write BDD-style tests using Jest as the test runner. Compared to Cucumber, jest-cucumber is more tightly integrated with Jest and may be easier to set up for projects already using Jest.

cypress-cucumber-preprocessor

cypress-cucumber-preprocessor is a plugin for Cypress that allows you to write your tests in Gherkin syntax. It combines the power of Cypress for end-to-end testing with the readability of Cucumber. This package is ideal for teams that prefer using Cypress for their testing needs but want to leverage BDD.

codeceptjs

CodeceptJS is an end-to-end testing framework that supports BDD-style tests. It allows you to write tests in plain language and supports multiple test runners and helpers. Compared to Cucumber, CodeceptJS offers more flexibility in terms of test runners and integrations.

README

Cucumber.js

Cucumber, the popular Behaviour-Driven Development tool, brought to your JavaScript stack.

It runs on both Node.js and modern web browsers.

Try it now: http://cucumber.no.de!

Development status

Cucumber.js is still a work in progress. Here is its current status.

Cucumber Technology Compatibility Kit

Feature	Status
Core (scenarios, steps, mappings)	Done
Background	Done1
Calling steps from step defs	To do
Comments	Done
Command-line interface	Done1, 2
Command-line options	To do2
Data tables	Done
Doc Strings	Done
Failing steps	Done
Hooks	Done
I18n	To do
JSON formatter	WIP3
Pretty formatter	WIP2
Scenario outlines and examples	To do
Stats collector	To do
Step argument transforms	To do
Tags	Done
Undefined steps	Done
Wire protocol	To do
World	Done

1. Not certified by Cucumber TCK yet.
2. Considered for removal from Cucumber TCK.
3. Missing 'matches' attributes. Simple wrapper for Gherkin's JsonFormatter pending porting of:

• https://github.com/cucumber/gherkin/blob/master/lib/gherkin/listener/formatter_listener.rb
• https://github.com/cucumber/gherkin/blob/master/lib/gherkin/formatter/filter_formatter.rb

in Gherkin itself.

Cucumber.js-specific features

Feature	Status
Background	Done1
CoffeeScript support	Done
Command-line interface	Done

1. Will be certified by Cucumber TCK.

Prerequesites

• Node.js
• NPM

Cucumber.js is tested on:

• Node.js 0.6 or 0.7 (see CI builds)
• Google Chrome
• Firefox
• Safari
• Opera

There are plans to have CI builds on browsers too.

Usage

Install

Cucumber.js is available as an npm module.

Install globally with:

$ npm install -g cucumber

OR

You may also define cucumber.js as a development dependency of your application by including it in a package.json file.

// package.json

{ "devDependencies" : {
    "cucumber": "latest"
  }
}

Then install with npm install --dev

Features

Features are written with the Gherkin syntax

# features/myFeature.feature

Feature: Example feature
  As a user of cucumber.js
  I want to have documentation on cucumber
  So that I can concentrate on building awesome applications

  Scenario: Reading documentation
    Given I am on the Cucumber.js Github repository
    When I go to the README file
    Then I should see "Usage" as the page title

Support Files

Support files let you setup the environment in which steps will be run, and define step definitions. Both JavaScript (.js) and CoffeeScript (.coffee) source files are supported.

World

World is a constructor function with utility properties, destined to be used in step definitions:

// features/support/world.js

var zombie = require('zombie');
var World = function World(callback) {
  this.browser = new zombie.Browser(); // this.browser will be available in step definitions

  this.visit = function(url, callback) {
    this.browser.visit(url, callback);
  };

  callback(); // tell Cucumber we're finished and to use 'this' as the world instance
};
exports.World = World;

It is possible to tell Cucumber to use another object instance than the constructor:

// features/support/world.js

var zombie = require('zombie');
var WorldConstructor = function WorldConstructor(callback) {
  this.browser = new zombie.Browser(); // this.browser will be available in step definitions

  var world = {
    visit: function(url, callback) {
      this.browser.visit(url, callback);
    }
  };

  callback(world); // tell Cucumber we're finished and to use our world object instead of 'this'
};
exports.World = WorldConstructor;

Step Definitions

Step definitions are the glue between features written in Gherkin and the actual SUT (system under test). They are written in JavaScript.

All step definitions will run with this set to what is known as the World in Cucumber. It's an object exposing useful methods, helpers and variables to your step definitions. A new instance of World is created before each scenario.

Step definitions are contained within one or more wrapper functions.

Those wrappers are run before executing the feature suite. this is an object holding important properties like the Given(), When() and Then() functions. Another notable property is World; it contains a default World constructor that can be either extended or replaced.

Step definitions are run when steps match their name. this is an instance of World.

// features/step_definitions/myStepDefinitions.js

var myStepDefinitionsWrapper = function () {
  this.World = require("../support/world.js").World; // overwrite default World constructor

  this.Given(/^I am on the Cucumber.js Github repository$/, function(callback) {
    // Express the regexp above with the code you wish you had.
    // `this` is set to a new this.World instance.
    // i.e. you may use this.browser to execute the step:

    this.visit('http://github.com/cucumber/cucumber-js', callback);

    // The callback is passed to visit() so that when the job's finished, the next step can
    // be executed by Cucumber.
  });

  this.When(/^I go to the README file$/, function(callback) {
    // Express the regexp above with the code you wish you had. Call callback() at the end
    // of the step, or callback.pending() if the step is not yet implemented:

    callback.pending();
  });

  this.Then(/^I should see "(.*)" as the page title$/, function(title, callback) {
    // matching groups are passed as parameters to the step definition

    if (!this.isOnPageWithTitle(title))
      // You can make steps fail by calling the `fail()` function on the callback:
      callback.fail(new Error("Expected to be on page with title " + title));
    else
      callback();
  });
};

module.exports = myStepDefinitionsWrapper;

It is also possible to use simple strings instead of regexps as step definition patterns:

this.Then('I should see "$title" as the page title', function(title, callback) {
  // the above string is converted to the following Regexp by Cucumber:
  // /^I should see "([^"]*)" as the page title$/

  if (!this.isOnPageWithTitle(title))
    // You can make steps fail by calling the `fail()` function on the callback:
    callback.fail(new Error("Expected to be on page with title " + title));
  else
    callback();
});

'I have $count "$string"' would translate to /^I have (.*) "([^"]*)")$/.

Hooks

Hooks can be used to prepare and clean the environment before and after each scenario is executed.

Before hooks

To run something before every scenario, use before hooks:

// features/support/hooks.js (this path is just a suggestion)

var myHooks = function () {
  this.Before(function(callback) {
    // Just like inside step definitions, "this" is set to a World instance.
    // It's actually the same instance the current scenario step definitions
    // will receive.

    // Let's say we have a bunch of "maintenance" methods available on our World
    // instance, we can fire some to prepare the application for the next
    // scenario:

    this.bootFullTextSearchServer();
    this.createSomeUsers();

    // Don't forget to tell Cucumber when you're done:
    callback();
  });
};

module.exports = myHooks;

After hooks

The before hook counterpart is the after hook. It's similar in shape but is executed, well, after every scenario:

// features/support/after_hooks.js

var myAfterHooks = function () {
  this.After(function(callback) {
    // Again, "this" is set to the World instance the scenario just finished
    // playing with.

    // We can then do some cleansing:

    this.emptyDatabase();
    this.shutdownFullTextSearchServer();

    // Release control:
    callback();
  });
};

module.exports = myAfterHooks;

Around hooks

It's also possible to combine both before and around hooks in one single definition with the help of around hooks:

// features/support/advanced_hooks.js

myAroundHooks = function() {
  this.Around(function(runScenario) {
    // "this" is - as always - an instance of World promised to the scenario.

    // First do the "before scenario" tasks:

    this.bootFullTextSearchServer();
    this.createSomeUsers();

    // When the "before" duty is finished, tell Cucumber to execute the scenario
    // and pass a function to be called when the scenario is finished:

    runScenario(function(callback) {
      // Now, we can do our "after scenario" stuff:

      this.emptyDatabase();
      this.shutdownFullTextSearchServer();

      // Tell Cucumber we're done:
      callback();
    });
  });
};

module.exports = myAroundHooks;

Tagged hooks

Hooks can be conditionally elected for execution based on the tags of the scenario.

// features/support/hooks.js (this path is just a suggestion)

var myHooks = function () {
  this.Before("@foo", "@bar,@baz", function(callback) {
    // This hook will be executed before scenarios tagged with @foo and either
    // @bar or @baz.

    // ...

    callback();
  });
};

module.exports = myHooks;

Run cucumber

Cucumber.js includes a binary file to execute the features.

If you installed cucumber.js globally, you may run it with:

$ cucumber.js

You may specify the features to run:

$ cucumber.js features/my_feature.feature

And require specific step definitions and support code files with the --require option:

$ cucumber.js features/my_feature.feature --require features/step_definitions/my_step_definitions.js

If you installed Cucumber locally or with npm install --dev, you'll need to specify the path to the binary:

$ ./node_modules/.bin/cucumber.js

Note to Windows users: invoke Cucumber.js with cucumber-js instead of cucumber.js. The latter is causing the operating system to invoke JScript instead of Node.js, because of the so-called file extension.

Examples

A few example apps are available for you to browse:

• Rails app serving features in the browser
• Express.js app running features in the cli
• Try cucumber.js in the browser

Contribute

See CONTRIBUTE.

Help & support

• Twitter: @cucumber_js
• IRC: #cucumber on Freenode
• Google Groups: cukes
• cukes.info

Changelog

[0.2.21]

Added

• Add bundler (Julien Biezemans)