@percy/nightwatch 2.1.0 → 2.2.0-beta.0

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,80 @@
 // Collect client and environment information
 const sdkPkg = require('../package.json');
 const nightwatchPkg = require('nightwatch/package.json');
+const { captureDOM } = 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());
+      await injectPercyDOM(this.api, domScript);
 
       // 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);
-        });
-      });
+      let { domSnapshot, url } = await captureDOM(this.api, options, utils, log, domScript);
 
-      // Post the DOM to the snapshot endpoint with snapshot options and other info
-      await utils.postSnapshot({
-        ...options,
+      // 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
+};

package/lib/snapshot.js

@@ -0,0 +1,361 @@
+const CS_MAX_SCREENSHOT_LIMIT = 25000;
+const SCROLL_DEFAULT_SLEEP_TIME = 0.45; // 450ms
+
+function ignoreCanvasSerializationErrors(options = {}, utils) {
+  return options?.ignoreCanvasSerializationErrors ??
+    utils?.percy?.config?.snapshot?.ignoreCanvasSerializationErrors ??
+    false;
+}
+
+function ignoreStyleSheetSerializationErrors(options = {}, utils) {
+  return options?.ignoreStyleSheetSerializationErrors ??
+    utils?.percy?.config?.snapshot?.ignoreStyleSheetSerializationErrors ??
+    false;
+}
+
+function unwrapResult(result) {
+  if (!result) return result;
+  if (typeof result === 'object' && 'value' in result && result.value !== undefined) {
+    return result.value;
+  }
+  return result;
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function executeScript(browser, fn, args = []) {
+  return new Promise((resolve, reject) => {
+    try {
+      browser.execute(fn, args, result => {
+        let value = unwrapResult(result);
+        if (result && result.status && result.status !== 0 && result.error) {
+          return reject(result.error);
+        }
+        resolve(value);
+      });
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+function getCookies(browser) {
+  if (typeof browser.getCookies !== 'function') return Promise.resolve([]);
+  return new Promise((resolve, reject) => {
+    try {
+      browser.getCookies(result => {
+        if (result && result.status && result.status !== 0 && result.error) {
+          return reject(result.error);
+        }
+        resolve(Array.isArray(result?.value) ? result.value : (result?.value || []));
+      });
+    } catch (error) {
+      reject(error);
+    }
+  }).catch(() => []);
+}
+
+async function captureSerializedDOM(browser, options = {}, utils) {
+  const serializeOptions = {
+    ...options,
+    ignoreCanvasSerializationErrors: ignoreCanvasSerializationErrors(options, utils),
+    ignoreStyleSheetSerializationErrors: ignoreStyleSheetSerializationErrors(options, utils)
+  };
+
+  let { domSnapshot, url } = await executeScript(browser, function(opts) {
+    return {
+      /* eslint-disable-next-line no-undef */
+      domSnapshot: PercyDOM.serialize(opts),
+      url: document.URL
+    };
+  }, [serializeOptions]);
+
+  if (!domSnapshot) domSnapshot = {};
+  domSnapshot.cookies = await getCookies(browser);
+
+  return { domSnapshot, url };
+}
+
+function isResponsiveOptionEnabled(options = {}, utils) {
+  if (utils?.percy?.config?.percy?.deferUploads) return false;
+
+  if (Object.prototype.hasOwnProperty.call(options, 'responsiveSnapshotCapture')) {
+    return Boolean(options.responsiveSnapshotCapture);
+  }
+
+  if (Object.prototype.hasOwnProperty.call(options, 'responsive_snapshot_capture')) {
+    return Boolean(options.responsive_snapshot_capture);
+  }
+
+  return Boolean(utils?.percy?.config?.snapshot?.responsiveSnapshotCapture);
+}
+
+function getWidthsForMultiDOM(userPassedWidths = [], eligibleWidths = {}) {
+  let widths = [];
+
+  if (eligibleWidths?.mobile?.length) widths = widths.concat(eligibleWidths.mobile);
+
+  if (userPassedWidths.length) {
+    widths = widths.concat(userPassedWidths);
+  } else if (eligibleWidths?.config?.length) {
+    widths = widths.concat(eligibleWidths.config);
+  } else if (Array.isArray(eligibleWidths)) {
+    widths = widths.concat(eligibleWidths);
+  }
+
+  return [...new Set(widths)].filter(width => !!width);
+}
+
+function promisifyBrowserCommand(browser, command, ...args) {
+  if (typeof browser[command] !== 'function') return Promise.resolve();
+
+  return new Promise((resolve, reject) => {
+    try {
+      browser[command](...args, result => {
+        if (result && result.status && result.status !== 0 && result.error) {
+          return reject(result.error);
+        }
+        resolve(unwrapResult(result));
+      });
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+async function getWindowRect(browser) {
+  let rect = await executeScript(browser, function() {
+    return { width: window.innerWidth, height: window.innerHeight };
+  }) || {};
+
+  if (typeof rect.width !== 'number' || Number.isNaN(rect.width)) rect.width = 1280;
+  if (typeof rect.height !== 'number' || Number.isNaN(rect.height)) rect.height = 720;
+  return rect;
+}
+
+async function setWindowRect(browser, { width, height }) {
+  const rect = { width, height };
+  if (typeof browser.setWindowRect === 'function') {
+    return await promisifyBrowserCommand(browser, 'setWindowRect', rect);
+  }
+
+  if (typeof browser.setWindowSize === 'function') {
+    return await promisifyBrowserCommand(browser, 'setWindowSize', width, height);
+  }
+
+  if (typeof browser.resizeWindow === 'function') {
+    return await promisifyBrowserCommand(browser, 'resizeWindow', width, height);
+  }
+
+  return await executeScript(browser, function(dimensions) {
+    window.resizeTo(dimensions.width, dimensions.height);
+  }, [rect]);
+}
+
+async function waitForCondition(condition, { timeout = 1000, interval = 100 } = {}) {
+  const end = Date.now() + timeout;
+
+  while (Date.now() < end) {
+    if (await condition()) return true;
+    await sleep(interval);
+  }
+
+  return await condition();
+}
+
+async function waitForResizeEvent(browser, resizeCount) {
+  await waitForCondition(async () => {
+    /* istanbul ignore next */
+    const current = await executeScript(browser, function() {
+      return window.resizeCount;
+    });
+    return current === resizeCount;
+  }).catch(() => {});
+}
+
+async function sendCDPResize(browser, width, height) {
+  const driver = browser?.driver || browser?.transport?.driver;
+  if (!driver || typeof driver.sendDevToolsCommand !== 'function') return false;
+
+  await driver.sendDevToolsCommand('Emulation.setDeviceMetricsOverride', {
+    height,
+    width,
+    deviceScaleFactor: 1,
+    mobile: false
+  });
+  return true;
+}
+
+async function changeWindowDimensionAndWait(browser, width, height, resizeCount, log) {
+  if (typeof width !== 'number' || Number.isNaN(width)) return;
+  if (typeof height !== 'number' || Number.isNaN(height)) {
+    ({ height } = await getWindowRect(browser));
+  }
+  try {
+    const caps = browser?.options?.capabilities || browser?.options?.desiredCapabilities;
+    const browserName = caps?.browserName || caps?.browser || '';
+    let usedCDP = false;
+
+    if (
+      typeof process !== 'undefined' &&
+      process.env.PERCY_DISABLE_CDP_RESIZE !== 'true' &&
+      browserName.toLowerCase() === 'chrome'
+    ) {
+      try {
+        usedCDP = await sendCDPResize(browser, width, height);
+      } catch (error) {
+        log?.debug?.(`Resizing using CDP failed for width ${width}`, error);
+      }
+    }
+
+    if (!usedCDP) {
+      await setWindowRect(browser, { width, height });
+    }
+  } catch (error) {
+    log?.debug?.(`Resizing window failed for width ${width}`, error);
+  }
+
+  try {
+    await waitForResizeEvent(browser, resizeCount);
+  } catch (error) {
+    log?.debug?.(`Timed out waiting for window resize event for width ${width}`, error);
+  }
+}
+
+async function maybeReloadPage(browser, domScript) {
+  if (!process.env.PERCY_RESPONSIVE_CAPTURE_RELOAD_PAGE) return false;
+  await promisifyBrowserCommand(browser, 'refresh');
+  if (domScript) await executeScript(browser, domScript);
+  return true;
+}
+
+async function maybeSleepForResponsiveCapture() {
+  if (!process.env.RESPONSIVE_CAPTURE_SLEEP_TIME) return;
+  const sleepTime = parseFloat(process.env.RESPONSIVE_CAPTURE_SLEEP_TIME);
+  if (!Number.isFinite(sleepTime)) return;
+  await sleep(sleepTime * 1000);
+}
+
+async function maybeScrollForLazyLoad(browser) {
+  if (!process.env.PERCY_ENABLE_LAZY_LOADING_SCROLL) return;
+  await slowScrollToBottom(browser);
+}
+
+async function getResponsiveHeight(browser, currentHeight, utils) {
+  if (!process.env.PERCY_RESPONSIVE_CAPTURE_MIN_HEIGHT) return currentHeight;
+  const minHeight = utils?.percy?.config?.snapshot?.minHeight || currentHeight;
+  return await executeScript(browser, function(height) {
+    return window.outerHeight - window.innerHeight + height;
+  }, [minHeight]);
+}
+
+async function captureResponsiveDOM(browser, options, utils, log, domScript) {
+  const widths = getWidthsForMultiDOM(options.widths || [], utils?.percy?.widths || {});
+  const domSnapshots = [];
+  const { width: originalWidth, height: originalHeight } = await getWindowRect(browser);
+  let lastWindowWidth = originalWidth;
+  let resizeCount = 0;
+
+  log?.info?.('Responsive snapshot capture enabled');
+  await executeScript(browser, function() {
+    /* eslint-disable-next-line no-undef */
+    PercyDOM.waitForResize();
+  });
+
+  const height = await getResponsiveHeight(browser, originalHeight, utils);
+  const responsiveWidths = widths.length ? widths : [originalWidth];
+  let lastURL;
+
+  for (let width of responsiveWidths) {
+    if (lastWindowWidth !== width) {
+      resizeCount += 1;
+      await changeWindowDimensionAndWait(browser, width, height, resizeCount, log);
+      lastWindowWidth = width;
+    }
+
+    log?.info?.(`Capturing responsive snapshot at width ${width}px`);
+    const reloaded = await maybeReloadPage(browser, domScript);
+    if (reloaded) {
+      await executeScript(browser, function() {
+        /* eslint-disable-next-line no-undef */
+        PercyDOM.waitForResize();
+      });
+    }
+    await maybeSleepForResponsiveCapture();
+    await maybeScrollForLazyLoad(browser);
+
+    let { domSnapshot, url } = await captureSerializedDOM(browser, options, utils);
+    domSnapshot.width = width;
+    domSnapshots.push(domSnapshot);
+    lastURL = url;
+  }
+
+  await changeWindowDimensionAndWait(browser, originalWidth, originalHeight, resizeCount + 1, log);
+  return { domSnapshot: domSnapshots, url: lastURL };
+}
+
+async function captureDOM(browser, options = {}, utils, log, domScript) {
+  const responsiveEnabled = isResponsiveOptionEnabled(options, utils);
+  if (responsiveEnabled) {
+    return await captureResponsiveDOM(browser, options, utils, log, domScript);
+  }
+
+  return await captureSerializedDOM(browser, options, utils);
+}
+
+async function slowScrollToBottom(browser, scrollSleep = SCROLL_DEFAULT_SLEEP_TIME) {
+  if (process.env.PERCY_LAZY_LOAD_SCROLL_TIME) {
+    scrollSleep = parseFloat(process.env.PERCY_LAZY_LOAD_SCROLL_TIME);
+  }
+
+  const scrollHeightCommand = function() {
+    return Math.max(
+      document.body.scrollHeight,
+      document.body.clientHeight,
+      document.body.offsetHeight,
+      document.documentElement.scrollHeight,
+      document.documentElement.clientHeight,
+      document.documentElement.offsetHeight
+    );
+  };
+
+  let scrollHeight = Math.min(await executeScript(browser, scrollHeightCommand), CS_MAX_SCREENSHOT_LIMIT);
+  const clientHeight = await executeScript(browser, function() {
+    return document.documentElement.clientHeight;
+  });
+  let current = 0;
+  let page = 1;
+
+  while (scrollHeight > current && current < CS_MAX_SCREENSHOT_LIMIT) {
+    current = clientHeight * page;
+    page += 1;
+    await executeScript(browser, function(position) {
+      window.scrollTo(0, position);
+    }, [current]);
+    await sleep(scrollSleep * 1000);
+    scrollHeight = await executeScript(browser, scrollHeightCommand);
+  }
+
+  if (process.env.BYPASS_SCROLL_TO_TOP !== 'true') {
+    await executeScript(browser, function() {
+      window.scrollTo(0, 0);
+    });
+  }
+
+  let sleepAfterScroll = 1;
+  if (process.env.PERCY_SLEEP_AFTER_LAZY_LOAD_COMPLETE) {
+    sleepAfterScroll = parseFloat(process.env.PERCY_SLEEP_AFTER_LAZY_LOAD_COMPLETE);
+  }
+
+  await sleep(sleepAfterScroll * 1000);
+}
+
+module.exports = {
+  captureSerializedDOM,
+  captureDOM,
+  slowScrollToBottom,
+  ignoreCanvasSerializationErrors,
+  ignoreStyleSheetSerializationErrors
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@percy/nightwatch",
   "description": "Nightwatch client library for visual testing with Percy",
-  "version": "2.1.0",
+  "version": "2.2.0-beta.0",
   "license": "MIT",
   "author": "Perceptual Inc.",
   "repository": "https://github.com/percy/percy-nightwatch",
@@ -14,37 +14,40 @@
   "types": "types/percySnapshot.d.ts",
   "files": [
     "commands/percySnapshot.js",
+    "lib",
     "types/percySnapshot.d.ts"
   ],
   "engines": {
     "node": ">=14"
   },
   "scripts": {
-    "lint": "eslint --ignore-path .gitignore .",
-    "test": "MOZ_HEADLESS=1 nightwatch",
-    "test:coverage": "nyc yarn test",
+    "lint": "eslint .",
+    "test": "yarn test:unit && yarn test:nightwatch",
+    "test:unit": "mocha \"test/unit/**/*.test.js\"",
+    "test:nightwatch": "cross-env MOZ_HEADLESS=1 percy exec --testing -- nightwatch",
+    "test:coverage": "nyc yarn test:unit",
     "test:types": "tsd"
   },
   "dependencies": {
-    "@percy/sdk-utils": "^1.0.0"
+    "@percy/sdk-utils": "^1.31.4",
+    "@percy/selenium-webdriver": "^2.2.3"
   },
   "peerDependencies": {
-    "nightwatch": ">=1"
+    "nightwatch": ">=1 || >=2 || >=3"
   },
   "devDependencies": {
-    "@percy/core": "^1.0.0",
-    "@types/nightwatch": "^2.0.0",
+    "@percy/cli": "^1.31.4",
+    "cross-env": "^10.1.0",
     "eslint": "^7.11.0",
     "eslint-config-standard": "^16.0.1",
     "eslint-plugin-import": "^2.22.1",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "^5.1.0",
     "eslint-plugin-standard": "^5.0.0",
-    "expect": "^27.0.2",
-    "geckodriver": "^3.0.1",
-    "mocha": "^10.0.0",
-    "nightwatch": "^2.1.3",
-    "nyc": "^15.1.0",
-    "tsd": "^0.20.0"
+    "expect": "^30.2.0",
+    "mocha": "^11.7.5",
+    "nightwatch": "^3.12.3",
+    "nyc": "^17.1.0",
+    "tsd": "^0.33.0"
   }
 }

package/types/percySnapshot.d.ts

@@ -1,12 +1,75 @@
 import { SnapshotOptions } from '@percy/core';
 import { NightwatchAPI, NightwatchCustomCommands } from 'nightwatch';
 
+export type PercyRegionAlgorithm = 'standard' | 'layout' | 'ignore' | 'intelliignore';
+
+export interface PercyRegionBoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface PercyRegionPadding {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+
+export interface PercyRegionSelector {
+  boundingBox?: PercyRegionBoundingBox;
+  elementXpath?: string;
+  elementCSS?: string;
+}
+
+export interface PercyRegionConfiguration {
+  diffSensitivity?: number;
+  imageIgnoreThreshold?: number;
+  carouselsEnabled?: boolean;
+  bannersEnabled?: boolean;
+  adsEnabled?: boolean;
+}
+
+export interface PercyRegionAssertion {
+  diffIgnoreThreshold?: number;
+}
+
+export interface PercyRegion {
+  algorithm: PercyRegionAlgorithm;
+  elementSelector?: PercyRegionSelector;
+  padding?: PercyRegionPadding;
+  configuration?: PercyRegionConfiguration;
+  assertion?: PercyRegionAssertion;
+}
+
+export interface CreateRegionOptions extends PercyRegionSelector {
+  padding?: PercyRegionPadding;
+  algorithm?: PercyRegionAlgorithm;
+  diffSensitivity?: number;
+  imageIgnoreThreshold?: number;
+  carouselsEnabled?: boolean;
+  bannersEnabled?: boolean;
+  adsEnabled?: boolean;
+  diffIgnoreThreshold?: number;
+}
+
+export type CreateRegion = (options?: CreateRegionOptions) => PercyRegion;
+
+export interface PercyNightwatchExports {
+  path: string;
+  createRegion: CreateRegion;
+}
+
+declare const percyNightwatch: PercyNightwatchExports;
+export default percyNightwatch;
+
 declare module 'nightwatch' {
   interface NightwatchCustomCommands {
     percySnapshot(
       this: NightwatchAPI,
       name?: string,
       options?: SnapshotOptions
-    ): this
+    ): this;
   }
 }