Playwright Integration

The official Playwright integration client for RegressionBot allows you to capture high-resolution screenshots directly from your local or CI/CD Playwright execution, streaming them to the cloud for automated, parallel pixel comparison.

🔑 Prerequisite: API Key RequiredYou will need an active API key to initialize the Playwright runner connection.

Get API Key →

npm install --save-dev @regressionbot/playwright

Quick Start

Integrating RegressionBot into an existing Playwright test suite takes just three steps.

1. Configure Environment Variables

Expose your API key in your terminal session or CI environment.

export REGRESSIONBOT_API_KEY="your_regressionbot_api_key"

2. Set Up Playwright Hooks

Since Playwright runs tests across multiple worker processes, you must initialize and finalize jobs in separate global hook files.

global-setup.ts

import { FullConfig } from '@playwright/test';
import { initializeJob } from '@regressionbot/playwright';

async function globalSetup(config: FullConfig) {
  await initializeJob({
    project: 'my-frontend-app',
    testOrigin: 'http://localhost:3000', // The target URL of your test app
    devices: ['Desktop Chrome', 'iPhone 13'],
  });
}

export default globalSetup;

global-teardown.ts

import { FullConfig } from '@playwright/test';
import { finalizeJob } from '@regressionbot/playwright';

async function globalTeardown(config: FullConfig) {
  await finalizeJob();
}

export default globalTeardown;

playwright.config.ts

import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalSetup: require.resolve('./global-setup'),
  globalTeardown: require.resolve('./global-teardown'),
  use: {
    baseURL: 'http://localhost:3000',
  },
});

3. Capture Visuals In Spec Files

Call the asynchronous captureVisual method to queue screenshot capture and comparison.

tests/example.spec.ts

import { test } from '@playwright/test';
import { captureVisual } from '@regressionbot/playwright';

test('Homepage visual verification', async ({ page }, testInfo) => {
  await page.goto('/');
  
  // Parameterize variantName with the active project/device name to avoid S3 key collisions in multi-device runs
  const deviceName = testInfo.project.name.toLowerCase().replace(/\s+/g, '_');
  await captureVisual(page, `homepage_${deviceName}`);
});

test('Dashboard with dynamic widgets', async ({ page }) => {
  await page.goto('/dashboard');
  
  // Mask dynamic dashboard elements to prevent false positives
  await captureVisual(page, 'dashboard_metrics', {
    mask: ['.dynamic-charts', '.user-welcome-message', 'time.live-clock']
  });
});

API Reference

`initializeJob(config: SdkInitConfig): Promise<string>`

Initiates a visual regression job on the RegressionBot server. Calling this method sets the process.env.REGRESSIONBOT_JOB_ID environment variable, enabling subsequent captureVisual tasks to associate their screenshot uploads with the active job.

Config Options:

project (string, required): The target project name to baseline/test.
testOrigin (string, required): The base URL (test origin) where tests are executed.
apiKey (string, optional): Your API key. Defaults to process.env.REGRESSIONBOT_API_KEY.
apiUrl (string, optional): RegressionBot API endpoint. Defaults to process.env.REGRESSIONBOT_API_URL.
branch (string, optional): Git branch name. Defaults to process.env.CI_COMMIT_REF_NAME or 'main'.
commit (string, optional): Git commit SHA. Defaults to process.env.CI_COMMIT_SHA or ''.
devices (string[], optional): Target viewports configured for comparison. Defaults to ['Desktop Chrome'].

`captureVisual(page: Page, variantName: string, options?: { mask?: string[] }): Promise<void>`

Takes a full-page screenshot of the active browser state, injects custom styles to mask selectors matching the mask array, generates a secure presigned URL, and streams the screenshot directly to RegressionBot S3 storage.

Parameters:

page (Page): The active Playwright page object instance.
variantName (string): A unique filename identifier for this screenshot (e.g. 'homepage_hero').
options.mask (string[], optional): An array of CSS selectors to mask (sets visibility: hidden !important) before capture.

`finalizeJob(): Promise<void>`

Closes the initializing state of the current visual regression job and instructs the backend server to invoke the parallel Step Functions comparisons for all uploaded screenshots. Typically called in Playwright's globalTeardown.