Nightwatch.js

Nightwatch is an integrated testing framework powered by Node.js and the W3C Webdriver API. It supports a wide range of testing types within a single framework:

• End-to-End (E2E) Testing: Testing web applications and websites.
• Component Testing: Testing components in isolation (React, Vue, Angular, or Storybook) by mounting them in the browser.
• Mobile App Testing: Native mobile application testing on Android and iOS via Appium.
• API Testing: Includes request/response assertions, HTML report integration, and mock server support.
• Visual Regression Testing (VRT): An in-house plugin that captures screenshots, compares them against baselines, generates difference reports, and allows for change approval.
• Accessibility Testing: Uses the aXe-core plugin to perform ~90 types of accessibility tests for WCAG compliance.
• Node.js Unit Testing: Support for testing Node.js logic.

If you need to perform operations (like updating capabilities) before the browser starts, set auto_start_session: false in your test_runner.options. You can then manually launch the browser using this.client.launchBrowser() within a Cucumber Before hook.

Important: When manually launching the browser, you must assign the result to this.browser so Nightwatch can close it automatically, or call .quit() in your Cucumber After() hooks.

// Configuration
test_runner: {
  type: 'cucumber',
  options: {
    feature_path: 'examples/cucumber-js/*/*.feature',
    auto_start_session: false
  }
}

// _extra_setup.js
const {Before} = require('@cucumber/cucumber');

Before(async function(testCase) {
  if (!this.client) {
    console.error('Nightwatch instance was not created.');
    return;
  }

  this.client.updateCapabilities({
    testCap: 'testing'
  });

  this.browser = await this.client.launchBrowser();
});

# Run with the extra setup file
$ nightwatch examples/cucumber-js/features/step_definitions --require {/full/path/to/_extra_setup.js}

The TestSuite class is the core engine responsible for managing the lifecycle of a test suite in Nightwatch.js. It orchestrates the execution of test cases, manages hooks (before, after, beforeEach, afterEach), handles retries, manages the browser session via a client, and coordinates reporting.

Key responsibilities include:

• Lifecycle Management: Running global hooks, suite-level hooks, and individual test cases.
• Session Control: Creating and terminating browser sessions.
• Error Handling: Distinguishing between assertion errors and unexpected exceptions, and deciding whether to skip subsequent tests or take screenshots.
• Retries: Implementing both test-level and suite-level retry logic.
• Global API Injection: Automatically injecting useful globals like browser, expect, By, and element into the global scope (unless disabled via configuration).

const TestSuite = require('./lib/testsuite/index.js');

// Note: In a standard Nightwatch run, this is managed internally by the runner.
// The constructor requires a complex configuration object:
// const suite = new TestSuite({
//   modulePath: 'path/to/test.js',
//   modules: ['path/to/test.js'],
//   settings: { ... },
//   argv: { ... }
// });

The Concurrency class is used by Nightwatch to manage parallel test execution using either child processes or worker threads. It handles the orchestration of multiple test environments and modules, managing a pool of workers to optimize resource usage based on the available CPU cores or the test_workers.workers setting.

Key behaviors:

• Child Processes: Uses use_child_process to spawn separate OS processes for tests.
• Worker Processes: Uses worker threads for parallel execution when testWorkersEnabled is true.
• Environment Management: Can run multiple test environments (e.g., different browsers or configurations) in parallel.
• Exit Codes: Tracks a globalExitCode which is updated if any child process returns a non-zero exit code.

const Concurrency = require('./lib/runner/concurrency/index.js');

// Example initialization
const concurrency = new Concurrency(
  { 
    use_child_process: true, 
    test_workers: { workers: 4 } 
  }, 
  process.argv,
  true // isTestWorkerEnabled
);

The Element class is the base class for all element representations in Nightwatch. It encapsulates how an element is located (via selectors, WebElement objects, or webElementId) and how it should behave during test execution (timeouts, retries, error handling).

Key properties include:

• selector: The string or object used to find the element.
• index: An optional numeric index used for filtering results (e.g., when selecting the Nth element).
• locateStrategy: Determines how the element is resolved (e.g., standard or Recursion).
• abortOnFailure: Boolean indicating if the test should stop if this element is not found.
• suppressNotFoundErrors: Boolean indicating if errors should be silenced when the element is missing.
• timeout and retryInterval: Control the timing of element resolution.

When an element is defined in a Page Object, it is typically instantiated as an Element subclass.

// Conceptual representation of an Element definition
const myElement = {
  selector: '.my-class',
  index: 0,
  timeout: 5000,
  abortOnFailure: true
};