# Cucumber.js — BDD Testing with Plain Language Scenarios

> Cucumber.js is a JavaScript implementation of Cucumber that runs automated tests written in Gherkin plain language.

## Install

Save in your project root:

# Cucumber.js — BDD Testing with Plain Language Scenarios

## Quick Use
```bash
npm install --save-dev @cucumber/cucumber
```
```gherkin
# features/login.feature
Feature: User login
  Scenario: Valid credentials
    Given the user visits the login page
    When they enter valid credentials
    Then they should see the dashboard
```
```javascript
// features/step_definitions/login.steps.js
const { Given, When, Then } = require('@cucumber/cucumber');
Given('the user visits the login page', async function () { /* navigate */ });
When('they enter valid credentials', async function () { /* fill form */ });
Then('they should see the dashboard', async function () { /* assert */ });
```

## 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/

---
Source: https://tokrepo.com/en/workflows/615c4969-4278-11f1-9bc6-00163e2b0d79
Author: AI Open Source