Regressionbot Developer Docs

Welcome to the Regressionbot documentation. Explore our CLI, SDKs, Agentic Workflows, and comprehensive API to seamlessly integrate visual regression testing into your pipelines.

v1.0.0

Getting Started (CLI)

Install the CLI directly or start a test from your terminal. Regressionbot CLI makes it trivial to check an environment or hook it into CI quickly.

Terminal

# Run a quick test against your preview URL
npx regressionbot@latest https://preview.myapp.com \
  --project my-app-web \
  --against https://myapp.com \
  --on "Desktop Chrome,iPhone 12"

Node.js SDK

Integrate visual regression tests deeply into your automated test suites, scripts, or deployment pipelines using our strongly-typed Node.js SDK.

example.ts

import { Visual } from 'regressionbot';

// Initialize the SDK with your API Key
const visual = new Visual(process.env.REGRESSIONBOT_API_KEY);

async function run() {
  // 1. Trigger the Visual Test Suite
  const job = await visual.test('https://preview.myapp.com')
    .against('https://myapp.com')
    .forProject('my-app-web')
    .on(['Desktop Chrome', 'iPhone 13'])
    .mask(['.ads-banner', '#dynamic-timestamp'])
    .run();

  console.log(`Started Job ID: ${job.jobId}`);

  // 2. Wait for completion (polls automatically)
  await job.waitForCompletion(5000, (status) => {
    console.log(`Progress: ${status.progress?.percent || 0}%`);
  });

  // 3. Get the Summary
  const summary = await job.getSummary();
  console.log(`Overall Stability Score: ${summary.overallScore}/100`);
  
  if (summary.regressionCount > 0) {
    console.log(`Found ${summary.regressionCount} visual regressions.`);
    // Optionally download the diffs
    await job.downloadResults();
  }
}

run();

API Reference

Direct access to the underlying REST API that powers the SDKs, CLI, and Agentic Workflows.
Base URL: https://api.regressionbot.com

post/crawl

Start a visual regression job

Triggers a new visual regression job for a single URL or a sitemap.

Request Body

{
  "project": "string",
  "testOrigin": "string",
  "url": "string",
  "sitemapUrl": "string",
  "baseOrigin": "string",
  "devices": [
    "string"
  ],
  "paths": [
    {
      "path": "string",
      "label": "string"
    }
  ],
  "scans": [
    {
      "pattern": "string",
      "options": null
    }
  ],
  "masks": [
    "string"
  ],
  "concurrency": 0
}

Responses

200Job started successfully

{
  "message": "Visual regression job started",
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}

400Invalid input

500Internal server error

get/job/{jobId}

Get job status

Retrieve the current status and progress of a visual regression job.

Responses

200Job status retrieved successfully

{
  "jobId": "string",
  "status": "string",
  "progress": {
    "total": 0,
    "completed": 0,
    "percent": "50.00"
  },
  "executionTime": 0,
  "results": [
    {
      "url": "string",
      "status": "string",
      "diffCount": 0,
      "diffPercentage": 0,
      "currentKey": "string",
      "baselineKey": "string",
      "diffKey": "string"
    }
  ],
  "collageKey": "string",
  "createdAt": "string"
}

404Job not found

get/job/{jobId}/summary

Get job summary with signed URLs

Retrieve a summary of the completed job, including pre-signed URLs for diff images.

Responses

200Job summary retrieved successfully

{
  "jobId": "string",
  "status": "string",
  "totalUrls": 0,
  "completedCount": 0,
  "overallScore": 98.5,
  "executionTime": 0,
  "regressionCount": 0,
  "matchCount": 0,
  "newBaselineCount": 0,
  "errorCount": 0,
  "collageUrl": "string",
  "regressions": [
    {
      "url": "string",
      "variantName": "Desktop Chrome",
      "diffCount": 0,
      "baselineUrl": "string",
      "currentUrl": "string",
      "diffUrl": "string"
    }
  ],
  "matches": [
    {
      "url": "string",
      "variantName": "string",
      "baselineUrl": "string",
      "currentUrl": "string"
    }
  ],
  "newBaselines": [
    {
      "url": "string",
      "variantName": "string"
    }
  ],
  "errors": [
    {
      "url": "string",
      "errorMessage": "string"
    }
  ]
}

400Job not completed yet

404Job not found

get/job/{jobId}/collage

Generate and get regression collage

On-demand generation of a single collage image containing all detected regressions.

Responses

200Collage generated successfully

{
  "jobId": "string",
  "collageKey": "string",
  "collageUrl": "string",
  "regressionCount": 0
}

404Job not found or no regressions found

500Failed to generate collage

post/approve

Approve job baselines

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

Request Body

{
  "jobId": "string"
}

Responses

200Baselines approved successfully

{
  "message": "Job baseline approved",
  "jobId": "string",
  "approvedUrlsCount": 0
}

404Job not found