nightwatchjs/nightwatch

This system is Nightwatch.js, a browser automation and end-to-end testing framework for web and mobile applications. It provides a comprehensive API for controlling browsers via WebDriver, supporting features like page objects, custom commands, and assertions. The framework integrates with multiple test runners including Mocha and Cucumber, and offers extensive reporting capabilities such as HTML, JSON, and accessibility audits.

59 changes.

This period involved a comprehensive architectural overhaul of the Nightwatch framework, introducing a new tree-based command queue, a rewritten HTTP client, and a modular API structure. The work established the foundation for Nightwatch v3 by implementing robust async/await support, parallel execution via worker threads, and integration with external runners like Mocha and Cucumber. Extensive test infrastructure and example suites were added to validate the new core components and ensure backward compatibility.

66 changes.

This period focused on the foundational rewrite of Nightwatch 2.0, replacing the legacy transport layer with a custom Selenium WebDriver integration and restructuring the API loader, assertion engine, and element location logic into modular, class-based systems. The work introduced extensive new features including ES6 async/await support, Cucumber.js integration, accessibility reporting, and multiple output reporters, while simultaneously expanding test coverage to validate the new architecture across diverse environments and error scenarios.

56 changes.

This period focused on the development of the v3.0 chainable element API, introducing scoped queries, assertions, and wait capabilities alongside comprehensive TypeScript type definitions. It also expanded the framework's capabilities with new namespaces for network mocking, window management, and document execution, while integrating Cucumber.js support and refactoring BrowserStack transport.

5 changes.

This period focused on expanding the test suite by adding sample tests for specific API behaviors, including password redaction, element presence checks, and error suppression. It also introduced tests for async tree event handling and created sample scripts to validate reporting functionality for test statistics and status.

This change introduces a suite of new Appium-specific API commands in the \lib/api/protocol/appium\ directory, enabling more direct control over mobile device state and hybrid app contexts. Users can now manage application contexts with \getContext\, \getContexts\, and \setContext\ for hybrid app testing, and query device details via \getCurrentActivity\ and \getCurrentPackage\. Device interaction is expanded with \getGeolocation\/\setGeolocation\ for location simulation, \getOrientation\/\setOrientation\ for screen rotation, and \pressKeyCode\/\longPressKeyCode\ for raw key events. Additional utilities include \hideKeyboard\, \isKeyboardShown\, and \resetApp\ to streamline common mobile testing workflows.

lib/api/protocol/appium · high confidence

New page object examples have been added to the Google examples directory to demonstrate handling of consent modals and search result navigation. The \consent.js\ file provides a page object for managing Google's consent settings (search customization, YouTube history, ad personalization) with commands to turn off options and confirm. The \search.js\ file defines a page object for the Google search page, including elements for the search bar, submit button, and a consent modal section with a reject-all button. The \searchResults.js\ file adds a page object for the search results page, featuring a navigation menu section with commands to check if specific product tabs (Maps, Videos, Images, News) are selected.

examples/pages/google · high confidence

A new page object file (nightwatchFeatures.js) was added to the examples/pages directory to support feature reporting capabilities. This file defines commands for retrieving the count of features and specifies element selectors, including an explicit index property for the features heading element to target a specific DOM node.

examples/pages · high confidence

The Cucumber.js example project now includes a new step definition file (nightwatch.js) that maps Gherkin scenarios to Nightwatch.js browser automation commands. This enables users to run the Rijksmuseum search example using the Cucumber test runner with Nightwatch as the underlying browser driver, covering steps for navigation, cookie dismissal, search input, and title/content assertions.

_examples/cucumber-js/features/step\definitions · high confidence

New example custom commands have been added to the examples/custom-commands directory. The getElementsInList.js command allows users to retrieve elements within an Angular list by querying for attributes ending with the specified list name, while strictClick.js provides a command that waits for an element to be visible before performing a click action.

examples/custom-commands · high confidence

The examples/test-app directory now includes a sample web application and test configuration to demonstrate the new element() API. The app provides various HTML elements (inputs, buttons, images) with specific attributes and IDs to showcase locators like getByPlaceholderText, getByText, getByLabelText, getByAltText, and getByTestId, along with navigation between pages.

examples/test-app · high confidence

The \bin\ directory now contains the executable entry points for the Nightwatch CLI. The \nightwatch\ script validates the Node.js version against the requirements specified in \package.json\ before invoking the runner, ensuring compatibility. The \runner.js\ module initializes the CLI, sets up the test runner, and handles errors during startup or execution, including specific handling for ESM loading issues. Additionally, a \.gitignore\ file is added to exclude local driver binaries (such as chromedriver and selenium-server-standalone) from version control, and a survey prompt is displayed upon installation.

bin · high confidence

