jest-cucumber

What is jest-cucumber?

jest-cucumber is an npm package that allows you to write BDD (Behavior-Driven Development) tests using Gherkin syntax and run them with Jest. It bridges the gap between business stakeholders and developers by enabling the creation of human-readable test scenarios.

What are jest-cucumber's main functionalities?

Define Feature Files

You can define your test scenarios in Gherkin syntax, which is a human-readable format. This makes it easier for non-developers to understand the test cases.

Feature: Addition
  Scenario: Add two numbers
    Given I have entered 50 into the calculator
    And I have entered 70 into the calculator
    When I press add
    Then the result should be 120 on the screen

Step Definitions

You can define step definitions in JavaScript to map the Gherkin steps to actual test code. This allows you to implement the logic for each step in your test scenarios.

const { defineFeature, loadFeature } = require('jest-cucumber');
const feature = loadFeature('./features/addition.feature');

defineFeature(feature, test => {
  test('Add two numbers', ({ given, when, then }) => {
    let calculator;

    given('I have entered 50 into the calculator', () => {
      calculator = new Calculator();
      calculator.enter(50);
    });

    given('I have entered 70 into the calculator', () => {
      calculator.enter(70);
    });

    when('I press add', () => {
      calculator.add();
    });

    then('the result should be 120 on the screen', () => {
      expect(calculator.result).toBe(120);
    });
  });
});

Integration with Jest

jest-cucumber integrates seamlessly with Jest, allowing you to run your BDD tests using Jest's test runner. This means you can leverage Jest's powerful features like mocking, snapshot testing, and parallel test execution.

const { defineFeature, loadFeature } = require('jest-cucumber');
const feature = loadFeature('./features/addition.feature');

defineFeature(feature, test => {
  test('Add two numbers', ({ given, when, then }) => {
    let calculator;

    given('I have entered 50 into the calculator', () => {
      calculator = new Calculator();
      calculator.enter(50);
    });

    given('I have entered 70 into the calculator', () => {
      calculator.enter(70);
    });

    when('I press add', () => {
      calculator.add();
    });

    then('the result should be 120 on the screen', () => {
      expect(calculator.result).toBe(120);
    });
  });
});

// Run the tests using Jest
// jest

Other packages similar to jest-cucumber

cucumber

Cucumber is a widely-used BDD framework that supports multiple languages including JavaScript. It allows you to write tests in Gherkin syntax and provides a rich set of features for defining and running BDD tests. Compared to jest-cucumber, Cucumber is more feature-rich but may require more setup and configuration.

codeceptjs

CodeceptJS is an end-to-end testing framework that supports BDD-style tests using Gherkin syntax. It integrates with various test runners and provides a high-level API for writing tests. While it offers more flexibility in terms of test runners and integrations, it may not be as tightly integrated with Jest as jest-cucumber.

nightwatch

Nightwatch is an end-to-end testing framework that supports BDD-style tests using Gherkin syntax. It is designed for browser automation and provides a simple API for writing and running tests. Compared to jest-cucumber, Nightwatch is more focused on browser automation and may not offer the same level of integration with Jest.

README

Jest Cucumber

Execute Gherkin scenarios in Jest

Overview

jest-cucumber is an alternative to Cucumber.js that runs on top on Jest. Instead of using describe and it blocks, you instead write a Jest test for each scenario, and then define Given, When, and Then step definitions inside of your Jest tests. jest-cucumber then allows you to link these Jest tests to your feature files and ensure that they always stay in sync.

Motivation

Jest is an excellent test runner with great features like parallel test execution, mocking, snapshots, code coverage, etc. If you're using VS Code, there's also a terrific Jest extension that allows you get realtime feedback as you're writing your tests and easily debug failing tests individually. Cucumber is a popular tool for doing Acceptance Test-Driven Development and creating business-readable executable specifications. This library aims to achieve the best of both worlds, and even run your unit tests and acceptance tests in the same test runner.

Getting Started

Install Jest Cucumber:

npm install jest jest-cucumber --save-dev

Add a Feature file:

Feature: Logging in

Scenario: Entering a correct password
    Given I have previously created a password
    When I enter my password correctly
    Then I should be granted access

Add the following to your Jest configuration:

  "testMatch": [
    "**/*.steps.js"
  ],

Add a step definition file that links to your feature file:

// logging-in.steps.js

import { defineFeature, loadFeature } from 'jest-cucumber';

const feature = loadFeature('features/LoggingIn.feature');

Add a Jest test for each scenario into your step definition file:

// logging-in.steps.js

import { defineFeature, loadFeature } from 'jest-cucumber';

const feature = loadFeature('features/LoggingIn.feature');

defineFeature(feature, test => {
  test('Entering a correct password', ({ given, when, then }) => {

  });
});

Add step definitions to your scenario Jest tests:

// logging-in.steps.js

import { loadFeature, defineFeature } from 'jest-cucumber';
import { PasswordValidator } from 'src/password-validator';

const feature = loadFeature('specs/features/basic-scenarios.feature');

defineFeature(feature, (test) => {
  let passwordValidator = new PasswordValidator();
  let accessGranted = false;

  beforeEach(() => {
    passwordValidator = new PasswordValidator();
  });

  test('Entering a correct password', ({ given, when, then }) => {
    given('I have previously created a password', () => {
      passwordValidator.setPassword('1234');
    });

    when('I enter my password correctly', () => {
      accessGranted = passwordValidator.validatePassword('1234');
    });

    then('I should be granted access', () => {
      expect(accessGranted).toBe(true);
    });
  });
});

Additional Documentation

• Asynchronous steps
• Automatic step Binding
• Backgrounds
• Configuration options
• Contributing
• Gherkin tables
• Re-using step definitions
• Running the examples
• Running with another test runner
• Scenario outlines
• Step definition arguments
• Using Docstrings

FAQ

Why doesn't this library work exactly like Cucumber and how do I avoid duplicated step code?

If you prefer an experience more like Cucumber with global step matching and the ability to define steps exactly once that can be matched to multiple steps across multiple feature files, then Jest Cucumber does accommodate this preference with autoBindSteps.

However, the default mode in Jest Cucumber can be thought of as Cucumber reimagined for Jest, and is designed for writing Jest tests that are kept in sync with Gherkin feature files. The goal is that your Jest tests (i.e., step definitions) are perfectly readable by themselves without jumping back and forth between step definitions and feature files. Another goal is to avoid global step matching, which many people find problematic and difficult to maintain as a codebase grows. By default, Jest Cucumber expects that your step definitions and feature files match exactly, and will report errors / generate suggested code when they are out of sync. To avoid duplicated step code, you can use the techniques described here.

Changelog

4.5.0 (2024-07-25)

Features

• expose Options, ErrorOptions, ScenarioNameTemplateVars from configuration (6a9a8c3)