Cucumber.js

Cucumber.js brings Cucumber’s executable specifications to JavaScript projects, with scenarios written in Gherkin and linked to code through step definitions. It is a strong fit for Node.js teams using Behaviour-Driven Development; the trade-off is project-level setup and the need to supply the actions that make each scenario run.

Overview

Cucumber checks software against plain-text scenarios and reports whether each one succeeds or fails. Keeping Gherkin feature files in source control alongside the software gives teams a shared set of examples to discuss and maintain. Those examples are not self-executing, however: step definitions must connect their steps to code that performs the described actions.

Cucumber.js is the stable, canonical JavaScript implementation, distributed as the @cucumber/cucumber npm module for Node.js. The project describes @cucumber/node as pre-1.0.0 and subject to change, making @cucumber/cucumber the more settled choice for JavaScript teams. Cucumber says thousands of companies rely on its tests to validate software, but that adoption does not remove the work of authoring and maintaining definitions.

Key features

Gherkin and step definitions

Scenarios live in structured plain-text .feature files. Step definitions map their Gherkin steps to programming code; they can use Cucumber Expressions or regular expressions, but cannot combine both syntaxes in a single expression. This structure supports a shared vocabulary for examples, while requiring developers to keep the prose and its code connections aligned.

Command-line and parallel runs

The package includes an executable for running feature files from the command line, and parallel execution is supported. That suits teams incorporating scenarios into development or continuous integration. Cucumber is not a browser automation tool, so browser-based checks need to work with an automation tool such as Selenium WebDriver.

Reports and publishing

Reporter plugins can produce results showing which scenarios passed or failed. Cucumber supports built-in, separately installed and custom plugins, giving teams room to choose how results are presented. Publishing reports with --publish is supported from Cucumber-JS 7.3.0; the broader publishing support applies to Cucumber-JS 7.0.0 and above. Published reports are publicly accessible and deleted after 24 hours. Cucumber Reports says report data is stored in US data centers and encrypted at rest, so teams should avoid publishing sensitive material.

Pricing

Cucumber.js is open-source software with a free plan at no cost. The @cucumber/cucumber npm module is installed as a development dependency; there is no free trial or paid tier described. The free plan suits teams able to install and maintain the package within their own Node.js project, rather than those seeking a separately priced hosted testing service.

Installation requires Node.js and npm or Yarn. Cucumber.js does not work when installed globally, because globally installed modules cannot be imported or required in support files. Installing it as a project development dependency is therefore a requirement, not just a preference.

Platforms

Cucumber.js supports Node.js and is listed for Linux, macOS, Windows and self-hosted use. Its JavaScript setup uses npm or Yarn, and the command-line executable runs feature files in the project.

Who it's for

Choose Cucumber.js if a JavaScript team wants executable examples to support discovery, collaboration and testing as part of Behaviour-Driven Development. It is less suitable for teams that want a browser automation tool in one package, or cannot take on the work of writing step definitions and keeping them connected to application behavior.

The project provides a security policy for contacting maintainers about security issues and directs community questions to Discord, GitHub Discussions and Stack Overflow. It also advises against defining environment variables containing secrets globally. Cucumber says its intellectual property assets moved from SmartBear Software to the Open Source Collective in December 2024.

Pros and cons

• Pros: Gherkin scenarios can serve as both shared examples and executable checks, with results reported for each scenario.
• Pros: Command-line execution, parallel runs, CI use and configurable reporter plugins support integration into development workflows.
• Pros: The canonical JavaScript package is free and installable as a project development dependency through npm or Yarn.
• Cons: Every scenario depends on step definitions that connect its language to code, adding work to create and maintain.
• Cons: Global installation does not work, and browser automation must come from a separate tool.
• Cons: Published reports are public, even though they are deleted after 24 hours; sensitive content requires care.

Alternatives

For other options, browse JavaScript Testing Frameworks and Test Automation Software.

• QUnit is a free, open-source JavaScript testing framework distributed via CDN, npm and Yarn; choose it when that framework approach is a better fit than Cucumber’s Gherkin scenarios.
• Karma is free and MIT-licensed, but deprecated, with no new features or general bug fixes; it is an option only if that status is acceptable.
• Web Test Runner is an alternative for readers seeking a browser-focused approach to modern web development.
• Pure Test is free, Apache-2.0 open-source software with no paid plans; consider it if that project is a better match for your testing needs.
• Vitest is free and open source, with no plan limits stated; choose it if you prefer that alternative to Gherkin-based scenarios.
• Testem is a free, MIT-licensed open-source JavaScript test runner; it is an alternative if a test runner rather than BDD scenarios is what you need.
• Intern is another free option for readers comparing testing software.
• uvu is a free, MIT-licensed test runner for Node.js and the browser; consider it if you want a test runner for those environments rather than Cucumber’s Gherkin workflow.

Verdict

Cucumber.js is a sound choice for Node.js teams that want Gherkin examples to become repeatable behavior checks and are prepared to maintain step definitions. Its free, canonical package and CI-friendly execution are compelling; look elsewhere if you need browser automation included or want tests without the extra mapping from scenarios to code.