The repository has been initialized with the core Nightwatch.js v3 codebase, including the main entry point (index.js) that conditionally loads coverage instrumentation. Essential project configuration files have been added, such as .eslintrc (configuring ESLint for JavaScript and TypeScript with specific rules like 'prefer-const' and 'indent'), .eslintignore, and .gitignore (excluding build artifacts, logs, and environment files). Documentation and community guidelines are now present, including README.md (detailing v3 features like component testing and mobile automation), CONTRIBUTING.md, CODE\_OF\_CONDUCT.md, and LICENSE.md. Additionally, a codecov.yml file has been added to configure code coverage reporting settings.

(repo-wide) · high confidence

Nightwatch now includes built-in support for using Cucumber.js as a test runner, eliminating the need for external plugins. This change introduces the necessary setup logic to initialize Nightwatch clients within Cucumber hooks, a custom formatter to bridge Cucumber events with Nightwatch's internal event hub for reporting, and documentation on how to install and configure the integration.

lib/runner/test-runners/cucumber · high confidence

Added a new Nightwatch Inspector feature that enables interactive execution of Nightwatch commands directly from the browser. This is implemented via a new WebSocket server (listening on port 10096) and a Chrome extension that auto-opens devtools. Users can now send commands to the inspector, which executes them in a sandboxed context and returns results, facilitating a more interactive debugging and testing experience.

lib/testsuite/nightwatch-inspector · high confidence

Nightwatch now provides a comprehensive default configuration template and a robust settings management system. The \lib/settings/defaults.js\ file introduces default values for global properties (such as \abortOnElementLocateError\, \retryAssertionTimeout\, and \reuseBrowserSession\), reporter options (including \filename\_format\ for screenshots and reports), and Selenium server settings. The \lib/settings/settings.js\ module implements the logic to parse, merge, and validate these settings, supporting environment variable substitution, TypeScript configuration paths, and programmatic API initialization. This change establishes the foundation for consistent configuration handling across the test runner.

lib/settings · high confidence

Users can now write Nightwatch tests using a BDD-style describe interface, similar to Mocha, allowing for nested test suites and structured test organization. This new interface supports standard test attributes (such as tags, unitTest, and disabled) and hooks (before, after, beforeEach, afterEach) within describe blocks, providing a more flexible and readable way to structure test cases compared to the previous exports-based approach.

lib/testsuite/interfaces · high confidence

Added a new example directory demonstrating how to use Cucumber.js as an integrated test runner with Nightwatch 2. The entry includes a comprehensive README detailing configuration options (such as parallel execution and auto-start session settings), supported CLI arguments (like --tags, --format, and --retries), and instructions for custom session management. It also provides sample feature files and step definitions to illustrate basic usage, including running tests with specific workers or headless mode.

examples/cucumber-js · high confidence

The test runner now includes three new reporter implementations: an HTML reporter that generates a visual report with customizable filename and folder formats, a JSON reporter that outputs structured test results and HTTP logs to a file, and a JUnit reporter that produces XML reports compatible with CI/CD systems. These reporters provide users with additional options for viewing and integrating test results.

lib/reporter/reporters · high confidence

The \lib/api/web-element/commands\ directory now implements the new \ScopedWebElement\ API, providing a chainable interface for DOM interactions. This update introduces a wide range of new commands including element finding (\find\, \findAll\, \findByLabelText\, \findByRole\, \findByText\, \findByAltText\, \findByPlaceholderText\), interactions (\click\, \check\, \uncheck\, \clear\, \dragAndDrop\, \doubleClick\, \clickAndHold\), and property retrieval (\getAttribute\, \getProperty\, \getText\, \getRect\, \getShadowRoot\, \getAccessibleName\, \getAriaRole\, \isActive\, \isEnabled\, \isPresent\, \isVisible\, \isSelected\). It also adds navigation helpers (\getParentElement\, \getFirstElementChild\, \getLastElementChild\, \getNextElementSibling\, \getPreviousElementSibling\) and debugging tools (\inspectInDevTools\).

lib/api/web-element/commands · high confidence

The reporter now includes an AxeReport class that aggregates and prints accessibility violations and passes directly in the terminal. It displays a summary table of violations (ID, impact, description, node count) and, when enabled, detailed per-node targets and HTML snippets; it also prints a passes table with rule details and node counts. The global reporter automatically invokes this accessibility output after test suites, and the reporter API exposes setAxeResults/printA11Report to integrate axe data into test results.

lib/reporter · high confidence

Added new client commands under the \alerts\ namespace to interact with JavaScript alert dialogs. Users can now use \browser.alerts.accept()\ to confirm alerts, \browser.alerts.dismiss()\ to cancel them, \browser.alerts.getText()\ to retrieve the alert message, and \browser.alerts.setText()\ to input text into prompt dialogs. These commands support both callback and async/await syntax.

lib/api/client-commands/alerts · high confidence

