Quick and easy testing with cucumber.js

NPM Version Build Status JS.ORG

What is Cucumber-mink ?

Cucumber-mink lets you write Gherkin BDD style end-to-end test and run it inside any browser. You don't have to do any complex configuration, just focus on writing test:

Feature: Post page

    Given I browse "http://my-app:3000/"

  Scenario: Go on post 1
    Given I am on homepage
    And I follow "Post-1"
    Then I should be on "/post/1"
    And I should see "Post-1"

What steps can I use ?

Cucumber mink comes with 40+ built-in steps, those provides the essential set to test your website.
See the available steps

How to start

Below steps will help you start a new test project from scratch.

1. Folder structure

Let's start a new integration testing project for an app called mysite. The folder structure will need to match the structure expected by cucumber.js:

---- features/
--------- step_definitions/
-------------- mink-gherkin.js
--------- support/
-------------- mink.js
--------- mysite.feature
---- package.json

Features directory contains cucumber feature files written in gherkin syntax. step_definitions contains the JavaScript implementation of gherkin test cases. Check out the GitHub repository for example implementations covering most used testing scenarios.

2. Package.json

This can be an example package.json file for our project:

    "name": "mysite-test",
    "version": "1.0.0",
    "description": "Integration testing for mysite v1",
    "dependencies": {
        "cucumber": "latest",
        "cucumber-mink": "latest"

3. Install dependencies

Now we can get the project dependencies installed:

$ npm install

4. Scenario definitions

Let's start with the scenario file called mysite.feature. For more examples of feature and scenario definitions, check out test folder.

5. Get cucumber-mink gherkin steps

We now need the corresponding step definitions that implement the steps in our scenario. cucumber-mink has a collection of steps already implemented - ready to be included in your project - see gherkin expressions.

Add the following to test/features/step_definitions/mink-gherkin.js

const cucumber = require('cucumber');
const mink = require('cucumber-mink');


6. Support code

Now we need a support code to implement cucumber hooks and initialize mink. Add the following in features/support/mink.js:

const cucumber = require('cucumber');
const mink = require('cucumber-mink');

const driver = new mink.Mink({
  baseUrl: 'http://localhost:8080',
  viewport: {
    width: 1366,
    height: 768,


7. Run tests with cucumber.js

The following will run our scenario (in the project directory):

$ npx cucumber-js features/mysite.feature

1 scenario (1 passed)
3 steps (3 passed)