How to Use Reg-suit with Playwright Screenshots

Playwright captures the browser page; Reg-suit compares screenshot image files against stored snapshots and can publish comparison reports through plugins. To connect them, make your Playwright capture step write the images you want to check into a stable directory, then set Reg-suit’s core.actualDir to that directory and run reg-suit run afterward.

This is a project-specific directory handoff, not a claim of an official Reg-suit Playwright adapter or a tested, canonical integration. Playwright also has its own visual comparison API, await expect(page).toHaveScreenshot(). Choose which system owns baselines for each screenshot set to avoid duplicate comparison workflows.

1. Choose the comparison owner

Use Playwright’s built-in screenshot assertions when you want baseline creation and comparison close to the browser tests. Use Reg-suit when you want its image-directory workflow, publisher plugins, HTML report, or notification plugins. These capabilities overlap, so decide per screenshot set whether Playwright or Reg-suit owns the baseline and review signal.

Need	Possible fit
Assertions and baselines alongside Playwright tests	Playwright toHaveScreenshot()
Compare supplied image files and use Reg-suit publisher or notifier plugins	Reg-suit
Both browser-level assertions and centralized reporting	Use both only when their separate roles are clear; avoid maintaining duplicate baselines for the same set without a reason.

Reg-suit’s documented interface takes image files through core.actualDir. Its project README documents plugins, including S3 and GCS publishers. The Reg-suit demo cited in the research uses Puppeteer; the sources do not establish an official Playwright adapter.

2. Install and capture with Playwright

In an existing Node.js project, install Playwright Test and Reg-suit. The following example writes one screenshot file to screenshots/actual/home.png. It is a project-level starting point: adapt the URL, readiness condition, and filename to the application state you want to compare.

npm install --save-dev @playwright/test reg-suit
npx playwright install chromium

Create tests/capture.spec.ts:

import { test } from '@playwright/test';
import { mkdir } from 'node:fs/promises';
import { join } from 'node:path';

test('capture home page for Reg-suit', async ({ page }) => {
  await page.setViewportSize({ width: 1440, height: 900 });
  await page.goto('http://127.0.0.1:3000/', { waitUntil: 'networkidle' });
  await page.locator('main').waitFor({ state: 'visible' });

  const outputDir = join(process.cwd(), 'screenshots', 'actual');
  await mkdir(outputDir, { recursive: true });
  await page.screenshot({
    path: join(outputDir, 'home.png'),
    fullPage: true,
    animations: 'disabled',
  });
});

Run the application server before the test. For Playwright Test, a webServer entry in playwright.config.ts can start it automatically and wait for its URL:

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

export default defineConfig({
  testDir: './tests',
  use: { browserName: 'chromium' },
  webServer: {
    command: 'npm run start -- --port 3000',
    url: 'http://127.0.0.1:3000',
    reuseExistingServer: !process.env.CI,
  },
});

If your app’s start script or port differs, update both the command and URL. This config is an example; it is not a Reg-suit requirement.

3. Point Reg-suit at the captured images

Initialize Reg-suit using its documented setup entry point, then configure the generated regconfig.json for your project. The key connection is that core.actualDir must resolve to the directory containing the screenshot files when Reg-suit runs.

npx reg-suit init

For the example capture above, the relevant configuration is:

{
  "core": {
    "actualDir": "screenshots/actual",
    "workingDir": ".reg"
  }
}

Keep any plugin configuration generated or selected during initialization. Reg-suit’s README describes workingDir as temporary working space, with .reg as the default. Paths and configuration details can depend on the installed Reg-suit version; consult that version’s documentation before adding optional settings.

The complete handoff is sequential:

npx playwright test
npx reg-suit run

Playwright must finish successfully before Reg-suit runs. If you use a package script, preserve that order, for example: "visual:ci": "playwright test && reg-suit run".

4. Configure plugins, thresholds, and baselines

Plugins and storage

Reg-suit documents key generators, publishers, and notifiers, with publisher options including S3 and GCS. Choose plugins to match how your team selects the comparison baseline, stores images, and shares reports. Configure credentials and CI permissions for the storage or notification services you enable. Do not put access keys directly in source control; provide them through your CI secret mechanism.

Comparison behavior

The Reg-suit README documents configurable pixel and rate thresholds, antialias handling, matching threshold, and comparison concurrency. These settings affect how differences are assessed or processed. Check the README for your installed version before copying defaults: defaults may change, and a permissive threshold can hide a change you intended to review.

Begin with settings that make meaningful changes visible, then adjust only after inspecting real reports. A difference is a signal for human review, not proof of a functional defect.

Baseline keys and branches

