Cucumber.js — BDD Testing with Plain Language Scenarios

Introduction

Cucumber.js brings behavior-driven development to JavaScript and TypeScript projects. Tests are written as Gherkin feature files in plain English that non-technical stakeholders can read and contribute to. Step definitions in JavaScript map each Gherkin step to executable code, bridging the gap between requirements and test automation.

What Cucumber.js Does

• Executes feature files written in Gherkin (Given/When/Then) syntax
• Maps Gherkin steps to JavaScript or TypeScript step definitions
• Supports scenario outlines for data-driven tests with example tables
• Generates reports in JSON, HTML, JUnit XML, and custom formats
• Integrates with Playwright, Selenium, or Puppeteer for browser automation

Architecture Overview

The Cucumber.js runtime parses .feature files using the Gherkin parser, which produces an abstract syntax tree of features, scenarios, and steps. The step definition loader scans configured paths for matching patterns. At execution time, each scenario runs in isolation: the runtime matches each Gherkin step text against registered patterns (strings or regex), invokes the corresponding function, and collects pass/fail results. A World object provides shared context across steps within a single scenario.

Self-Hosting & Configuration

• Install @cucumber/cucumber and configure paths in cucumber.js or cucumber.yaml
• Define step files in features/step_definitions/ by convention
• Use --tags @smoke to filter scenarios by tag for selective runs
• Set --parallel N to run scenarios across multiple worker processes
• Generate HTML reports with cucumber-html-reporter or the built-in formatter

Key Features

• Plain-language feature files serve as living documentation readable by anyone
• Parameterized steps with Cucumber expressions reduce step definition duplication
• Scenario outlines drive the same scenario with multiple data rows from example tables
• Hooks (Before, After, BeforeStep) manage setup, teardown, and screenshots on failure
• Tag-based filtering organizes scenarios into suites: @smoke, @regression, @wip

Comparison with Similar Tools

• Jest — code-level unit testing; Cucumber.js focuses on behavior specs in natural language
• Cypress — browser E2E testing with its own API; Cucumber.js adds a Gherkin layer on top of any driver
• Playwright Test — built-in test runner; Cucumber.js provides a BDD wrapper when stakeholder-readable specs are needed
• Behat — Cucumber for PHP; Cucumber.js serves the JavaScript and TypeScript ecosystem
• SpecFlow — Cucumber for .NET; Cucumber.js targets Node.js with native async support

FAQ

Q: Can I use Cucumber.js with TypeScript? A: Yes. Use ts-node or tsx as the runtime and write step definitions in .ts files.

Q: How do I share state between steps? A: Use the World object. Each scenario gets a fresh World instance, and steps access it via this.

Q: Does Cucumber.js support parallel execution? A: Yes. Use --parallel <workers> to distribute scenarios across processes for faster runs.

Q: Can I integrate Cucumber.js with Playwright? A: Yes. Initialize a Playwright browser in a Before hook and close it in After, then drive pages in step definitions.

Sources

• https://github.com/cucumber/cucumber-js
• https://cucumber.io/docs/cucumber/