Mocha Adapter for Nightwatch.js

Common errors

• Error: The `nightwatch` dependency is not installed.

  cause Nightwatch.js is either missing from the project or installed at an incompatible version that the adapter cannot detect.
  fix Ensure `nightwatch@~0.9.12` is explicitly installed in your project: `npm install nightwatch@~0.9.12`.

• ReferenceError: describe is not defined

  cause The Mocha test runner environment has not been correctly initialized, preventing global test functions from being exposed.
  fix Verify that `test_runner.type` is explicitly set to 'mocha' in your `nightwatch.conf.js` file and that `mocha@~3.2.0` is installed as a dependency.

• TypeError: browser.url is not a function

  cause This error or similar 'browser' object method failures typically indicate an incompatibility between the old Nightwatch.js API expected by the adapter and a newer Nightwatch.js version being used.
  fix This adapter strictly supports Nightwatch.js <=0.9.12. Ensure `nightwatch@~0.9.12` is installed and that your `nightwatch.conf.js` correctly configures the Mocha test runner for this specific version.

Warnings

• breaking This package is incompatible with Nightwatch.js versions 1.x, 2.x, or 3.x and relies on the severely outdated Nightwatch.js ~0.9.12 API.
  Fix: Migrate your test suite to use Nightwatch.js's native test runners (e.g., Cucumber.js, Jest) or find a currently maintained adapter if available. Downgrading Nightwatch.js to a pre-1.0 version is not recommended.
• breaking This adapter is not compatible with Mocha versions 4.x and above, as it was designed for Mocha ~3.2.0. Significant breaking changes occurred in later Mocha releases.
  Fix: Downgrade Mocha to a compatible version (e.g., `mocha@3.2.0`) if you must use this adapter. Otherwise, rewrite your tests for a modern test runner.
• gotcha The `mocha-nightwatch` package is effectively abandoned, with its last update over five years ago. It is highly unlikely to function correctly with modern Node.js versions, browser versions, or current versions of its dependencies.
  Fix: Avoid using this package for any new development. For existing projects, prioritize migrating to a actively maintained testing framework and setup.
• gotcha The package requires Node.js >=0.10.x, an end-of-life Node.js release. Running it on modern Node.js LTS versions (e.g., v14+) will likely result in runtime errors or unexpected behavior due to API changes and deprecations.
  Fix: This package is not compatible with modern Node.js. If forced to use it, you would need to run an extremely old, unsupported Node.js version, which is a significant security risk and not recommended.

Install

• npm install mocha-nightwatch npm
• yarn add mocha-nightwatch yarn
• pnpm add mocha-nightwatch pnpm

Imports

• describe
  wrong:

  import { describe } from 'mocha-nightwatch'

  correct:

  /* Used globally or implicitly by Mocha test runner */

  While 'describe' is a core Mocha function, it's typically available globally in a Mocha test environment or implicitly provided by the test runner, not directly imported from `mocha-nightwatch`. This package facilitates Mocha's usage with Nightwatch.
• it
  wrong:

  import { it } from 'mocha-nightwatch'

  correct:

  /* Used globally or implicitly by Mocha test runner */

  Similar to 'describe', 'it' is a Mocha global for defining individual test cases and is made available by the test runner setup, not directly through an import from `mocha-nightwatch`.
• browser
  wrong:

  import { browser } from 'mocha-nightwatch'

  correct:

  /* Injected as a parameter into test functions */

  The 'browser' (or 'client') object is a Nightwatch.js global or an argument passed to test functions, providing access to browser commands and assertions. It's not a direct import from `mocha-nightwatch` but a core Nightwatch feature used within tests that this adapter enables.

Quickstart

Demonstrates how to configure Nightwatch.js to use Mocha as its test runner and write a basic end-to-end test. Ensure 'chromedriver' and 'nightwatch@~0.9.12' are installed.

// nightwatch.conf.js
const chromedriver = require('chromedriver');

module.exports = {
  src_folders: ["test"],
  output_folder: "reports",
  globals_path: "globals.js",

  test_runner: {
    type: "mocha",
    options: {
      ui: "bdd",
      reporter: "spec",
      timeout: "60000"
    }
  },

  webdriver: {
    start_process: true,
    port: 9515,
    server_path: chromedriver.path, // Requires 'chromedriver' package
    cli_args: [
      "--verbose"
    ]
  },

  test_settings: {
    default: {
      launch_url: "http://localhost",
      desiredCapabilities: {
        browserName: "chrome",
        javascriptEnabled: true,
        acceptSslCerts: true,
        chromeOptions: {
          args: ["--headless"]
        }
      }
    }
  }
};

// test/example.spec.js

describe('Google Homepage Test', function() {
  it('should have a title', function(browser) {
    browser
      .url('https://www.google.com')
      .waitForElementVisible('body', 1000)
      .assert.titleContains('Google')
      .end();
  });

  it('should find the search input', function(browser) {
    browser
      .url('https://www.google.com')
      .waitForElementVisible('input[name="q"]', 1000)
      .assert.elementPresent('input[name="q"]')
      .end();
  });
});