RegressionBot SDK

The official SDK for RegressionBot.com — the simplest way to automate visual regression testing.

RegressionBot is a declarative visual regression testing platform that helps you catch UI changes before they reach production. This SDK provides a fluent, chainable API to define your test scope, run visual tests, and manage baselines programmatically.

Why RegressionBot?

Unlike traditional visual diffing libraries, RegressionBot is designed for modern, automated development loops and agentic pipelines:

• Highly Accurate Regressions (Zero Noise): Leveraging advanced pixel-matching algorithms and element masking (using CSS selectors or the automatic data-vr-mask attribute), RegressionBot eliminates false positives caused by dynamic data, layout shifting, or third-party widgets.
• Plain-English Summaries: No more manual screenshot comparisons. RegressionBot translates visual diffs into concise, plain-English descriptions of what changed, so you know exactly what was modified at a glance.
• Agentic Workflow Ready: Built from the ground up to support autonomous coding agents (like Gemini or Claude) and automated developer loops. Through standard API endpoints, CLI commands, and Model Context Protocol (MCP) integrations, agents can trigger tests, read plain-English results, and approve baseline changes programmatically without human intervention.

Features

• Fluent Manifest Builder: Chainable methods to define your test scope.
• Matrix Testing: Test multiple devices and viewports in a single job.
• Auto-Discovery: Scan sitemaps with glob patterns and limits.
• RegressionBot Summaries: Plain-English change descriptions for every regression, generated on-demand via the API.
• Project-Based Baselines: Save and reuse test configurations; share visual history across environments.
• Auto-Approval: Automatically promote screenshots to baselines on jobs that pass your criteria.
• Zero Infrastructure: No browser maintenance or server provisioning — RegressionBot handles it all.

Installation

npm install regressionbot

Usage

Basic Example

import { RegressionBot } from 'regressionbot';

const rb = new RegressionBot(); // uses REGRESSIONBOT_API_KEY env var

const job = await rb
  .test('https://preview.myapp.com')
  .forProject('my-app-web')
  .run();

const status = await job.waitForCompletion();
const summary = await job.getSummary();
console.log(`Stability Score: ${summary.overallScore}/100`);

// Download only diff images
await job.downloadResults();

// Download all images (baseline, current, diff)
await job.downloadResults({ full: true });

Full Matrix Example

import { RegressionBot } from 'regressionbot';

const rb = new RegressionBot(process.env.API_KEY);

const job = await rb
  .test(process.env.VERCEL_PREVIEW_URL)   // The Candidate (Test Origin)
  .against('https://production-app.com')    // The Source of Truth (Base Origin)
  .forProject('marketing-site-v2')          // Context: Links to Baselines & History

  // Matrix Configuration: Run all checks on both Desktop and Mobile
  .on(['Desktop Chrome', 'iPhone 13'])

  // Sitemap: Explicitly provide a sitemap location (optional)
  .sitemap('https://production-app.com/sitemap_index.xml')

  // Scope: Explicitly check critical paths
  .check('/', 'Homepage')
  .check('/pricing', 'Pricing Table')

  // Discovery: Auto-discover up to 20 blog posts
  .scan('/blog/**', { limit: 20 })
  
  // Concurrency: Max parallel browser instances
  .concurrency(10)

  // Masking: Automatic and manual masking
  .mask(['.ads', '#modal']) // Manual selectors
  // Tip: Adding 'data-vr-mask' to your HTML elements masks them automatically!

  // Execute: Compiles manifest and triggers the API
  .run();

const result = await job.waitForCompletion();
const summary = await job.getSummary();

console.log(`Job ${job.jobId} finished. Overall Score: ${summary.overallScore}`);

RegressionBot Summaries

RegressionBot can generate plain-English descriptions of what changed for each regression. Summaries are generated asynchronously after job completion.

// Wait for the job and its RegressionBot summaries to both finish
const status = await job.waitForCompletion(2000, undefined, { waitForSummaries: true });
const summary = await job.getSummary();

if (summary.regressions.length > 0) {
  console.log(`\n${summary.regressions.length} regressions found:`);
  for (const regression of summary.regressions) {
    if (regression.regressionbotSummary) {
      console.log(`\nRegressionBot Summary for ${regression.url}:`);
      console.log(`> ${regression.regressionbotSummary}`);
    }
  }
}

// Or trigger RegressionBot summary generation on-demand for a completed job:
const aiResult = await job.generateAiSummary();
console.log(`Generated summaries for ${aiResult.summaries.length} regressions.`);

Progress Tracking

Pass a callback to waitForCompletion to receive status updates while the job runs:

const status = await job.waitForCompletion(3000, (s) => {
  console.log(`[${s.status}] ${s.progress?.completed}/${s.progress?.total} pages checked`);
});

Auto-Approval

Set .autoApprove() to automatically promote screenshots to baselines when the job completes. Useful for scheduled health checks or first-run baseline seeding.

const job = await rb
  .test('https://production-app.com')
  .forProject('health-check')
  .scan('/**', { limit: 50 })
  .autoApprove()
  .run();

You can also approve an existing job's results programmatically:

const result = await job.approve();
console.log(`Approved ${result.approvedUrlsCount} URLs.`);

Saved Projects

Projects let you save a test configuration in the RegressionBot dashboard and trigger runs against it without re-specifying every option.

// List all saved projects for your organization
const projects = await rb.listProjects();
console.log(projects.map(p => p.name));

// Fetch a specific project's configuration
const project = await rb.getProject('marketing-site-v2');
console.log(project);

// Trigger a run from a saved project, optionally overriding fields
const job = await rb.runProject('marketing-site-v2', {
  testOrigin: process.env.VERCEL_PREVIEW_URL,
});

const status = await job.waitForCompletion();
const summary = await job.getSummary();
console.log(`Score: ${summary.overallScore}/100`);

Reconnecting to an Existing Job

If you have a job ID from a previous run (e.g., stored in CI state), you can attach to it without re-running the test:

const job = rb.job('job_abc123');
const summary = await job.getSummary();

CLI Usage

The regressionbot CLI is the easiest way to interact with the RegressionBot API from your terminal or CI scripts.

Authentication

The CLI looks for the following environment variables:

• REGRESSIONBOT_API_KEY: Your project API key.
• REGRESSIONBOT_API_URL: (Optional) Override the default API endpoint.

Commands

1. Quick Check

Test a single URL against its established baseline.

npx regressionbot https://example.com --project my-site --on "Desktop Chrome, iPhone 12"

2. Sitemap Scan

Test an entire site using glob patterns.

npx regressionbot https://example.com --project my-project --scan "/**" --exclude "/admin/**" --concurrency 20

3. Job Summary

Get detailed results and diff URLs for a completed job.

npx regressionbot summary <jobId>

Add the --download flag to save the diff images locally:

npx regressionbot summary <jobId> --download

Use the --download-full flag to save baseline, current, and diff images:

npx regressionbot summary <jobId> --download-full

4. Approve Changes

Promote the current screenshots of a job to be the new baselines.

npx regressionbot approve <jobId>

Examples & Integrations

Check out the examples/ directory for real-world integration guides:

• GitHub Actions: Self-contained composite action for CI.
• Preview vs Production: Compare staging URLs to live sites.
• AWS Amplify: Wait for builds and test dynamically.
• Scheduled Health Checks: Monitor production visuals daily.

Visit RegressionBot.com for more documentation, pricing, and to create your account.

Made with ❤️ by RegressionBot. Report issues on GitHub.