Workflow:Nightwatchjs Nightwatch Cucumber BDD Integration
| Knowledge Sources | |
|---|---|
| Domains | BDD, E2E_Testing, Cucumber |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
End-to-end process for integrating Cucumber.js with Nightwatch to write behavior-driven development (BDD) tests using Gherkin syntax mapped to Nightwatch browser commands.
Description
This workflow covers using Cucumber.js as an alternative test runner within Nightwatch. Tests are authored as Gherkin feature files with Given/When/Then steps that are implemented using Nightwatch's browser automation API. This enables non-technical stakeholders to read and contribute to test specifications while developers implement the step definitions using the full power of Nightwatch's WebDriver API. The integration supports parallel execution, custom formatters, and the complete Cucumber lifecycle hooks.
Usage
Execute this workflow when your team practices behavior-driven development and wants to write test specifications in natural language (Gherkin) that are executable against real browsers. This is especially valuable when product owners or QA analysts need to define acceptance criteria that double as automated tests.
Execution Steps
Step 1: Install Cucumber Dependencies
Install @cucumber/cucumber as a dependency alongside Nightwatch. The Cucumber integration is built into Nightwatch's test runner and does not require a separate plugin, but the Cucumber package itself must be present.
Key considerations:
- Install @cucumber/cucumber at a compatible version
- Nightwatch's built-in Cucumber runner handles session management
- No additional plugins are needed for basic Cucumber integration
Step 2: Configure Cucumber Test Runner
Update the Nightwatch configuration to use Cucumber as the test runner. This involves setting the test_runner property to cucumber, specifying feature file paths, and configuring step definition locations.
What happens:
- Set test_runner type to "cucumber" in nightwatch.conf.js
- Configure feature_path to locate .feature files
- Specify step_definitions path for step implementation files
- Optionally configure parallel execution and formatters
Step 3: Write Feature Files
Author Gherkin feature files that describe user scenarios in natural language using Feature, Scenario, Given, When, Then, And, and But keywords. Each scenario represents a distinct test case with clear preconditions, actions, and expected outcomes.
Key considerations:
- Feature files use .feature extension and Gherkin syntax
- Scenarios should be independent and self-contained
- Use Scenario Outline with Examples for data-driven testing
- Background steps run before each scenario in the feature
Step 4: Implement Step Definitions
Write step definition files that map Gherkin steps to Nightwatch browser commands using regex or Cucumber expression patterns. Step functions receive the browser object and return promises from Nightwatch command chains.
What happens:
- Import Given, When, Then from @cucumber/cucumber
- Define regex patterns that match Gherkin step text
- Step function body uses Nightwatch browser commands
- Parameterized steps capture values from the Gherkin text
- Steps return browser command promises for proper async handling
Step 5: Execute and Report
Run Cucumber tests via the Nightwatch CLI with the Cucumber configuration. The runner manages WebDriver sessions, executes feature files, and produces reports in Cucumber's native format alongside Nightwatch's standard reporting.
Key considerations:
- Use npx nightwatch with the Cucumber environment configuration
- Parallel execution runs feature files across multiple workers
- Custom Cucumber formatters can be configured for specialized output
- Tags can filter which scenarios to execute