This change introduces new assertion capabilities for the scoped element API, adding \element-assertions.js\ and \value-assertions.js\ alongside \elements-assertions.js\. Users can now chain assertions like \present\, \visible\, \enabled\, \hasClass\, \hasAttribute\, and \customScript\ on scoped elements, with specific handling to prevent unhandled promise rejections during test execution. Additionally, value assertions (\contains\, \equals\, \matches\) are provided for scoped values, enabling direct verification of element text or attribute values within the new chainable syntax.

lib/api/web-element/assert · high confidence

The \lib/api/web-element\ module introduces a new chainable element API (\browser.element.find()\) that provides a consistent, promise-based interface for locating and interacting with DOM elements. This new API includes a \waitUntil\ command, allowing users to wait for specific element states (such as 'visible', 'present', or 'enabled') before proceeding. To improve usability, the API also exposes a set of shorter aliases for common commands, including \.text()\, \.attr()\, \.prop()\, \.rect()\, and \.isDisplayed()\. The implementation ensures that these new commands and assertions are available on page objects and supports chaining for more readable test scripts.

lib/api/web-element · high confidence

Users can now access a new \document\ namespace on the browser object to interact with the current page's document context. This change introduces four new commands: \document.executeScript\ (with aliases \execute\ and \document.execute\) for injecting and running synchronous JavaScript, \document.executeAsyncScript\ (with aliases \executeAsync\ and \document.executeAsync\) for asynchronous script execution, \document.injectScript\ for loading external scripts by URL, and \document.source\ (with alias \document.pageSource\) for retrieving the serialized HTML source of the current page. These commands provide a structured way to perform document-level operations, supporting both callback and async/await patterns.

lib/api/client-commands/document · high confidence

The examples directory now includes a sample globals module (globalsModule.js) demonstrating global settings like abortOnAssertionFailure and hook definitions, a sample globals configuration file (globals.json) for environment-specific values, a custom assertion example (testCustomAssertion.js) showing how to define and use custom assertions, and a TypeScript configuration file (tsconfig.json) to support TypeScript examples.

examples · high confidence

A new \.network\ namespace has been introduced under \lib/api/client-commands/network\ to provide granular control over browser network interactions. This change adds three specific client commands: \network.captureRequests\ (aliased as \.captureNetworkRequests\) to log outgoing network calls as they occur, \network.mockResponse\ (aliased as \.mockNetworkResponse\) to intercept specific URLs and return custom mock responses, and \network.setConditions\ (aliased as \.setNetworkConditions\) to emulate network settings like latency and throughput. These commands are available since version 2.2.0 and are restricted to Chrome and Edge drivers, utilizing the CDP protocol for implementation.

lib/api/client-commands/network · high confidence

The library now exposes a \createClient\ function that allows users to programmatically instantiate and configure a Nightwatch browser instance without relying on the CLI. This API accepts options such as \headless\, \silent\, \output\, \useAsync\, \env\, \browserName\, \timeout\, \parallel\, \reporter\, \globals\, and \config\. It returns an object with methods to update capabilities, run global before/after hooks, launch the browser (with an option to skip loading Nightwatch APIs), and perform cleanup. This enables integration with external build runners and custom test orchestration logic.

lib · high confidence

Nightwatch now exposes a public API entry point at \api/index.js\ that allows users to programmatically import and extend core commands, such as \Quit\, \findElement\, and \findElements\. This change enables developers to create custom command implementations that inherit from and enhance the built-in functionality, as documented in the newly added \api/README.md\.

api · high confidence

This change introduces a comprehensive set of new client commands under the \browser.window\ namespace, allowing users to manage browser windows and tabs directly. The new API includes \window.open\ to open new tabs or windows, \window.close\ to close the current one, and \window.switchTo\ to switch focus between them using window handles. It also adds \window.getAllHandles\ and \window.getHandle\ for identifying available windows, along with \window.maximize\, \window.minimize\, \window.fullscreen\, \window.getSize\, \window.getPosition\, and \window.getRect\ to control window dimensions and position. Additionally, \window.setSize\, \window.setPosition\, and \window.setRect\ allow users to resize and reposition windows programmatically. These commands support both callback and async/await styles, enabling more robust automation of multi-window workflows.

lib/api/client-commands/window · high confidence

The BrowserStack integration has been restructured from a single monolithic file into distinct modules: a base \BrowserStack\ class handling core authentication, settings adaptation, and session status updates; an \Automate\ class for standard Selenium automation; an \AutomateTurboScale\ class for TurboScale-specific API endpoints and session reason reporting; and a new \AppAutomate\ class that enables uploading mobile apps to BrowserStack's App Automate service. This change introduces support for uploading apps via \appUploadPath\ or \appUploadUrl\ capabilities and ensures all API calls strictly use port 443 for secure connections.

