Node.js SDK

The RegressionBot Node.js SDK provides a fluent API for integrating visual testing directly into your end-to-end tests (like Playwright or Cypress) or custom scripts.

npm install regressionbot

Basic Usage

Here is a simple example of comparing a preview environment against your production baseline.

import { Visual } from 'regressionbot';

// Automatically uses process.env.REGRESSIONBOT_API_KEY
const visual = new Visual();

async function runTest() {
  const job = await visual
    .test('https://preview.myapp.com')
    .against('https://myapp.com')
    .forProject('my-web-app')
    .run();

  const result = await job.waitForCompletion();
  
  if (result.regressionCount > 0) {
    console.log(`Found ${result.regressionCount} regressions.`);
    process.exit(1);
  }
}

runTest();

Advanced Options

You can chain additional methods to customize the devices tested, specific paths, and CSS selectors to mask.

const job = await visual
  .test('https://preview.myapp.com')
  .against('https://myapp.com')
  .on(['Desktop Chrome', 'iPhone 13', 'iPad Mini'])
  .paths(['/', '/pricing', '/about'])
  .mask(['.ad-banner', '#dynamic-timestamp'])
  .run();

Reading Results

Once a job completes, the summary includes a plain-English RegressionBot Summary of each regression, a perceptual similarity score, and pre-signed image URLs you can download or display directly.

const summary = await job.getSummary();

for (const regression of summary.regressions) {
  console.log(`\n${regression.url} [${regression.variantName}]`);
  console.log(`  Changed pixels : ${regression.diffPercentage?.toFixed(2)}%`);
  console.log(`  Visual match   : ${regression.visualMatchScore}/100`);

  if (regression.regressionbotSummary) {
    console.log(`  AI summary     : ${regression.regressionbotSummary}`);
  }

  // Tip: visualMatchScore ≥ 99 + small diffPercentage = likely rendering noise
  const isNoise = (regression.visualMatchScore ?? 0) >= 99 && (regression.diffPercentage ?? 0) < 0.5;
  if (isNoise) {
    console.log('  ⚠️  Possible rendering artifact — review before approving');
  }

  console.log(`  Diff image     : ${regression.diffUrl}`);
}

Use job.downloadResults() to save diff images locally, or { full: true } to also save baseline and current screenshots.

Glob Patterns & Scans

When using the .sitemap() method, you can use .scan() to filter which pages are included using glob patterns.

*

Matches top-level pages only. It skips any nested directory separators (e.g. /docs/api would be skipped).

**

Recursive match (Globstar). Matches everything, including all nested directories and the root path. Recommended for full-site coverage.

// Test every single URL found in the sitemap
const job = await visual
  .test('https://preview.myapp.com')
  .sitemap('https://preview.myapp.com/sitemap.xml')
  .scan('**') // Recursive match
  .run();