@percy/nightwatch 2.2.0 → 2.2.1-beta.1

package/README.md

@@ -1,139 +1,209 @@
-# @percy/nightwatch
-
-[![Version](https://img.shields.io/npm/v/@percy/nightwatch.svg)](https://www.npmjs.com/package/@percy/nightwatch)
-![Test](https://github.com/percy/percy-nightwatch/workflows/Test/badge.svg)
-
-[Percy](https://percy.io) visual testing for [Nightwatch.js](http://nightwatchjs.org).
-
-## Installation
-
-```sh-session
-$ npm install --save-dev @percy/cli @percy/nightwatch
-```
-
-### Nightwatch configuration
-
-Add the path exported by `@percy/nightwatch` to your Nightwatch configuration's
-`custom_commands_path` property.
-
-```javascript
-const percy = require('@percy/nightwatch');
-
-module.exports = {
-  // ...
-  custom_commands_path: [percy.path],
-  // ...
-};
-```
-
-## Usage
-
-This is an example test using the `browser.percySnapshot()` command. For other examples of how to
-write Nightwatch tests, check out [the official Nightwatch
-guides](https://nightwatchjs.org/guide/using-nightwatch/writing-tests.html).
-
-```javascript
-module.exports = {
-  'Snapshots pages': function(browser) {
-    browser
-      .url('http://example.com')
-      .assert.containsText('h1', 'Example Domain')
-      .percySnapshot('Example snapshot');
-    browser
-      .url('http://google.com')
-      .assert.elementPresent('img[alt="Google"]')
-      .percySnapshot('Google homepage');
-    browser.end();
-  }
-};
-```
-
-Running the test above directly will result in the following logs:
-
-```sh-session
-$ nightwatch
-
-[Example] Test Suite
-====================
-...
-
-Running:  Snapshots pages
-
-✔ Testing if element <h1> contains text 'Example Domain'
-[percy] Percy is not running, disabling snapshots
-✔ Testing if element <img[alt="Google"]> is present
-
-OK. 2 assertions passed.
-```
-
-When running with [`percy
-exec`](https://github.com/percy/cli/tree/master/packages/cli-exec#percy-exec), and your project's
-`PERCY_TOKEN`, a new Percy build will be created and snapshots will be uploaded to your project.
-
-```sh-session
-$ export PERCY_TOKEN=[your-project-token]
-$ percy exec -- nightwatch
-[percy] Percy has started!
-[percy] Created build #1: https://percy.io/[your-project]
-[percy] Running "nightwatch"
-
-[Example] Test Suite
-====================
-...
-
-Running:  Snapshots pages
-
-✔ Testing if element <h1> contains text 'Example Domain'
-[percy] Snapshot taken "Snapshots pages"
-✔ Testing if element <img[alt="Google"]> is present
-[percy] Snapshot taken "Google homepage"
-
-OK. 2 assertions passed.
-[percy] Stopping percy...
-[percy] Finalized build #1: https://percy.io/[your-project]
-[percy] Done!
-```
-
-## Configuration
-
-`percySnapshot([name][, options])`
-
-- `name` - The snapshot name; must be unique to each snapshot
-- `options` - [See per-snapshot configuration options](https://docs.percy.io/docs/cli-configuration#per-snapshot-configuration)
-
-## Upgrading
-
-### Automatically with `@percy/migrate`
-
-We built a tool to help automate migrating to the new CLI toolchain! Migrating
-can be done by running the following commands and following the prompts:
-
-``` shell
-$ npx @percy/migrate
-? Are you currently using @percy/nightwatch? Yes
-? Install @percy/cli (required to run percy)? Yes
-? Migrate Percy config file? Yes
-? Upgrade SDK to @percy/nightwatch@2.0.0? Yes
-```
-
-This will automatically run the changes described below for you.
-
-### Manually
-
-#### Installing `@percy/cli`
-
-If you're coming from a pre-2.0 version of this package, make sure to install `@percy/cli` after
-upgrading to retain any existing scripts that reference the Percy CLI command.
-
-```sh-session
-$ npm install --save-dev @percy/cli
-```
-
-#### Migrating Config
-
-If you have a previous Percy configuration file, migrate it to the newest version with the
-[`config:migrate`](https://github.com/percy/cli/tree/master/packages/cli-config#percy-configmigrate-filepath-output) command:
-
-```sh-session
-$ percy config:migrate
-```
+# @percy/nightwatch
+
+[![Version](https://img.shields.io/npm/v/@percy/nightwatch.svg)](https://www.npmjs.com/package/@percy/nightwatch)
+![Test](https://github.com/percy/percy-nightwatch/workflows/Test/badge.svg)
+
+[Percy](https://percy.io) visual testing for [Nightwatch.js](http://nightwatchjs.org).
+
+## Installation
+
+```sh-session
+$ npm install --save-dev @percy/cli @percy/nightwatch
+```
+
+### Nightwatch configuration
+
+Add the path exported by `@percy/nightwatch` to your Nightwatch configuration's
+`custom_commands_path` property.
+
+```javascript
+const percy = require('@percy/nightwatch');
+
+module.exports = {
+  // ...
+  custom_commands_path: [percy.path],
+  // ...
+};
+```
+
+## Usage
+
+This is an example test using the `browser.percySnapshot()` command. For other examples of how to
+write Nightwatch tests, check out [the official Nightwatch
+guides](https://nightwatchjs.org/guide/using-nightwatch/writing-tests.html).
+
+```javascript
+module.exports = {
+  "Snapshots pages": function (browser) {
+    browser.url("http://example.com").assert.containsText("h1", "Example Domain").percySnapshot("Example snapshot");
+    browser.url("http://google.com").assert.elementPresent('img[alt="Google"]').percySnapshot("Google homepage");
+    browser.end();
+  },
+};
+```
+
+Running the test above directly will result in the following logs:
+
+```sh-session
+$ nightwatch
+
+[Example] Test Suite
+====================
+...
+
+Running:  Snapshots pages
+
+✔ Testing if element <h1> contains text 'Example Domain'
+[percy] Percy is not running, disabling snapshots
+✔ Testing if element <img[alt="Google"]> is present
+
+OK. 2 assertions passed.
+```
+
+When running with [`percy
+exec`](https://github.com/percy/cli/tree/master/packages/cli-exec#percy-exec), and your project's
+`PERCY_TOKEN`, a new Percy build will be created and snapshots will be uploaded to your project.
+
+```sh-session
+$ export PERCY_TOKEN=[your-project-token]
+$ percy exec -- nightwatch
+[percy] Percy has started!
+[percy] Created build #1: https://percy.io/[your-project]
+[percy] Running "nightwatch"
+
+[Example] Test Suite
+====================
+...
+
+Running:  Snapshots pages
+
+✔ Testing if element <h1> contains text 'Example Domain'
+[percy] Snapshot taken "Snapshots pages"
+✔ Testing if element <img[alt="Google"]> is present
+[percy] Snapshot taken "Google homepage"
+
+OK. 2 assertions passed.
+[percy] Stopping percy...
+[percy] Finalized build #1: https://percy.io/[your-project]
+[percy] Done!
+```
+
+## Configuration
+
+`percySnapshot([name][, options])`
+
+- `name` - The snapshot name; must be unique to each snapshot
+- `options` - [See per-snapshot configuration options](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#per-snapshot-configuration)
+
+### Responsive snapshots
+
+Set `responsiveSnapshotCapture: true` (and optionally `widths`) to have the Nightwatch SDK resize the browser window and capture DOM snapshots at multiple breakpoints in a single Percy snapshot. The SDK implementation:
+
+- Calling `PercyDOM.waitForResize()` once and waiting on `window.resizeCount` before each snapshot.
+- Using Chrome DevTools Protocol resizing when available (disable with `PERCY_DISABLE_CDP_RESIZE=true`) and falling back to WebDriver window APIs.
+- Honoring the environment toggles:
+  - `PERCY_RESPONSIVE_CAPTURE_MIN_HEIGHT` – ensure a minimum viewport height using `snapshot.minHeight`.
+  - `PERCY_RESPONSIVE_CAPTURE_RELOAD_PAGE` – reload the page (and re-inject Percy DOM) between widths.
+  - `RESPONSIVE_CAPTURE_SLEEP_TIME` – wait (in seconds) between width changes.
+  - `PERCY_ENABLE_LAZY_LOADING_SCROLL` – trigger the lazy-load scroll helper described below.
+- Resetting the window back to its original dimensions after the final width.
+
+### Lazy-loading scroll helper
+
+When `PERCY_ENABLE_LAZY_LOADING_SCROLL` is set the SDK scrolls the page in increments (up to 25,000px) to trigger lazy-loaded content before each snapshot. Additional environment variables control the behavior:
+
+- `PERCY_LAZY_LOAD_SCROLL_TIME` – seconds to pause between scroll steps (default `0.45`).
+- `BYPASS_SCROLL_TO_TOP=true` – skip scrolling back to the top of the page.
+- `PERCY_SLEEP_AFTER_LAZY_LOAD_COMPLETE` – seconds to wait after finishing the scroll sequence.
+
+### Running tests
+
+All unit and Nightwatch integration tests can be executed with:
+
+```sh
+yarn test
+```
+
+Additional scripts are available when iterating locally:
+
+- `yarn test:unit` &mdash; runs the mocha suite under `test/unit/**`.
+- `yarn test:nightwatch` &mdash; runs the Nightwatch suite (wrapped by `percy exec`) in headless Firefox.
+
+### E2E Visual Testing
+
+The repository includes comprehensive end-to-end (E2E) visual regression tests that create actual Percy builds and validate all SDK features. These tests use real HTML fixtures and test scenarios to ensure the SDK works correctly.
+
+**Running E2E tests locally:**
+
+```sh
+# Terminal 1 - Start test server
+yarn e2e:server
+
+# Terminal 2 - Run tests with Percy
+PERCY_TOKEN=your_token yarn e2e:chrome    # Chrome (with CDP)
+PERCY_TOKEN=your_token yarn e2e:firefox   # Firefox (WebDriver)
+
+# Or run everything in one command
+PERCY_TOKEN=your_token yarn e2e:local
+```
+
+**What's tested:**
+- ✅ Responsive snapshots with multiple widths (CDP + WebDriver fallbacks)
+- ✅ Lazy loading with scroll helper
+- ✅ Canvas and stylesheet serialization
+- ✅ Region algorithms (ignore, standard, layout, intelliignore)
+- ✅ Percy CSS, scope selectors, and DOM transformation
+- ✅ Cookie capture and attachment
+- ✅ Shadow DOM serialization
+- ✅ Complex real-world integration scenarios
+
+**E2E test structure:**
+- `test/e2e/fixtures/` - 7 comprehensive HTML test pages
+- `test/e2e/e2e.test.js` - 13 optimized test scenarios covering all features
+- `test/e2e/server.js` - Static file server for fixtures
+- `test/e2e/nightwatch.e2e.conf.js` - E2E-specific configuration
+
+**Snapshot count:**
+- PRs: ~25-30 snapshots (Chrome only, optimized for quick review)
+- Main branch: ~75-90 snapshots (Chrome + Firefox + environment tests)
+
+See [`test/e2e/README.md`](test/e2e/README.md) for detailed documentation, environment variables, and troubleshooting.
+
+**CI/CD:** E2E tests run automatically on pull requests (Chrome) and main branch pushes (Chrome + Firefox) via GitHub Actions (`.github/workflows/e2e-percy.yml`).
+
+## Upgrading
+
+### Automatically with `@percy/migrate`
+
+We built a tool to help automate migrating to the new CLI toolchain! Migrating
+can be done by running the following commands and following the prompts:
+
+```shell
+$ npx @percy/migrate
+? Are you currently using @percy/nightwatch? Yes
+? Install @percy/cli (required to run percy)? Yes
+? Migrate Percy config file? Yes
+? Upgrade SDK to @percy/nightwatch@2.0.0? Yes
+```
+
+This will automatically run the changes described below for you.
+
+### Manually
+
+#### Installing `@percy/cli`
+
+If you're coming from a pre-2.0 version of this package, make sure to install `@percy/cli` after
+upgrading to retain any existing scripts that reference the Percy CLI command.
+
+```sh-session
+$ npm install --save-dev @percy/cli
+```
+
+#### Migrating Config
+
+If you have a previous Percy configuration file, migrate it to the newest version with the
+[`config:migrate`](https://github.com/percy/cli/tree/master/packages/cli-config#percy-configmigrate-filepath-output) command:
+
+```sh-session
+$ percy config:migrate
+```

package/commands/percySnapshot.js

@@ -1,52 +1,90 @@
 // Collect client and environment information
 const sdkPkg = require('../package.json');
 const nightwatchPkg = require('nightwatch/package.json');
+const { captureDOM, waitForReady } = require('../lib/snapshot');
+const { createRegion } = require('../lib/regions');
 const CLIENT_INFO = `${sdkPkg.name}/${sdkPkg.version}`;
 const ENV_INFO = `${nightwatchPkg.name}/${nightwatchPkg.version}`;
+const NOT_RUNNING_ERROR = 'Percy is not running, disabling snapshots.';
+const AUTOMATE_ERROR = 'Invalid function call - percySnapshot(). Please use percyScreenshot() function while using Percy with Automate. For more information on usage of percyScreenshot, refer https://www.browserstack.com/docs/percy/integrate/functional-and-visual';
 
 // Take a DOM snapshot and post it to the snapshot endpoint
+function injectPercyDOM(browser, domScript) {
+  return new Promise((resolve, reject) => {
+    browser.execute(domScript, [], (result) => {
+      if (result && result.status && result.status !== 0 && result.error) {
+        return reject(result.error);
+      }
+      resolve();
+    });
+  });
+}
+
 module.exports = class PercySnapshotCommand {
-  async command(name, options) {
+  async command(name, options = {}) {
     let utils = await import('@percy/sdk-utils');
-
-    if (!(await utils.isPercyEnabled())) return;
     name = name || this.api.currentTest.name;
     let log = utils.logger('nightwatch');
 
+    if (!(await utils.isPercyEnabled())) {
+      if (process.env.PERCY_RAISE_ERROR === 'true') {
+        throw new Error(NOT_RUNNING_ERROR);
+      }
+      return;
+    }
+
+    if (utils.percy?.type === 'automate') {
+      throw new Error(AUTOMATE_ERROR);
+    }
+
     try {
+      let domScript = await utils.fetchPercyDOM();
+
       // Inject the DOM serialization script
-      await this.api.execute(await utils.fetchPercyDOM());
-
-      // Serialize and capture the DOM
-      /* istanbul ignore next: no instrumenting injected code */
-      let { domSnapshot, url } = await new Promise((resolve) => {
-        this.api.execute(function(options) {
-          return {
-            /* eslint-disable-next-line no-undef */
-            domSnapshot: PercyDOM.serialize(options),
-            url: document.URL
-          };
-        }, [options], function(result) {
-          // Check if we're in Nightwatch 1.x (which returns with `.value`)
-          result.value ? resolve(result.value) : resolve(result);
-        });
-      });
+      await injectPercyDOM(this.api, domScript);
 
-      // Post the DOM to the snapshot endpoint with snapshot options and other info
-      await utils.postSnapshot({
-        ...options,
+      // Readiness gate — runs before serialize when CLI supports it.
+      const readinessDiagnostics = await waitForReady(this.api, options, utils, log);
+
+      // Thread domScript + log through ctx so concurrent percySnapshot calls
+      // (parallel workers in the same Node process) don't race on shared
+      // module-level state.
+      let { domSnapshot, url } = await captureDOM(this.api, options, utils, domScript, log);
+
+      // Attach readiness diagnostics so the CLI can log timing and pass/fail
+      if (readinessDiagnostics && domSnapshot && typeof domSnapshot === 'object' && !Array.isArray(domSnapshot)) {
+        domSnapshot.readiness_diagnostics = readinessDiagnostics;
+      }
+
+      // Filter out DOM-only serialization options that shouldn't be posted to Percy
+      const {
+        ignoreCanvasSerializationErrors,
+        ignoreStyleSheetSerializationErrors,
+        ...snapshotOptions
+      } = options;
+
+      const postData = {
+        ...snapshotOptions,
+        domSnapshot,
         environmentInfo: ENV_INFO,
         clientInfo: CLIENT_INFO,
-        domSnapshot,
         name,
         url
-      });
+      };
+
+      // Post the DOM to the snapshot endpoint with snapshot options and other info
+      await utils.postSnapshot(postData);
     } catch (error) {
       // Handle errors
       log.error(`Could not take DOM snapshot "${name}"`);
       log.error(error);
+
+      if (process.env.PERCY_RAISE_ERROR === 'true') {
+        throw error;
+      }
     }
   }
 };
 
+module.exports.createRegion = createRegion;
 module.exports.path = __dirname;

package/lib/regions.js

@@ -0,0 +1,59 @@
+const AVAILABLE_ALGORITHMS = ['standard', 'layout', 'ignore', 'intelliignore'];
+
+function createRegion({
+  boundingBox = null,
+  elementXpath = null,
+  elementCSS = null,
+  padding = null,
+  algorithm = 'ignore',
+  diffSensitivity = null,
+  imageIgnoreThreshold = null,
+  carouselsEnabled = null,
+  bannersEnabled = null,
+  adsEnabled = null,
+  diffIgnoreThreshold = null
+} = {}) {
+  if (!AVAILABLE_ALGORITHMS.includes(algorithm)) {
+    throw new Error(`Invalid algorithm "${algorithm}". Expected one of: ${AVAILABLE_ALGORITHMS.join(', ')}`);
+  }
+
+  const elementSelector = {};
+  if (boundingBox) elementSelector.boundingBox = boundingBox;
+  if (elementXpath) elementSelector.elementXpath = elementXpath;
+  if (elementCSS) elementSelector.elementCSS = elementCSS;
+
+  const region = { algorithm };
+  if (Object.keys(elementSelector).length > 0) {
+    region.elementSelector = elementSelector;
+  }
+
+  if (padding) {
+    region.padding = padding;
+  }
+
+  const configuration = {};
+  if (['standard', 'intelliignore'].includes(algorithm)) {
+    if (diffSensitivity !== null) configuration.diffSensitivity = diffSensitivity;
+    if (imageIgnoreThreshold !== null) configuration.imageIgnoreThreshold = imageIgnoreThreshold;
+    if (carouselsEnabled !== null) configuration.carouselsEnabled = carouselsEnabled;
+    if (bannersEnabled !== null) configuration.bannersEnabled = bannersEnabled;
+    if (adsEnabled !== null) configuration.adsEnabled = adsEnabled;
+  }
+
+  if (Object.keys(configuration).length > 0) {
+    region.configuration = configuration;
+  }
+
+  const assertion = {};
+  if (diffIgnoreThreshold !== null) assertion.diffIgnoreThreshold = diffIgnoreThreshold;
+
+  if (Object.keys(assertion).length > 0) {
+    region.assertion = assertion;
+  }
+
+  return region;
+}
+
+module.exports = {
+  createRegion
+};