lib/transport/selenium-webdriver/browserstack · high confidence

Element commands now support Appium-specific locate strategies (such as accessibility id, Android UIAutomator, iOS predicate string, and iOS class chain) when running against Appium clients. This is implemented via a new \AppiumLocator\ class and a \NightwatchLocator\ factory that routes element location requests to the appropriate strategy handler based on the client type, allowing users to locate mobile elements using native Appium selectors.

lib/element · high confidence

The assertion API in lib/api/assertions has been restructured to introduce a new base class (\_assertionInstance) and a suite of new assertions including textContains, textEquals, titleContains, titleEquals, hasAttribute, hasClass, hasDescendants, enabled, and selected. Several legacy assertions such as containsText, cssClassPresent, cssClassNotPresent, hidden, and title have been marked as deprecated in favor of the new equivalents (e.g., textContains, hasClass, not.visible, titleEquals). All element-based assertions now utilize the suppressNotFoundErrors option to prevent errors when elements cannot be located, and the API supports negation via the .not syntax.

lib/api/assertions · high confidence

A pre-commit hook has been added to the repository to automatically run lint-staged on files staged for commit. This ensures that code quality checks are performed locally before changes are committed, helping to catch linting errors early in the development workflow.

.husky · high confidence

The \lib/utils\ module has been restructured to provide more actionable feedback and better support for mobile platforms. Error handling is enhanced with \addDetailedError\ and \beautifyStackTrace\, which now detect common configuration mistakes (such as loading conflicting plugins or using the browser object too early) and display relevant source code snippets in the terminal. Mobile testing support is expanded via \mobile.js\, which introduces specific error classes like \AndroidHomeError\ and \RealIosDeviceIdError\ with clear setup instructions, and \locatestrategy.js\ now includes Appium-specific strategies (Accessibility ID, Android UIAutomator, iOS Predicate String/Class Chain). Additionally, \requireModule.js\ improves ES6 module compatibility, and \chalkColors.js\ migrates the color library from \colors.js\ to \chalk.js\.

lib/utils · high confidence

A new \BaseAssertion\ abstract class has been added to the assertion framework to serve as the foundation for all Chai-based assertions. This class standardizes how assertions interact with the Nightwatch client, handling core lifecycle methods like \executeCommand\, \elementFound\, and \elementNotFound\, while managing internal state such as timeouts, retry intervals, and custom error messages. This structural change enables more consistent behavior across different assertion types and supports the integration of third-party libraries by providing a unified interface for assertion execution and result processing.

lib/api/expect/assertions · high confidence

The CLI runner now uses a new \ArgvSetup\ class (replacing the deprecated \optimist\ library) to parse command-line arguments, enabling more robust handling of flags and options. Additionally, a new default configuration template (\nightwatch.conf.ejs\) is generated when no config file is found, providing pre-configured settings for Firefox, Chrome, Edge, and Safari, along with support for plugins like Storybook and React.

lib/runner/cli · high confidence

The test runner now uses a dedicated logging module (\lib/utils/logger\) that provides structured, color-coded console output for LOG, INFO, WARN, and ERROR severities, including ISO timestamp support and object inspection. It introduces a \LogSettings\ class to control output behavior, such as enabling/disabling logs, toggling timestamp formats, and configuring HTTP request/response data visibility for the HTML reporter. Raw HTTP logs are now escaped to prevent HTML injection issues.

lib/utils/logger · high confidence

The TypeScript definitions in the \types/\ directory have been completely rewritten and upgraded to support Nightwatch v3.0.0, replacing the previous DefinitelyTyped-based definitions. This update introduces comprehensive type coverage for the new Element API (including aliases like \.attr()\, \.prop()\, and \.text()\), Page Objects, and Expect assertions. It also adds specific type interfaces for browser-specific configurations (such as \ChromeOptions\), custom commands, and global test settings, ensuring stricter type safety and better IDE autocomplete for users migrating to the latest version.

types · high confidence

The concurrency runner has been rewritten to support two distinct parallel execution modes: traditional child processes and modern Node.js worker threads (via the Piscina library). Users can now choose the execution strategy via the \use\_child\_process\ setting. The worker thread mode introduces new configuration options, including \test\_workers.node\_options\ to pass Node.js flags to workers, \parallel\_process\_delay\ to stagger worker starts, and \disable\_output\_boxes\ to toggle the visual formatting of test results. This change also ensures environment variables and CLI arguments are correctly propagated to parallel workers, and disables parallelism when Safari environments are detected to maintain stability.

lib/runner/concurrency · high confidence

The service builder implementations in lib/transport/selenium-webdriver/service-builders have been rewritten to introduce a new base class and dedicated builders for Chrome, Edge, Firefox, Safari, Appium, and Selenium Server. This change adds explicit support for Selenium Server 4 (including standalone/grid modes) and aligns with the removal of bundled driver binaries by relying on external drivers or Selenium Manager. Users benefit from improved logging controls (allowing verbose logging to be disabled for Chrome, Edge, and Firefox), better handling of driver paths, and a more robust service lifecycle management via the new base service.

