Use Nightwatch’s integrated Cucumber.js runner to run Gherkin feature files with JavaScript step definitions. Install Cucumber in the Nightwatch project, select the Cucumber runner in nightwatch.conf.js, point Nightwatch to your feature and step-definition paths, then run the suite with the Nightwatch CLI.
How the Cucumber and Nightwatch integration works
Cucumber describes scenarios in Gherkin feature files; step definitions connect those scenarios to executable test code. Nightwatch can use Cucumber.js as an alternative test runner, so Nightwatch’s CLI starts the suite while Cucumber interprets the features and runs their steps. The integration guide documents Cucumber.js 7.3 or higher for this setup. Treat that as the guide’s stated requirement, not a promise of compatibility with every later release; check the versions installed in your project and the current Nightwatch documentation before pinning dependencies. Nightwatch’s Cucumber.js guide
Install Cucumber and configure Nightwatch
1. Add the Cucumber dependency
From the project directory that contains Nightwatch, install Cucumber as a development dependency:
npm i @cucumber/cucumber --save-devKeep the feature and step-definition paths consistent with your project’s directory structure; the paths below are an example, not required folder names.
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 minute#1 Best Overall
2. Point Nightwatch at the runner and test files
In nightwatch.conf.js, select the Cucumber runner, set the feature-file pattern, and list the directory containing the step definitions:
module.exports = {
test_runner: {
type: 'cucumber',
options: {
feature_path: 'tests/features/*.feature',
auto_start_session: true,
parallel: 2
}
},
src_folders: ['tests/step_definitions']
};Here, Nightwatch looks for feature files in tests/features and step definitions in tests/step_definitions. The official integration guide allows feature and step-definition files to be supplied through src_folders or as CLI arguments; the Nightwatch boilerplate shows features and step definitions in separate directories. Nightwatch looks for a configuration file in the working directory by default. 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 location. Nightwatch configuration reference
Write a feature and its step definitions
For example, save this Gherkin in tests/features/homepage.feature:
Feature: Homepage
Scenario: Open the homepage
Given I open the homepage
Then the page title contains "Example Domain"Then create a JavaScript step-definition file under tests/step_definitions, such as homepage.js:
const { Given, Then } = require('@cucumber/cucumber');
Given('I open the homepage', async function () {
await this.browser.navigateTo('https://example.com');
});
Then('the page title contains {string}', async function (expectedText) {
const title = await this.browser.getTitle();
if (!title.includes(expectedText)) {
throw new Error(`Expected title to contain "${expectedText}", got "${title}"`);
}
});This example assumes the Nightwatch-managed browser is available to the steps as this.browser. If your project’s installed integration exposes or initializes the browser differently, follow its current Nightwatch example and keep your hooks and steps consistent with that lifecycle.
Run the Cucumber suite
From the project root, run Nightwatch with the configured source folders:
npx nightwatchYou can also pass the relevant path to the CLI, as in the integration examples:
npx nightwatch tests/step_definitionsNightwatch’s guide demonstrates passing --parallel 2 for parallel execution and forwarding Cucumber formatter options. The boilerplate shows tag filtering with an expression such as --tags "@nightwatch and @cucumber". For example, where supported by your installed versions:
npx nightwatch --parallel 2 --tags "@nightwatch and @cucumber"CLI options and forwarding behavior can change between releases. Check npx nightwatch --help and the CLI documentation for the versions in your project before building CI commands around them. Nightwatch CLI options
Choose when the browser session starts
For a typical test, leave auto_start_session: true; the documented example enables automatic session startup. Set it to false when a scenario must change capabilities or perform setup before the browser launches.
With automatic startup disabled, use a Cucumber hook and the Nightwatch client to set capabilities and call launchBrowser(). The integration guide’s approach assigns the returned browser to this.browser, allowing Nightwatch to close it automatically. If your hook does not use that pattern, explicitly close the session during teardown so browser processes are not left running. Follow the hook and capability APIs documented for your installed Nightwatch version. Nightwatch Cucumber hooks and session setup
Pick a local or remote browser environment
Start locally to validate the integration with the least configuration. Nightwatch organizes browser targets into test_settings, with a default environment and named environments for other browsers or destinations. Depending on the supported local driver and configuration, Nightwatch can manage local WebDriver processes. Testing through a Selenium Grid or cloud service requires Selenium configuration. Nightwatch Selenium setup Nightwatch settings Nightwatch test environments
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 →Best Value
Choose between local and remote execution based on the coverage and operations your team needs:
- Browser and operating-system coverage: use the environments that can exercise the browser and operating-system combinations your application supports.
- Setup and maintenance: local runs require suitable browsers and driver management; remote runs require a reachable Grid or service and its configuration.
- CI integration and capacity: consider how your pipeline connects to the target environment and whether its available parallel capacity suits your suite.
- Cost: compare current service terms directly before choosing a cloud provider. Nightwatch’s environment documentation names BrowserStack and Sauce Labs as examples, but does not establish current prices or a comparative feature assessment.
Configure Cucumber reporting
In integrated-runner mode, reporting is handled by the Cucumber CLI. Nightwatch’s guide says its own reporters, including JUnit XML reporting and the global custom reporter, are unavailable in this mode. Use a Cucumber formatter instead: the guide says the progress formatter is the default and that Nightwatch forwards --format and --format-options. Confirm the formatter package, output format, and CLI syntax against the Cucumber version installed in your project. Cucumber reporting in Nightwatch
Troubleshoot common setup problems
- Nightwatch cannot find configuration: run the command from the directory containing the config, or provide the intended file with
--config. - No features or steps are discovered: compare
feature_pathandsrc_folderswith the real project paths and filenames. Alternatively, pass the paths through the CLI as supported by your installed version. - Step definitions are undefined: ensure the step-definition files are in a directory Nightwatch passes to Cucumber, and check that the Gherkin wording matches the expressions in the JavaScript definitions.
- The browser starts before setup is ready: set
auto_start_session: false, then launch it in a hook after setting the needed capabilities. Make sure the hook follows the installed integration’s client and browser lifecycle. - A browser or remote session fails to start: check the selected
test_settingsenvironment and its browser/driver configuration. For a Grid or cloud target, verify Selenium setup and connectivity. - Nightwatch reporter options have no effect: the integrated Cucumber runner uses Cucumber reporting. Configure a compatible Cucumber formatter and use the forwarded formatter options instead.
- Parallel or tag arguments are rejected: check Nightwatch CLI help and installed Nightwatch/Cucumber versions; the documented examples may not match every release combination.
Or skip the browser setup
If your goal is a screenshot rather than an interactive browser test, ScreenshotNeo returns an image or PDF from one GET request. For example, capture a page as WebP:
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 removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo free.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
Can I use Nightwatch’s built-in reporters with the integrated Cucumber runner?
No. In integrated-runner mode, use Cucumber formatters; Nightwatch’s own reporters are unavailable.
Does ScreenshotNeo replace Cucumber and Nightwatch for browser tests?
No. ScreenshotNeo captures page images or PDFs; Cucumber and Nightwatch run browser automation tests with scenarios and assertions.
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.
