regressionbot 0.0.1

package/README.md

@@ -0,0 +1,125 @@
+# RegressionBot SDK
+
+The declarative visual regression testing SDK.
+
+## 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.
+- **Project-Based Baselines**: Share visual history across different environments (Preview vs Prod).
+
+## Installation
+
+```bash
+npm install regressionbot
+```
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { Visual } from 'regressionbot';
+
+const visual = new Visual();
+
+const job = await visual
+  .test('https://preview.myapp.com')
+  .forProject('my-app-web')
+  .run();
+
+const status = await job.waitForCompletion();
+console.log(`Stability Score: ${status.overallScore}/100`);
+```
+
+### Full Matrix Example
+
+```typescript
+import { Visual } from 'regressionbot';
+
+const visual = new Visual(process.env.API_KEY);
+
+const job = await visual
+  .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}`);
+```
+
+## CLI Usage
+
+The `regressionbot` CLI is the easiest way to interact with the 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.
+```bash
+npx regressionbot https://example.com --project my-site --on "Desktop Chrome, iPhone 12"
+```
+
+#### 2. Sitemap Scan
+Test an entire site using glob patterns.
+```bash
+npx regressionbot https://example.com --scan "/**" --exclude "/admin/**" --concurrency 20
+```
+
+#### 3. Job Summary
+Get detailed results and diff URLs for a completed job.
+```bash
+npx regressionbot summary <jobId>
+```
+
+Add the `--download` flag to save regression images locally:
+```bash
+npx regressionbot summary <jobId> --download
+```
+
+#### 4. Approve Changes
+Promote the current screenshots of a job to be the new baselines.
+```bash
+npx regressionbot approve <jobId>
+```
+
+## Development
+
+### Versioning
+
+```bash
+npm version patch # or minor/major
+npm publish
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+function parseArgs(args) {
+    const options = { _: [] };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const value = args[i + 1];
+            if (value && !value.startsWith('--')) {
+                options[key] = value;
+                i++;
+            }
+            else {
+                options[key] = true;
+            }
+        }
+        else {
+            options._.push(arg);
+        }
+    }
+    return options;
+}
+const argv = parseArgs(process.argv.slice(2));
+const command = argv._[0];
+const param = argv._[1];
+const sdk = new index_1.Visual();
+async function main() {
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        showHelp();
+        return;
+    }
+    try {
+        if (command === 'status') {
+            if (!param)
+                throw new Error('Job ID is required for status command.');
+            await checkStatus(param);
+        }
+        else if (command === 'summary') {
+            if (!param)
+                throw new Error('Job ID is required for summary command.');
+            await showSummary(param, argv);
+        }
+        else if (command === 'approve') {
+            if (!param)
+                throw new Error('Job ID is required for approve command.');
+            await approveJob(param);
+        }
+        else if (command.startsWith('http')) {
+            // Implicit test command
+            await startJob(command, argv);
+        }
+        else {
+            console.error(`Unknown command: ${command}`);
+            showHelp();
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(`
+Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+function showHelp() {
+    console.log(`
+RegressionBot CLI
+
+Usage:
+  npx regressionbot <url>           Quick test a URL.
+  npx regressionbot status <jobId>  Check the status of a specific job.
+  npx regressionbot summary <jobId> Get detailed results and diff URLs.
+                                     Use --download to save images locally.
+  npx regressionbot approve <jobId> Approve a job's results as new baselines.
+
+Options for <url>:
+  --project <id>       Required project ID.
+  --against <url>      Base origin to compare against.
+  --sitemap <url>      Explicit sitemap.xml location.
+  --on <devices>       Comma-separated device names (e.g. "Desktop Chrome,iPhone 12").
+  --scan <pattern>     Glob pattern to scan in sitemap (e.g. "/blog/**").
+  --exclude <patterns> Comma-separated glob patterns to exclude.
+  --concurrency <n>    Max concurrent workers (default 10).
+  --auto-approve       Automatically approve results as new baselines.
+  --mask <selectors>   Comma-separated CSS selectors to hide (e.g. ".ad,#popup").
+
+Environment Variables:
+  REGRESSIONBOT_API_KEY   Override the API Key.
+  REGRESSIONBOT_API_URL   Override the API URL.
+`);
+}
+async function startJob(url, options) {
+    console.log(`🚀 Initializing visual test...`);
+    const projectId = options.project || new URL(url).hostname;
+    const devices = options.on ? options.on.split(',').map((s) => s.trim()) : ['Desktop Chrome'];
+    const builder = sdk.test(url)
+        .forProject(projectId)
+        .on(devices)
+        .concurrency(Number(options.concurrency) || 10);
+    if (options.against) {
+        builder.against(options.against);
+    }
+    if (options.sitemap) {
+        builder.sitemap(options.sitemap);
+    }
+    if (options.scan) {
+        const exclude = options.exclude ? options.exclude.split(',').map((s) => s.trim()) : [];
+        builder.scan(options.scan, { exclude });
+    }
+    if (options['auto-approve']) {
+        builder.autoApprove(true);
+    }
+    if (options.mask) {
+        const selectors = options.mask.split(',').map((s) => s.trim());
+        builder.mask(selectors);
+    }
+    const job = await builder.run();
+    console.log(`✅ Job started! ID: ${job.jobId}`);
+    console.log(`📊 Project: ${projectId}`);
+    console.log(`📱 Matrix: ${devices.join(', ')}`);
+    if (options.scan) {
+        console.log(`🔍 Scan: ${options.scan} (Exclude: ${options.exclude || 'none'})`);
+    }
+    console.log(`
+Waiting for completion...
+`);
+    const result = await job.waitForCompletion(2000, (status) => {
+        const progress = status.progress || { percent: '0' };
+        process.stdout.write(`\r   Status: ${status.status} (${progress.percent}%)`);
+    });
+    console.log('\n\n✅ Job Completed.');
+    const summary = await job.getSummary();
+    console.log(`Overall Stability Score: ${summary.overallScore}/100`);
+    console.log(`Total Tasks: ${summary.totalUrls}`);
+    console.log(`Regressions: ${summary.regressionCount}`);
+    console.log(`New Baselines: ${summary.newBaselineCount}`);
+    console.log(`Errors: ${summary.errorCount}`);
+    if (summary.newBaselineCount > 0) {
+        console.log('\n✨ New Baselines Created:');
+        summary.newBaselines.forEach((nb) => {
+            console.log(`- ${nb.url} [${nb.variantName}]`);
+        });
+    }
+    if (summary.regressionCount > 0) {
+        console.log('\n❌ Regressions found:');
+        summary.regressions.forEach((r) => {
+            console.log(`- ${r.url} [${r.variantName}] (Score: ${r.score.toFixed(2)})`);
+            console.log(`  Diff: ${r.diffUrl}`);
+        });
+        console.log(`\nTo approve these changes, run:\n  npx regressionbot approve ${job.jobId}`);
+        process.exit(1);
+    }
+    else if (summary.errorCount > 0) {
+        console.log('\n⚠️ Errors encountered:');
+        summary.errors.forEach((e) => {
+            console.log(`- ${e.url}: ${e.errorMessage}`);
+        });
+        process.exit(1);
+    }
+    else {
+        console.log('\n✨ No regressions found. All good!');
+    }
+}
+async function checkStatus(jobId) {
+    const job = sdk.job(jobId);
+    const status = await job.getStatus();
+    console.log(JSON.stringify(status, null, 2));
+}
+async function showSummary(jobId, options = {}) {
+    const job = sdk.job(jobId);
+    const summary = await job.getSummary();
+    console.log(`
+Job Summary: ${jobId}
+Status: ${summary.status}
+Overall Score: ${summary.overallScore}/100
+Execution Time: ${summary.executionTime}s
+Total Tasks: ${summary.totalUrls}
+Regressions: ${summary.regressionCount}
+Matches: ${summary.matchCount}
+Errors: ${summary.errorCount}
+`);
+    if (summary.collageUrl) {
+        console.log(`Collage: ${summary.collageUrl}`);
+        if (options.download) {
+            const fs = require('fs');
+            const path = require('path');
+            const dir = path.join(process.cwd(), 'regressions', jobId);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            const res = await fetch(summary.collageUrl);
+            const buffer = Buffer.from(await res.arrayBuffer());
+            const filePath = path.join(dir, 'collage.jpg');
+            fs.writeFileSync(filePath, buffer);
+            console.log(`💾 Downloaded collage to: ${filePath}\n`);
+        }
+    }
+    if (summary.regressionCount > 0) {
+        console.log('❌ Regressions found:');
+        for (const r of summary.regressions) {
+            console.log(`- ${r.url} [${r.variantName}] (Score: ${r.score.toFixed(2)})`);
+            console.log(`  Diff: ${r.diffUrl}`);
+            if (options.download) {
+                const fs = require('fs');
+                const path = require('path');
+                const dir = path.join(process.cwd(), 'regressions', jobId, r.variantName);
+                if (!fs.existsSync(dir))
+                    fs.mkdirSync(dir, { recursive: true });
+                const download = async (url, name) => {
+                    const res = await fetch(url);
+                    const buffer = Buffer.from(await res.arrayBuffer());
+                    const filePath = path.join(dir, name);
+                    fs.writeFileSync(filePath, buffer);
+                    console.log(`  💾 Downloaded: ${name}`);
+                };
+                await download(r.baselineUrl, 'baseline.png');
+                await download(r.currentUrl, 'current.png');
+                await download(r.diffUrl, 'diff.png');
+            }
+        }
+    }
+    if (summary.errorCount > 0) {
+        console.log('\n⚠️ Errors encountered:');
+        summary.errors.forEach((e) => {
+            console.log(`- ${e.url}: ${e.errorMessage}`);
+        });
+    }
+}
+async function approveJob(jobId) {
+    console.log(`Approving baselines for job: ${jobId}...`);
+    const job = sdk.job(jobId);
+    const res = await job.approve();
+    console.log(`Success! ${res.message}`);
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { JobStatus, JobSummary } from './types';
+export declare class Visual {
+    private apiKey;
+    private apiUrl;
+    constructor(apiKey?: string, apiUrl?: string);
+    /**
+     * Set the candidate URL/Origin to test.
+     */
+    test(origin: string): JobBuilder;
+    /**
+     * Get a handle to an existing job.
+     */
+    job(jobId: string): JobHandle;
+    _request<T>(path: string, method?: string, body?: any): Promise<T>;
+}
+export declare class JobBuilder {
+    private sdk;
+    private manifest;
+    constructor(sdk: Visual, testOrigin: string);
+    against(origin: string): this;
+    sitemap(url: string): this;
+    forProject(id: string): this;
+    /**
+     * Define the matrix: list of Playwright devices or viewport names.
+     */
+    on(variants: string[]): this;
+    /**
+     * Add a specific page to the test scope.
+     */
+    check(path: string, label?: string): this;
+    /**
+     * Add a discovery rule to scan the sitemap.
+     */
+    scan(pattern: string, options?: {
+        limit?: number;
+        exclude?: string[];
+    }): this;
+    concurrency(n: number): this;
+    autoApprove(val?: boolean): this;
+    mask(selectors: string[]): this;
+    /**
+     * Compiles the manifest and triggers the API.
+     */
+    run(): Promise<JobHandle>;
+}
+export declare class JobHandle {
+    private sdk;
+    jobId: string;
+    constructor(sdk: Visual, jobId: string);
+    getStatus(): Promise<JobStatus>;
+    getSummary(): Promise<JobSummary>;
+    approve(): Promise<{
+        message: string;
+    }>;
+    waitForCompletion(intervalMs?: number, callback?: (status: JobStatus) => void): Promise<JobStatus>;
+}

package/dist/index.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobHandle = exports.JobBuilder = exports.Visual = void 0;
+class Visual {
+    apiKey;
+    apiUrl;
+    constructor(apiKey, apiUrl) {
+        this.apiKey = apiKey || process.env.REGRESSIONBOT_API_KEY || "";
+        this.apiUrl = apiUrl || process.env.REGRESSIONBOT_API_URL || "https://api.regressionbot.com";
+        if (!this.apiKey) {
+            console.warn("Warning: No API Key provided. Set REGRESSIONBOT_API_KEY environment variable or pass it to the constructor.");
+        }
+        if (this.apiUrl.endsWith('/')) {
+            this.apiUrl = this.apiUrl.slice(0, -1);
+        }
+    }
+    /**
+     * Set the candidate URL/Origin to test.
+     */
+    test(origin) {
+        return new JobBuilder(this, origin);
+    }
+    /**
+     * Get a handle to an existing job.
+     */
+    job(jobId) {
+        return new JobHandle(this, jobId);
+    }
+    // Internal fetch wrapper
+    async _request(path, method = 'GET', body) {
+        const headers = {
+            'Content-Type': 'application/json',
+            'x-api-key': this.apiKey
+        };
+        const response = await fetch(`${this.apiUrl}${path}`, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`API Error ${response.status}: ${errorText}`);
+        }
+        return response.json();
+    }
+}
+exports.Visual = Visual;
+class JobBuilder {
+    sdk;
+    manifest;
+    constructor(sdk, testOrigin) {
+        this.sdk = sdk;
+        this.manifest = {
+            testOrigin: testOrigin.replace(/\/$/, ''),
+            variants: [],
+            checks: [],
+            scans: [],
+            concurrency: 10
+        };
+    }
+    against(origin) {
+        this.manifest.baseOrigin = origin.replace(/\/$/, '');
+        return this;
+    }
+    sitemap(url) {
+        this.manifest.sitemapUrl = url;
+        return this;
+    }
+    forProject(id) {
+        this.manifest.projectId = id;
+        return this;
+    }
+    /**
+     * Define the matrix: list of Playwright devices or viewport names.
+     */
+    on(variants) {
+        this.manifest.variants.push(...variants);
+        return this;
+    }
+    /**
+     * Add a specific page to the test scope.
+     */
+    check(path, label) {
+        this.manifest.checks.push({ path, label });
+        return this;
+    }
+    /**
+     * Add a discovery rule to scan the sitemap.
+     */
+    scan(pattern, options) {
+        this.manifest.scans.push({ pattern, options });
+        return this;
+    }
+    concurrency(n) {
+        this.manifest.concurrency = n;
+        return this;
+    }
+    autoApprove(val = true) {
+        this.manifest.autoApprove = val;
+        return this;
+    }
+    mask(selectors) {
+        this.manifest.masks = selectors;
+        return this;
+    }
+    /**
+     * Compiles the manifest and triggers the API.
+     */
+    async run() {
+        if (!this.manifest.projectId) {
+            throw new Error('Project ID is required. Use .forProject("id")');
+        }
+        // If no checks/scans provided, default to root
+        if (this.manifest.checks.length === 0 && this.manifest.scans.length === 0) {
+            this.manifest.checks.push({ path: '/', label: 'Home' });
+        }
+        const payload = {
+            project: this.manifest.projectId,
+            testOrigin: this.manifest.testOrigin,
+            sitemapUrl: this.manifest.sitemapUrl,
+            baseOrigin: this.manifest.baseOrigin,
+            devices: this.manifest.variants,
+            paths: this.manifest.checks,
+            scans: this.manifest.scans,
+            concurrency: this.manifest.concurrency,
+            autoApprove: this.manifest.autoApprove,
+            masks: this.manifest.masks
+        };
+        const res = await this.sdk._request('/crawl', 'POST', payload);
+        return new JobHandle(this.sdk, res.jobId);
+    }
+}
+exports.JobBuilder = JobBuilder;
+class JobHandle {
+    sdk;
+    jobId;
+    constructor(sdk, jobId) {
+        this.sdk = sdk;
+        this.jobId = jobId;
+    }
+    async getStatus() {
+        return this.sdk._request(`/job/${this.jobId}`);
+    }
+    async getSummary() {
+        return this.sdk._request(`/job/${this.jobId}/summary`);
+    }
+    async approve() {
+        return this.sdk._request('/approve', 'POST', { jobId: this.jobId });
+    }
+    async waitForCompletion(intervalMs = 2000, callback) {
+        await new Promise(resolve => setTimeout(resolve, 3000));
+        while (true) {
+            const status = await this.getStatus();
+            if (callback)
+                callback(status);
+            if (status.status === 'COMPLETED' || status.status === 'APPROVED')
+                return status;
+            if (status.status === 'FAILED')
+                throw new Error(`Job Failed: ${status.error}`);
+            await new Promise(resolve => setTimeout(resolve, intervalMs));
+        }
+    }
+}
+exports.JobHandle = JobHandle;

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+export interface VRConfig {
+    apiKey?: string;
+    apiUrl?: string;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export declare const Viewports: {
+    readonly DESKTOP: {
+        readonly width: 1920;
+        readonly height: 1080;
+    };
+    readonly LAPTOP: {
+        readonly width: 1366;
+        readonly height: 768;
+    };
+    readonly TABLET: {
+        readonly width: 768;
+        readonly height: 1024;
+    };
+    readonly MOBILE: {
+        readonly width: 375;
+        readonly height: 667;
+    };
+};
+export interface JobResult {
+    url: string;
+    status: 'SUCCESS' | 'ERROR';
+    diffCount?: number;
+    diffPercentage?: number;
+    score?: number;
+    currentKey?: string;
+    baselineKey?: string;
+    diffKey?: string;
+    isNewBaseline?: boolean;
+}
+export interface JobStatus {
+    jobId: string;
+    status: 'PROCESSING' | 'COMPLETED' | 'APPROVED' | 'FAILED' | 'INITIALIZING';
+    error?: string;
+    progress?: {
+        total: number;
+        completed: number;
+        percent: string;
+    };
+    executionTime?: number;
+    results?: JobResult[];
+    createdAt?: string;
+    collageKey?: string;
+}
+export interface JobSummary {
+    jobId: string;
+    status: string;
+    totalUrls: number;
+    completedCount: number;
+    overallScore: number;
+    executionTime: number;
+    regressionCount: number;
+    matchCount: number;
+    newBaselineCount: number;
+    errorCount: number;
+    collageUrl?: string;
+    regressions: Array<{
+        url: string;
+        variantName: string;
+        diffCount: number;
+        score: number;
+        baselineUrl: string;
+        currentUrl: string;
+        diffUrl: string;
+    }>;
+    matches: Array<{
+        url: string;
+        variantName: string;
+        score: number;
+        baselineUrl: string;
+        currentUrl: string;
+    }>;
+    newBaselines: Array<{
+        url: string;
+        variantName: string;
+    }>;
+    errors: Array<{
+        url: string;
+        errorMessage: string;
+        score: number;
+    }>;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Viewports = void 0;
+exports.Viewports = {
+    DESKTOP: { width: 1920, height: 1080 },
+    LAPTOP: { width: 1366, height: 768 },
+    TABLET: { width: 768, height: 1024 },
+    MOBILE: { width: 375, height: 667 }
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "regressionbot",
+  "version": "0.0.1",
+  "description": "The official SDK for regressionbot.com - the simplest way to automate visual regression testing.",
+  "homepage": "https://regressionbot.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cbestall/vr-api.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/cbestall/vr-api/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "regressionbot": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "visual-regression",
+    "testing",
+    "sdk",
+    "cli"
+  ],
+  "author": "RegressionBot (https://regressionbot.com)",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}