Nightwatch.js can run Cucumber.js feature files through its integrated Cucumber runner. Install Cucumber in your Nightwatch project, point the runner at your feature files and step definitions, then start the suite with the Nightwatch CLI. The configuration below shows the basic setup, browser-session choices, parallel execution, tags, and reporting limitations.
Set up Cucumber in a Nightwatch project
Nightwatch documents Cucumber.js as an alternative integrated test runner. Install the Cucumber package in the same project as Nightwatch:
As an Amazon Associate I earn from qualifying purchases.
npm i @cucumber/cucumber --save-devThe Nightwatch integration guide specifies Cucumber.js 7.3 or later for the documented integration. That is the guide’s stated requirement, not a guarantee for every future release; check the installed Nightwatch and Cucumber versions together when choosing versions. Nightwatch’s Cucumber guide
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteOrganize feature files and step definitions
Feature files contain Gherkin scenarios; JavaScript step definitions implement their steps. A common layout keeps those in separate directories, for example:
#1 Best Overall
tests/
features/
login.feature
step_definitions/
login.js
nightwatch.conf.jsNightwatch allows feature files and step-definition files to be specified through src_folders or as command-line arguments. Set the paths to match your own project rather than copying a directory name that does not exist. The Nightwatch boilerplate also demonstrates separate feature and step-definition directories.
Configure the integrated runner
In the project’s Nightwatch configuration file, select the Cucumber runner and identify the feature files and step-definition source directory:
module.exports = {
test_runner: {
type: 'cucumber',
options: {
feature_path: 'tests/features/*.feature',
auto_start_session: true,
parallel: 2
}
},
src_folders: ['tests/step_definitions']
};Change feature_path and src_folders to the paths in your repository. The example enables automatic browser-session startup and configures two parallel workers; those are choices, not mandatory settings. By default, Nightwatch looks for a configuration file in the working directory. Recognized names in its configuration reference include nightwatch.conf.js, nightwatch.conf.cjs, nightwatch.conf.ts, and nightwatch.json. Use --config to select a different file. Nightwatch configuration reference
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Write a feature and matching step definitions
A feature file describes behavior in Gherkin. For example, a simple navigation scenario could be:
Feature: Home page
Scenario: Open the home page
Given I open the home page
Then the page title contains "Example"Implement each step in a JavaScript step-definition file under the configured source directory. This illustrative version uses Nightwatch’s browser client through the Cucumber world; adapt the hooks and browser setup to the conventions supported by your installed Nightwatch and Cucumber versions:
const { Given, Then } = require('@cucumber/cucumber');
Given('I open the home page', async function () {
await this.browser.url('https://example.com');
});
Then('the page title contains {string}', async function (expected) {
const title = await this.browser.title();
if (!title.includes(expected)) {
throw new Error(`Expected title to contain "${expected}", got "${title}"`);
}
});The exact browser object available to a step depends on how the project initializes its Cucumber world and session. Nightwatch’s integration guide specifically documents using this.client in hooks for session setup and assigning a launched browser to this.browser when controlling startup manually.
Run scenarios with the Nightwatch CLI
From the project root, run the configured suite with:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutenpx nightwatchIf you need to pass the step-definition directory directly, the integration examples also show:
npx nightwatch tests/step_definitionsThe integrated runner accepts Cucumber-related CLI options. The guide demonstrates parallel execution and passing Cucumber formatter options; the boilerplate shows tag filtering. For example:
npx nightwatch --parallel 2
npx nightwatch --tags "@nightwatch and @cucumber"Confirm option support with the CLI help and the versions installed in your project before relying on an invocation in CI. The integration guide and boilerplate examples document these patterns.
Choose when the browser session starts
For a standard run, leave auto_start_session: true (the guide’s example default) and let Nightwatch start the browser. Turn it off when a hook needs to change capabilities or perform other setup before launch:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →- Set
auto_start_session: falsein the Cucumber runner options. - In the relevant Cucumber hook, use Nightwatch’s
this.clientinstance to update capabilities. - Call
launchBrowser()after setup and assign the returned browser tothis.browser. - Ensure teardown closes the session if your hooks do not use the documented browser assignment pattern.
This gives setup code control of launch timing, but also makes session cleanup your responsibility when you depart from the documented pattern. Nightwatch’s Cucumber guide
Best Value
Run locally or against a remote browser
Start with a local browser when the goal is to verify the integration with minimal infrastructure. Nightwatch’s environment settings support a default environment and named environments for different browsers or targets. Its documentation describes managed local WebDriver processes as well as remote Selenium and cloud testing configurations; Selenium is required for Grid or cloud testing services. See setup guidance, settings, and environment configuration.
Decide between local and remote execution based on the coverage and operating systems you need, local browser and driver maintenance, CI or remote-grid integration, execution speed and parallel capacity, and service cost. Nightwatch names BrowserStack and Sauce Labs as provider examples, but current prices and provider feature comparisons are not established here; check each provider’s current terms directly. Nightwatch environment documentation
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Configure Cucumber reporting
With the integrated runner, reporting is delegated to the Cucumber CLI. Nightwatch’s own reporters—including its JUnit XML reporting and global custom reporter—are unavailable in this mode. Use a Cucumber formatter instead; Nightwatch forwards --format and --format-options, and the guide identifies the progress formatter as the default. Verify formatter package installation and output details against the Cucumber version in your project. Nightwatch reporting guidance
Troubleshoot common setup problems
- Nightwatch does not find the configuration: Run the command from the project root or pass the configuration’s path with
--config. Check that its filename is one recognized by the current configuration reference. - No feature files are discovered: Check that
feature_pathmatches the actual feature-file location and glob. Alternatively, pass the relevant path as a CLI argument as supported by the integration. - Steps are undefined: Confirm that the step-definition files are under a configured
src_folderspath or are otherwise passed to the CLI. Make sure the Gherkin step text and the Cucumber expression in the definition match. - Browser starts before setup is ready: Disable automatic startup and launch from a hook after changing capabilities. Close the session during teardown if you manage it manually.
- Reporter options or output are unexpected: Use Cucumber formatter options rather than Nightwatch reporters in the integrated-runner mode, and check that the selected formatter works with the installed Cucumber version.
- Parallel or tag options are rejected: Check the installed CLI’s help and version compatibility; command-line support can change across releases.
- Remote Grid or cloud launch fails: Review the selected Nightwatch environment and Selenium configuration; Nightwatch’s settings reference requires Selenium for Grid and cloud testing.
Or skip the browser setup
If your goal is to capture a web page rather than run an interactive browser test, ScreenshotNeo offers a screenshot API and MCP server. One GET request returns an image or PDF; for example, using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for request options. It accepts cookie or consent banners before capture and removes supported consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Can I keep Nightwatch tests and Cucumber scenarios in one project?
Yes. Install Cucumber as a development dependency in the Nightwatch project and configure the integrated runner to locate the features and step definitions.
Does the integrated Cucumber runner support Nightwatch’s JUnit reporter?
No. In this runner mode, reporting is handled by Cucumber’s CLI and Nightwatch’s reporters are unavailable.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