lib/transport/selenium-webdriver/service-builders · high confidence

The assertion logic in lib/assertion has been restructured into a new modular system (AssertionRunner, NightwatchAssertion, and NightwatchAssertError). This change improves user experience by providing more actionable error messages that clearly display expected versus actual values, including stringified objects for better readability. Additionally, the system now correctly detects and reports 5xx internal server errors from remote Selenium/WebDriver services, ensuring that test failures due to server issues are communicated clearly rather than being treated as generic assertion failures.

lib/assertion · high confidence

The element locating mechanism in \lib/element/locate\ has been restructured to use a new recursive lookup architecture. New files \recursive-lookup.js\, \single-element-by-recursion.js\, and \elements-by-recursion.js\ introduce base and specialized classes that handle nested element searches by chaining \elementIdElement\ and \elementIdElements\ transport actions. This change replaces previous inline or monolithic locating logic with a modular, promise-based recursive approach, affecting how single and multiple elements are found within page object sections and nested structures.

lib/element/locate · high confidence

The expect API has been restructured to use a new internal architecture based on \BaseExpect\ and \BaseAssertion\ classes, replacing the previous implementation. This change introduces dedicated command classes for \cookie\, \title\, \url\, \element\, \elements\, and \component\, each handling their specific transport actions and promise resolution logic. The \expect.cookie\ command now correctly retrieves and processes cookie values, addressing previous issues where it returned undefined. The \expect.elements\ command now properly handles cases where elements are not found, ensuring the count assertion returns 0 instead of failing unexpectedly. Additionally, the \expect.title\ command has been updated to fix promise handling issues that previously caused unhandled rejections.

lib/api/expect · high confidence

The internal implementation of element assertions (such as .present, .visible, .enabled, .value, .attribute, and .text) has been restructured from a monolithic or mixed-style codebase into a consistent, modular class hierarchy. Each assertion now extends a shared base class (\_element-assertion.js) that standardizes protocol action execution, retry logic, and error handling. This change ensures that all element assertions behave uniformly, particularly regarding how they locate elements, handle retries for transient failures, and format error messages, providing a more stable and predictable experience when using browser.expect.element() chains.

lib/api/expect/assertions/element · high confidence

The protocol command implementations in \lib/api/protocol\ have been restructured to inherit from a new \ProtocolAction\ base class (\\_base-action.js\). This change centralizes common logic for element validation, transport interaction, and error reporting, while introducing a standardized \elementCommandToActionMap\ to handle element and element-id lookups. Additionally, several legacy JSON Wire Protocol commands (such as \keys\, \mouseButtonClick\, and \elementIdLocation\) are now explicitly marked as deprecated in favor of the newer Selenium User Actions API and W3C WebDriver standards.

lib/api/protocol · high confidence

The transport module has been restructured to integrate with the selenium-webdriver library, replacing previous implementation details. This change introduces a TransportFactory that dynamically selects the appropriate driver (Chrome, Firefox, Safari, Edge, or IE) based on configuration or CLI flags, while also supporting connections to Selenium Server, Appium, and BrowserStack (including TurboScale). Users benefit from improved browser compatibility, better error handling for protocol errors, and the ability to use standard Selenium capabilities objects in their configuration.

lib/transport · high confidence

The \lib/transport/selenium-webdriver\ module has been completely rewritten to replace the previous \selenium-webdriver\ integration with a custom transport layer. This change introduces a new \TransportActions\ class to handle protocol actions and error handling, a custom \HttpClient\ to manage HTTP requests, and dedicated transport classes for specific browsers (Chrome, Firefox, Edge, Safari) and services (Selenium Server, Appium). The new architecture also adds support for Chrome DevTools Protocol (CDP) connections, network mocking, and improved session management, fundamentally changing how Nightwatch communicates with browser drivers.

lib/transport/selenium-webdriver · high confidence

The internal mechanism for loading API commands, assertions, and page objects has been restructured into a modular loader system. This change introduces dedicated loaders for different command types (commands, assertions, elements, expect, ensure, plugins, and page objects) and a base loader for shared logic. Key behavioral updates include the introduction of a new \element()\ API with improved chainable locator syntax, the addition of \.not\ assertion negation support, and the implementation of an \ensure\ API based on Selenium's \until\ conditions. The system now better handles TypeScript file loading, ESM support for globals and custom commands, and improved error handling for unhandled rejections in async tests.

_lib/api/\loaders · high confidence

