Nightwatch.js Tutorial: Getting Started with Browser Testing

To get started with Nightwatch.js browser testing, install Node.js, scaffold a project with npm init nightwatch, choose end-to-end testing and an installed browser, then run the generated tests with npx nightwatch ./nightwatch/examples. Nightwatch is a Node.js framework that automates browsers through the W3C WebDriver API. This guide walks through the first run, a useful test, local configuration, and when to move tests to a remote browser grid.

1. Check Node.js and browser prerequisites

Install a supported Node.js release and one desktop browser, such as Chrome. Nightwatch’s getting-started guide has stated support for Node versions above v14.20, but this minimum is version-sensitive; check the current Nightwatch getting-started guide before choosing a runtime for a new project.

For a local Chrome run, Nightwatch needs a compatible ChromeDriver. The setup wizard can configure a runner and browser, and Nightwatch documents installing chromedriver for local Chrome use. Browser and driver compatibility depends on your environment; follow the current ChromeDriver setup guide if you manage the driver directly.

2. Scaffold a Nightwatch project

From a new project directory or an existing project, run:

npm init nightwatch

The initializer is interactive. Choose end-to-end testing, your preferred language and runner, an installed browser, a test folder, the base URL your app will use, and local or remote execution. For a first run, keep the setup small: one desktop browser and a local development URL. The wizard creates nightwatch.conf.js and sample tests.

If starting from a new directory, create it and enter it before running the initializer:

mkdir nightwatch-demo
cd nightwatch-demo
npm init nightwatch

Use the same Node package manager and project conventions as the application if you are adding Nightwatch to an existing codebase.

3. Run the generated example

Run the example tests generated by the setup:

npx nightwatch ./nightwatch/examples

Nightwatch prints test and assertion results in the terminal. The getting-started flow also reports the location of an HTML report, which you can open in a browser to review the run. If the generated example uses a different path in your chosen setup, use the path the wizard created.

4. Write a first useful browser test

A good first test checks an outcome a user can observe: a page title, a URL, visible text, or a form value. Replace the sample test with a test for a route in your application, and set url to that route or configure the base URL in the project settings.

module.exports = {
  'home page shows the expected heading'(browser) {
    browser
      .url('/')
      .assert.titleContains('Example')
      .assert.visible('main h1')
      .assert.textContains('main h1', 'Welcome')
      .end();
  }
};

This example uses Nightwatch’s browser test structure and selector-based assertions. Change the title fragment, selector, and expected text to match your app. Keep assertions tied to outcomes that matter; checking implementation details can make tests brittle when the UI changes without changing user behavior.

Choose between assert and verify

Use assert when a failed check should stop the test immediately. Use verify when you want the test to record a failed check and continue with later checks. For example, a missing prerequisite element may make later interactions meaningless, while several independent content checks may still be useful in one run. See the Nightwatch assertions guide for the available assertion APIs.

Find elements and choose stable selectors

Nightwatch supports selector-based element lookup and assertions. Prefer selectors that reflect stable application contracts, such as accessible roles, labels, or dedicated test attributes, where your application provides them. Avoid selectors tied to generated class names or incidental layout when a stable selector is available. A selector that matches no element usually means the page is not at the expected state, the selector is wrong, or the element has not appeared yet.

5. Configure local Chrome explicitly

The setup wizard is the easiest starting point. If you need to manage the local environment yourself, Nightwatch documents installing the framework and ChromeDriver, then defining a chrome-local environment with Chrome as the browser.

npm install --save-dev nightwatch chromedriver

In nightwatch.conf.js, configure a local environment along these lines, adapting details to the configuration format and driver setup used by your installed Nightwatch version:

module.exports = {
  src_folders: ['tests'],
  test_settings: {
    default: {
      launch_url: 'http://localhost:3000'
    },
    'chrome-local': {
      webdriver: {
        start_process: true,
        server_path: require('chromedriver').path,
        port: 9515
      },
      desiredCapabilities: {
        browserName: 'chrome'
      }
    }
  }
};

Run tests against that environment with:

npx nightwatch --env chrome-local

Nightwatch environments let you define target-specific settings while sharing defaults. WebDriver process management uses settings such as start_process and a driver server_path. Configuration keys and supported formats can change across releases, so compare your config with the current environment guide and WebDriver settings reference.

