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!

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

1. Not certified by Cucumber TCK yet.
2. Considered for removal from Cucumber TCK.

1. Will be certified by Cucumber TCK.

• Node.js
• NPM

Cucumber.js was tested on:

• Node.js 0.4, 0.5, 0.6
• Google Chrome
• Firefox
• Safari

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 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 page
    When I go to the README file
    Then I should see "Usage"

Support files let you setup the environment in which steps will be run, and define step definitions.

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

// features/support/world.js

require('zombie');
var World = module.exports = function(){
  this.browser = new zombie.Browser(); // this.browser will be available in step definitions
  
  this.visit = function(url){
    this.browser.visit(url, callback(err, browser, status){
      callback(err, browser, status);
    });
  };
};

Step definitions are written in javascript. Each step definition has a World property that can be set to a constructor function. Each individual step will be executed in the context of an instance of the World function. (i.e. this inside a step will refer to a newly created instance of the World property, making sure state stays consistent between each scenario)

// features/step_definitions/myStepDefinitions.js

var myStepDefinitions = function(){
  this.World = require(" <path to the world file> ");
  
  this.Given( <REGEXP>, function(next){
    // 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', next);
  });
  
  this.When( <REGEXP>, function(next) {
    // express the regexp above with the code you wish you had
    // Call next() at the end of the step, or next.pending() if the step is not yet implemented.
    next.pending();
  });
  
  this.Then( <REGEXP>, function(next) {
    // express the regexp above with the code you wish you had
    next.pending();
  });
};

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

If you installed cucumber.js with npm install --dev, you may run cucumber with:

  @NODE_ENV=test ./node_modules/.bin/cucumber.js

You may specify the features to run with the first argument:

  @NODE_ENV=test ./node_modules/.bin/cucumber.js features/myFeature.feature

And require specific step definitions with the --require option:

  @NODE_ENV=test ./node_modules/.bin/cucumber.js features/myFeature.feature \
    --require features/step_definitions/myStepDefinitions.js

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

Install the required dependencies:

$ npm link

$ node example/server.js

Then go to localhost:9797.

$ node_modules/.bin/jasmine-node spec

There is a common set of features shared by all cucumber implementations. It's called the Technology Compatibility Kit or TCK. Find more on the Cucumber TCK repository.

The official way of running them is through Cucumber-ruby and Aruba. Ruby and Bundler are required for this to work.

$ git submodule update --init
$ bundle
$ rm -rf doc; ARUBA_REPORT_DIR=doc cucumber features/cucumber-tck -r features

You can then open the generated documentation:

$ open doc/features/cucumber-tck/*.html # might open a lot of files ;)

In addition to that, Cucumber.js is able to run the features for itself too:

$ ./bin/cucumber.js features/cucumber-tck -r features

There are a few other Cucumber.js-dependent features. Execute everything:

$ ./bin/cucumber.js

Alternatively, you can run everything with the help of Rake:

$ git submodule update --init
$ bundle
$ rake

You can display debug messages by setting the DEBUG_LEVEL environment variable. It goes from 1 to 5. 5 will diplay everything, 1 will only print out the critical things.

$ DEBUG_LEVEL=5 ./bin/cucumber.js

It even works with Aruba:

$ rm -rf doc; DEBUG_LEVEL=5 ARUBA_REPORT_DIR=doc cucumber features/cucumber-tck -r features
$ open doc/features/cucumber-tck/*.html # you'll see debug messages in Aruba-generated docs