The client API commands have been reorganized into a structured \lib/api/client-commands\ directory, introducing a \ClientCommand\ base class to standardize promise handling and result reporting. This change introduces namespaced command groups, such as \cookies\ (for \get\, \set\, \delete\) and \logs\ (for \getSessionLog\, \captureBrowserConsoleLogs\), while marking the legacy top-level commands (e.g., \getCookie\, \getLog\) as deprecated in favor of their new counterparts. Additionally, new capabilities include a \debug\ command that provides an interactive REPL interface for real-time debugging and \axeInject\/\axeRun\ commands for accessibility testing.

lib/api/client-commands · high confidence

The API loading mechanism has been refactored into a new \ApiLoader\ class that orchestrates the initialization of commands, assertions, page objects, and plugins. This change introduces support for loading plugins (including the default \nightwatch-axe-verbose\ plugin) and defines specific namespaces for assertions (\assert\/\verify\) and expectations (\expect\/\should\). It also establishes the infrastructure for within-context queries and browser-specific APIs (Chrome/Firefox), while maintaining the existing proxy-based API interface for negation (\.not\) and command execution.

lib/api · high confidence

The core test execution engine has been replaced with a new tree-based command queue (lib/core/queue.js) and an asynchronous execution tree (lib/core/asynctree.js). This change introduces a structured node hierarchy for commands, enabling more robust handling of nested commands, custom commands, and integration with various test runners (Mocha, Cucumber, foreign runners). It specifically improves promise resolution and rejection logic for ES6 async/await tests, fixes issues with the command queue hanging or clearing incorrectly on failures, and ensures proper error propagation and session cleanup. The new architecture also supports better debugging, step-over capabilities, and more accurate stack traces for test failures.

lib/core · high confidence

The element command implementation in \lib/api/element-commands\ has been completely rewritten to use a new base class structure (\\_baseElementCommand.js\ and \\_waitFor.js\), introducing support for async/await and improved error handling. This update adds several new mouse interaction commands (\clickAndHold\, \rightClick\, \releaseMouseButton\) and DOM navigation commands (\getFirstElementChild\, \getLastElementChild\, \getNextSibling\, \getPreviousSibling\). It also introduces new accessibility inspection commands (\getAccessibleName\, \getAriaRole\) and state manipulation commands (\check\, \uncheck\, \clearValue\, \setAttribute\). Existing commands like \click\, \doubleClick\, and \getAttribute\ have been refactored to align with the new architecture, and \waitForElement\ commands now have a dedicated base class for better consistency.

lib/api/element-commands · high confidence

The page object implementation has been completely refactored to improve reliability and usability. The new \BaseObject\ and \CommandWrapper\ classes provide a more robust foundation for creating page objects and sections, ensuring that commands and assertions are correctly wrapped and chained. Key improvements include better support for ES6 async/await in page object commands, fixed handling of nested elements within sections using recursion, and enhanced error messages when overwriting existing methods. The \navigate\ command now properly validates URLs and supports relative paths with a configured base URL. Additionally, the new structure allows for more flexible command definitions, including support for class-based commands and object-based selectors, while maintaining backward compatibility with existing page object definitions.

lib/page-object · high confidence

The test runner has been completely rewritten to improve stability and extensibility. A new \eventHub\ provides a centralized event system for lifecycle hooks (global, suite, and test level) and Cucumber-specific events, ensuring robust reporting and analytics integration. The runner now includes built-in support for launching and managing Android emulators via \androidEmulator.js\, enabling mobile web testing. A new \rerunUtil\ allows users to automatically re-execute failed tests from previous runs using a JSON report. Additionally, the \process-listener\ has been refactored to better handle uncaught exceptions and unhandled rejections, preventing infinite loops and ensuring proper exit codes. The core \runner.js\ and \folder-walk.js\ modules now support Mocha and Cucumber runners alongside the default Nightwatch runner, with improved source file filtering and tag matching.

lib/runner · high confidence

The test runner implementations in lib/runner/test-runners have been completely rewritten. The new Cucumber runner now targets @cucumber/cucumber, supports ESM imports via the --import flag, and enables parallel execution with workers. The Mocha runner has been updated to work with Mocha 9, supports the mochawesome and mocha-junit-reporter reporters, and handles parallel report merging. A new DefaultRunner class provides a standardized base for test execution, managing global reporting, concurrency, and session lifecycle.

lib/runner/test-runners · high confidence

The test suite execution engine has been completely rewritten to improve reliability and structure. The new \Context\ class centralizes module loading, test case tracking, and retry state management, replacing the previous ad-hoc approach. A new \TestHooks\ system explicitly manages lifecycle hooks (before/after all, before/each, and child process hooks) via dedicated classes, ensuring consistent execution order. The \Runnable\ class now handles test and hook execution with robust Promise-based state tracking, preventing unhandled rejections and ensuring the asynchronous command queue is properly cleared. Additionally, a new \SuiteRetries\ class cleanly separates test-level and suite-level retry logic, and the \GlobalsContext\ now supports async loading and proper merging of external global files. This refactoring resolves issues with parallel execution, session handling, and hook persistence.