If you use Reg-suit’s Git-hash key generator, it needs branch information to select a base commit. If expected images seem to come from the wrong revision or are missing, inspect checkout depth and branch state. Reg-suit documents a detached-HEAD workaround for some CI environments; its example workflow checks out full history. Treat these as environment-specific remedies, not universal CI requirements.

5. Keep screenshots stable in CI

Playwright warns that browser rendering can vary with the host OS, browser version, settings, hardware, power source, headless mode, and other factors. Generate and compare baselines in a consistent environment. Where practical, keep these aligned:

• Operating system and browser version.
• Installed fonts and font-rendering environment.
• Viewport dimensions and device scale factor.
• Headless settings and browser launch configuration.
• Application data, locale, timezone, and other state that changes rendered content.
• Animation and timing behavior, including when screenshots are taken.

Wait for a meaningful page condition, such as a visible main landmark or a specific component, rather than relying only on a fixed delay. If external content changes unpredictably, mock or otherwise stabilize it where appropriate for your application. Keep generated screenshots in the same directory and with the same naming scheme that Reg-suit expects.

6. Playwright’s built-in alternative

If you do not need Reg-suit’s image-directory workflow or plugins, Playwright can create and compare its own screenshot baselines:

import { test, expect } from '@playwright/test';

test('home page matches its screenshot', async ({ page }) => {
  await page.goto('http://127.0.0.1:3000/');
  await expect(page).toHaveScreenshot('home.png', { fullPage: true });
});

On the initial run, Playwright creates a reference screenshot; later runs compare against it. Playwright documents snapshot path configuration through testConfig.snapshotPathTemplate. Keep Playwright’s snapshots and Reg-suit’s actual images distinct unless you have a deliberate process for using both comparison systems.

7. Troubleshooting

Symptom	Likely cause	Fix
Reg-suit finds no actual images	The capture did not run, wrote elsewhere, or actualDir points to a different path.	Run Playwright first; inspect the output directory and filenames; align core.actualDir with it.
Screenshot test cannot reach the app	The server is not running, the configured port is wrong, or startup has not completed.	Start the app before capture or configure Playwright’s webServer command and URL to match the project.
Many differences appear on every CI run	Rendering environment, fonts, viewport, timing, or content varies between baseline and comparison.	Align host and browser settings; use stable page state and data; wait for a specific readiness condition.
Expected snapshots are missing or selected unexpectedly	Branch metadata, Git history depth, or detached-HEAD state prevents the key generator from identifying the intended base.	Inspect CI checkout and branch state; follow the Reg-suit documentation for the relevant key generator and environment.
Screenshot is blank or incomplete	Capture happened before the page or target component became ready, or navigation failed.	Check navigation errors and URL; wait for a visible selector or application-specific ready state before capture.
Images differ after a browser or OS update	Rendering can vary across browser versions and host environments.	Use a consistent environment and intentionally review and regenerate baselines when upgrading the rendering stack.
Publishing or notifications fail in CI	Plugin credentials or permissions are absent or insufficient.	Check the selected plugin configuration and CI secret/permission setup; avoid printing secrets into logs.

8. Performance, reliability, and cost

Capture time depends on the application, page readiness, browser startup, and the number of pages you render. Keep the capture set focused on states that provide useful coverage. Reg-suit documents comparison concurrency as configurable; tune it with your CI resource limits and installed-version guidance rather than assuming more concurrency will always help.

Reliability comes primarily from repeatable inputs: a stable browser and host, deterministic data, explicit readiness conditions, and a clear baseline selection process. Treat report differences as review items and decide intentionally whether each change is expected.

The cited project documentation does not provide a universal runtime benchmark or a cost figure for this workflow. Your CI cost depends on your own runners, browser execution, storage, and notification services. Reg-suit’s S3 and GCS publisher plugins make those storage choices possible; they do not establish provider pricing or an affiliate relationship.

Or skip the browser setup

If you need screenshots of live pages rather than browser tests against your own app, ScreenshotNeo is a screenshot API and MCP server. One GET request returns an image or PDF; see the API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Cookie and consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, with no card.

FAQ

Does Reg-suit capture screenshots from Playwright?

No. In this workflow Playwright captures the pages and Reg-suit consumes the resulting image files.

Is there an official Reg-suit Playwright adapter?

The sources reviewed for this guide do not establish one. The directory handoff shown here is a project-specific integration pattern based on Reg-suit’s image-directory configuration.

Should I use Reg-suit and toHaveScreenshot() together?

Only when each has a clear role, such as browser assertions in Playwright and centralized comparison or publishing through Reg-suit. Avoid duplicating baselines and review signals without a specific need.

Where can I read the primary documentation?

See the Reg-suit repository README, Playwright visual comparisons documentation, and the Reg-suit Puppeteer demonstration.