6. Understand the main configuration choices

Choice	What it controls	Beginner starting point
Test folder	Where Nightwatch discovers test files	Keep the generated folder initially
Base URL	The application host used by tests	Use the local development server URL
Environment	Browser, WebDriver, and target-specific settings	One local Chrome environment
WebDriver process	Whether Nightwatch starts the driver and where it is located	Use the generated setup or documented local driver settings
Assertions	Whether a failed check stops a test or allows it to continue	Use `assert` for dependent checks; `verify` for independent checks
Execution location	Local browser versus a remote Selenium or cloud service	Run locally until broader coverage is needed

Nightwatch has broader configuration options; consult the settings reference when you need to change defaults. Keep configuration focused on actual project needs so that a local first run stays understandable.

7. Expand to other browsers or remote execution

Nightwatch documents Chrome, Firefox, Safari, and Edge, as well as execution through Selenium Grid and cloud browser services. Local execution is usually the simplest way to begin. Consider a remote grid when you need browser and operating-system combinations that are not available on a developer’s machine, or when distributed execution is part of your team’s workflow.

Remote providers require provider-specific capabilities and credentials. Nightwatch’s guide includes examples for BrowserStack, Sauce Labs, and TestingBot; use the provider’s current documentation for account setup, supported capabilities, secrets, and pricing. Avoid committing access credentials to source control. See Nightwatch’s cloud provider guide.

8. Troubleshoot common first-run failures

Symptom	Likely cause	What to check
`npm init nightwatch` does not start	Node.js or npm is missing, or the runtime does not meet the current requirement	Check `node --version` and `npm --version`, then verify the current Nightwatch requirements.
Chrome fails to launch or the session cannot be created	ChromeDriver is missing, not found, or incompatible with the installed browser	Review the driver path and browser/driver compatibility instructions in the ChromeDriver guide.
Connection refused by WebDriver	The driver process is not running, the configured port is occupied, or process management settings do not match the setup	Check `start_process`, `server_path`, the configured port, and the WebDriver startup output.
Test cannot reach the application	The development server is stopped or the base URL is wrong	Start the app, open its URL directly, and compare it with `launch_url` or the configured base URL.
Element assertion fails immediately	The selector is incorrect, the element is absent, or the page has not reached the expected state	Confirm the page URL and selector in the browser, then use the appropriate wait or synchronization behavior documented for your Nightwatch version.
Tests pass locally but fail on a remote provider	Different browser versions, operating systems, timing, capabilities, or environment variables	Compare provider capabilities and logs, remove assumptions about local machine state, and keep credentials in environment-specific secret storage.
Report path is unclear	The report location is printed by the selected runner or setup	Read the end of the command output and open the reported HTML file in a browser.

9. Keep runs reliable and costs predictable

Start with one browser. Add browser and OS combinations when the project has a concrete coverage need.
Assert user-visible outcomes. Stable checks are easier to maintain when UI internals change.
Make environment assumptions explicit. Use environment-specific settings for local and remote targets rather than relying on a developer’s machine defaults.
Handle secrets carefully. Store cloud provider keys outside committed configuration.
Account for remote service costs. Remote grids and cloud providers may have their own pricing and limits; check current provider terms before scaling parallel runs.

Browser tests exercise real browser behavior and generally require more setup and runtime resources than a static page check. Keep the end-to-end suite focused on important user flows; use the smallest number of browser environments that gives the coverage the team needs.

10. Or skip the browser setup

For a website screenshot, you can use the ScreenshotNeo screenshot API instead of setting up a browser automation project. Its API returns an image or PDF from one GET request. See the ScreenshotNeo API documentation for parameters and response details.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Is Nightwatch.js only for end-to-end testing?

This getting-started path focuses on browser-based end-to-end tests. The initializer asks you to choose testing types and setup options, so select the mode that fits your project and consult the current guide for its supported workflow.

Do I need Selenium Grid to start?

No. A local browser is enough for a first run. Grid or cloud execution is an optional step for broader browser and operating-system coverage or remote execution needs.

Can I use a screenshot API instead of Nightwatch?

A screenshot API can capture a page as an image or PDF, but it does not replace an end-to-end test that interacts with your app and asserts user behavior. Choose based on whether you need a visual capture or an automated browser test.