lib/testsuite · high confidence

The internal implementation of test suite hooks (beforeAll, beforeEach, afterAll, afterEach, and child-process variants) has been rewritten to use a new BaseHook class. This change introduces more robust handling of asynchronous hook completion, including explicit support for callbacks, promises, and queue synchronization, which resolves previous issues where hooks could block the test queue or fail to trigger completion correctly when errors occurred or callbacks were omitted.

lib/testsuite/hooks · high confidence

The HTTP layer in lib/http has been completely rewritten to replace the previous external request library with a custom, built-in implementation. This change introduces support for HTTP keep-alive connections to improve performance, adds a robust retry mechanism for 5xx internal server errors, and ensures that POST/PUT requests with empty data are handled correctly. It also includes better formatting for JSON responses to handle unicode characters and improves error reporting for API commands.

lib/http · high confidence

The transport layer now uses a centralized error mapping system that translates internal error types (such as NoSuchElementError) into standardized WebDriver error codes with descriptive messages. This change ensures that users receive consistent, human-readable error explanations and, for specific issues like missing elements or frames, actionable troubleshooting steps (e.g., verifying DOM presence or checking window handles) directly in the error output.

lib/transport/errors · high confidence

The test runner now uses dedicated matcher classes to filter tests. The new \FilenameMatcher\ handles test file selection via \src\_folders\, \filter\, and \exclude\ patterns, correctly resolving relative paths against source directories. The new \TagsMatcher\ implements tag-based filtering, supporting \--tag\ (AND logic for multiple tags) and \--skiptags\ arguments, and fixes a previous issue where the \browser\ object was undefined during tag loading by defining a global placeholder.

lib/runner/matchers · high confidence

The Mocha test runner implementation has been refactored to improve reliability and error reporting. A new custom runnable execution path ensures that the last assertion error is properly reset between tests, preventing stale errors from affecting subsequent assertions. Additionally, the runner now provides clearer error output when a browser session fails to create, and allows desired capabilities and other settings to be updated before the transport and session are initialized.

lib/runner/test-runners/mocha · high confidence

Added Appium API demo tests; Added CLI runner test suite; Added ES6 async/await sample test for Selenium; Added Mocha integration test samples; Added Mocha-based example tests for Nightwatch 2; Added Nightwatch 2 API demo tests for Angular todo list; Added TypeScript sample test; Added TypeScript test infrastructure and demo test; Added async sample test suite; Added browser automation tests for the bstackdemo example; Added comprehensive type tests for Nightwatch API; Added high-level tests for the global expect() API; Added integration tests for Cucumber runner CLI arguments and scenarios; Added integration tests for Cucumber runner parallelism, formatters, and hooks; Added mock implementations for assertion loading and execution; Added mock implementations for core assertion and session components; Added mock infrastructure for assertion loading and WebDriver protocol simulations; Added page object test fixtures for command definitions and edge cases; Added protocol unit tests for API commands; Added sample Cucumber integration tests; Added sample Nightwatch test for syncnames; Added sample test case for error handling validation; Added sample test files for mixed file types; Added sample test files for report validation; Added sample test for ES6 async failure scenarios; Added sample test for ES6 async/await custom commands; Added sample test for Selenium WebDriver integration; Added sample test for XPath usage; Added sample test for browser object tagging; Added sample test for customCommandAppendResults; Added sample test for element locate errors; Added sample test for trace viewer; Added sample test suite for validation; Added sample test suites for async hooks, exclusion, and subfolder structures; Added sample test with intentional failures; Added sample tests for Chai Expect integration; Added sample tests for ES6 async/await syntax; Added sample tests for async failure handling and lifecycle hooks; Added sample tests for before hooks with commands; Added sample tests for before/after hooks and srcFolders configuration; Added sample tests for browser session reuse; Added sample tests for describe interface failures and configuration; Added sample tests for describe-based suites and unit tests; Added sample tests for skipped and duplicate test cases; Added sample tests for the new .within() command; Added sample tests for uncaught error handling; Added sample unit tests for the test runner; Added test cases for suite retry behavior; Added test coverage for Appium API demos; Added test coverage for ES6 async/await element commands; Added test coverage for ES6 async/await with getLog(); Added test coverage for async expect assertion failures; Added test coverage for command errors in demo test; Added test coverage for custom command error handling and async failures; Added test coverage for custom command features; Added test coverage for global expect API element assertions; Added test coverage for handling 5xx server errors; Added test coverage for plugin custom assertions, commands, and globals; Added test coverage for the new element API; Added test demos for element APIs, navigation, and relative locators; Added test fixture for user-file error handling; Added test fixtures for async hook timeouts and custom reporters; Added test fixtures for custom command scenarios; Added test fixtures for page object command classes; Added test fixtures for parallel execution, Cucumber integration, and global hooks; Added test for XPath usage with Page Objects; Added test for async hook unit test failure reporting; Added test for incorrect arguments in element commands; Added test for isPresent command on non-existent elements; Added test for password value redaction in setPassword; Added test for suppressNotFoundErrors in find operation; Added test for sync custom commands in parallel mode; Added test for unknown method error handling; Added test for unknown module require handling; Added test for waitForElementNotPresent status code; Added test globals for W3C commands, legacy commands, and expect assertions; Added test infrastructure and TypeScript support for custom commands; Added test page object for /other; Added tests for Actions API demo scripts; Added tests for Actions API with async perform callback; Added tests for Angular demo element handling and error scenarios; Added tests for CDP basic authentication registration; Added tests for CDP connection reset behavior; Added tests for CLI runner parallel execution modes; Added tests for Chrome API demo commands; Added tests for ES6 async/await custom commands; Added tests for Firefox and Chrome API demos; Added tests for async tree event handling in describe blocks; Added tests for autoInvoked custom command behavior; Added tests for component testing sample configurations and execution; Added tests for cookie API demo functionality; Added tests for cookie API demos; Added tests for custom command features; Added tests for custom command return function; Added tests for document namespace API commands; Added tests for element() assertion commands; Added tests for ensure API element selection and location checks; Added tests for error handling in async hook callbacks; Added tests for expect() API; Added tests for global element API and element finding in custom/page commands; Added tests for logs API commands; Added tests for namespaced API support; Added tests for navigation commands; Added tests for nested page objects; Added tests for new element API commands and waitUntil behavior; Added tests for page-object command return types; Added tests for pageSource, sendKeys, and updateValue commands; Added tests for relative locators demo; Added tests for utility functions and module loading; Added tests for verify behavior in perform blocks and failure scenarios; Added tests for web element API demos; Added tests for window management API commands; Added unit test examples for utility functions; Added unit tests for API assertions; Added unit tests for WebDriver service builders; Added unit tests for async hook failure scenarios and timeout configuration; Added unit tests for cookie API commands; Added unit tests for core Nightwatch components; Added unit tests for custom assertion implementations; Added unit tests for element selector commands and page object integration; Added unit tests for expect element assertions; Added unit tests for index module configuration and transport behavior; Added unit tests for the analytics utility; Added unit tests for the new web-element API commands; Added unit tests for the withaftereach sample test; Added unit tests for transport layer configuration and browser options; Expanded test coverage for the test runner; New test infrastructure and mock utilities for the test suite.

This release updates the project to version 3.16.0 and enforces a minimum Node.js engine version of 18.20.5. Key dependency upgrades include selenium-webdriver to 4.27.0, mocha to 10.8.2, jsdom to 24.1.0, and nightwatch-axe-verbose to 2.3.0. The package also adds an override for minimatch to resolve security vulnerabilities and marks chromedriver and geckodriver as optional peer dependencies.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 40 → 43 (+2.3)
• Rubric changed (rubric-2026.09.12 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 54 → 54 (+0.0)
• Architecture 54 → 53 (-0.4)
• Maturity 55 → 55 (+0.0)
• Readiness 42 → 44 (+1.7)
• Security 43 → 52 (+9.6)
• Accessibility 34 → 34 (+0.0)
• Performance 85 (new)

• Dependency hygiene PARTLY measured — npm pinning read, dependency currency not (no pnpm-resolved versions to grade)
• Documentation: no usage examples (README.md)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• Medium CVE: [GHSA redacted] (package-lock.json)
• command (cognitive 20) (lib/api/web-element/commands/findAllByRole.js)
• command (cognitive 30) (lib/api/web-element/commands/findByLabelText.js)
• command (cyclomatic 24) (lib/api/web-element/commands/findByLabelText.js)

• Critical CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• High CVE: [GHSA redacted] (package-lock.json)
• Low cohesion: NightwatchClient (LCOM4 4) (lib/core/client.js)
• Low cohesion: Transport (LCOM4 8) (lib/transport/selenium-webdriver/index.js)
• Low cohesion: TreeNode (LCOM4 4) (lib/core/treenode.js)
• Outdated (npm): @nightwatch/nightwatch-inspector
• Outdated (npm): @types/chai
• Outdated (npm): @types/selenium-webdriver
• Outdated (npm): aria-query
• Outdated (npm): assertion-error
• Outdated (npm): boxen
• Outdated (npm): chalk
• Outdated (npm): ci-info
• Outdated (npm): devtools-protocol
• Outdated (npm): dotenv
• Outdated (npm): ejs
• Outdated (npm): envinfo
• …and 21 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

nightwatchjs/nightwatch was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.