How to Configure Reg-suit with Puppeteer

To configure reg-suit with Puppeteer, have Puppeteer save screenshots to a directory, then set reg-suit’s core.actualDir to that same directory. Run the capture script before npx reg-suit run. Puppeteer creates the current images; reg-suit retrieves the expected snapshots, compares them, and generates a report.

The examples below use a project-local screenshot/ directory. The important contract is that the capture script’s output path and actualDir match. The code is a starting point; set the page readiness condition and viewport to match your application.

1. Install Puppeteer and reg-suit

From your project directory, install Puppeteer and initialize reg-suit:

npm install --save-dev puppeteer reg-suit
npx reg-suit init

The reg-suit initializer can help select a key-generator and a publisher plugin. The example configuration below uses the Git-hash key-generator and S3 publisher shown in the project documentation. Install and configure the plugins you actually select; plugin fields and credential requirements depend on their versions and storage provider. The project also lists a simple key-generator and a Google Cloud Storage publisher.

2. Capture screenshots with Puppeteer

Create scripts/capture-screenshots.cjs:

const fs = require('node:fs/promises');
const path = require('node:path');
const puppeteer = require('puppeteer');

async function main() {
  const outputDir = path.resolve('screenshot');
  await fs.mkdir(outputDir, { recursive: true });

  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.setViewport({ width: 1280, height: 800, deviceScaleFactor: 1 });

    await page.goto('http://localhost:3000/', {
      waitUntil: 'networkidle0',
      timeout: 60000
    });

    // Replace this with an application-specific readiness check when possible.
    await page.waitForSelector('[data-test="visual-ready"]', { timeout: 15000 });

    await page.screenshot({
      path: path.join(outputDir, 'home.png'),
      fullPage: true
    });
  } finally {
    await browser.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Use a stable route and filename on every run. If you capture multiple pages, give each a deterministic filename, such as account-settings.png or products-list.png. Avoid filenames containing timestamps or random identifiers: reg-suit needs to associate current images with the corresponding expected images.

networkidle0 is useful for pages that settle after network requests, but analytics, polling, or streaming connections can prevent it from completing. For those pages, use a more appropriate navigation condition and wait for a page-specific selector or application readiness signal. A fixed delay can be a fallback, but it can be both slower and less reliable than checking an actual ready state.

3. Point reg-suit at the capture directory

Configure regconfig.json in the project root. This example uses the S3 publisher and Git-hash key-generator demonstrated by reg-suit:

{
  "core": {
    "workingDir": ".reg",
    "actualDir": "screenshot",
    "thresholdRate": 0.05
  },
  "plugins": {
    "reg-keygen-git-hash-plugin": {},
    "reg-publish-s3-plugin": {
      "bucketName": "your-aws-s3-bucket"
    }
  }
}

This illustrates the configuration shape, not a universal set of plugin settings. Check the installed plugin’s documentation for supported fields, access policy, region, and credentials. Keep credentials in your CI secret store or environment rather than committing them to this file.

Setting	Purpose	Practical guidance
`core.actualDir`	Directory containing current screenshots	Required. It must match the capture script output directory.
`core.workingDir`	reg-suit working files	Defaults to `.reg` in the documented core configuration.
`core.thresholdRate`	Allowed differing-pixel rate	Documented range is 0 to 1. Choose based on tolerated visual noise.
`core.thresholdPixel`	Alternative absolute differing-pixel threshold	Use when an absolute pixel count is easier to reason about than a rate.
`core.concurrency`	Controls comparison concurrency	Documented default is 4. Adjust only if resource limits or workload warrant it.
`plugins`	Key-generator and publisher configuration	Plugin package names are keys; values are plugin-specific settings.

Thresholds trade sensitivity for tolerance. A zero threshold can flag small rendering differences; a larger threshold may suppress insignificant changes but can also hide a real, small regression. Start with the strictness your review process needs, inspect reports, and adjust deliberately.

4. Run capture before comparison

Add scripts to package.json so the order is explicit:

{
  "scripts": {
    "capture": "node scripts/capture-screenshots.cjs",
    "visual-regression": "npm run capture && reg-suit run"
  }
}

Then run:

npm run visual-regression

The reg-suit CLI run syncs expected snapshots, compares them with the actual images, builds an HTML report, and can publish images and reports or notify through configured plugins. On the first run, the workflow may report images as new because no expected snapshots have been published yet. Treat that run as baseline creation: review the captured images and report, then publish the baseline through your configured publisher.

5. Add the workflow to CI

A CI job should install dependencies, start the application, wait until it is ready, capture screenshots, and run reg-suit. The exact YAML depends on your CI provider and application startup process. Keep these requirements in view:

Use a supported Node runtime and compatible Puppeteer, browser, reg-suit, and plugin versions.
Start the app on a known local address and wait for its readiness endpoint or log before capturing.
Provide enough Git history and branch information for the selected key-generator. A Git-graph-based key generator can fail or choose an unexpected key when CI checks out only a shallow commit.
Provide cloud credentials securely to the job with the permissions required by the selected publisher.
Preserve the reg-suit report as a CI artifact or publish it with the configured plugin so reviewers can inspect differences.

Do not copy old CI snippets without checking their assumptions. The historical reg-puppeteer-demo uses Node 8 and CircleCI 2 syntax and demonstrates reg-suit 0.6.1; those details are not a current compatibility recommendation. Its Puppeteer launch also includes --no-sandbox and --disable-setuid-sandbox. Those flags are specific to that old sample; evaluate the browser sandbox and container security model before changing launch arguments.

6. Keep Puppeteer configuration separate

Puppeteer configuration controls browser installation and Puppeteer behavior; it does not replace reg-suit’s regconfig.json. Puppeteer supports configuration files such as .puppeteerrc.json, .puppeteerrc.js, puppeteer.config.js, and configuration in package.json. Its standard package downloads a specific Chrome version by default, and the configuration guide describes specifying another executable path. Puppeteer configuration files and environment variables are ignored by puppeteer-core. When changing browser download settings, the documented command to apply installation configuration is:

npx puppeteer browsers install

Check the official Puppeteer configuration guide for the configuration supported by your installed version.

7. Common problems and fixes

Symptom	Likely cause	Fix
No actual images found	The capture script did not run, wrote to another directory, or failed before saving.	Run the capture script by itself, inspect its exit code, and make `actualDir` match the resolved output path.
Every image appears new	No expected baseline exists for the selected key, or the key-generator maps this run to a different revision key.	Review the initial report and publish the intended baseline. Check key-generator configuration and Git history.
Browser launch fails in CI	Browser installation, runtime libraries, executable path, or runtime compatibility is wrong.	Confirm Puppeteer’s configured browser is installed in the CI environment, review its launch error, and align the Node runtime, Puppeteer version, browser, and CI image.
Navigation times out	The page never reaches the selected lifecycle condition, or the application is not ready.	Check that the app is running and reachable. Use an appropriate `waitUntil` condition and a page-specific readiness selector; set a timeout that reflects the environment.
Images differ on every run	Dynamic content, animation, fonts, data, viewport, or browser versions vary between captures.	Use stable test data, disable or freeze animations in the test environment, wait for fonts and content, and pin the viewport and browser/runtime versions.
Expected images cannot be retrieved or published	Publisher configuration, credentials, bucket access, or selected key is incorrect.	Check the installed publisher’s current documentation, job secrets and permissions, and the key-generator output. Confirm the target storage location exists when required by that plugin.
Too many tiny differences are reported	Rendering noise or a very strict threshold is triggering comparisons.	First stabilize rendering inputs. Then choose a justified rate or pixel threshold and inspect the report for changes that a tolerance could conceal.

8. Performance, reliability, and cost

Capture time is mostly affected by application startup, navigation, readiness waits, page count, and screenshot size. Start the application once per job where possible, avoid unnecessarily long fixed sleeps, and capture only the routes you need. reg-suit’s documented comparison concurrency defaults to 4; raising parallel work can increase resource use, while reducing it can help constrained CI runners.

For reliable comparisons, keep viewport dimensions, device scale factor, browser version, test data, locale-sensitive content, and page state consistent. Use explicit readiness conditions instead of assuming a page is ready after navigation. Make the capture step fail the CI job when a required screenshot is missing; otherwise reg-suit may compare an incomplete set.

The tool configuration itself does not establish a fixed cost. Account for your CI runner and the chosen snapshot storage provider, including their current pricing and retention policies. The sources for this guide do not establish a benchmark or universal cost for a given number of pages.

Or skip the browser setup

If your task is to capture pages rather than build a repeatable visual-regression pipeline, ScreenshotNeo is a website screenshot API and MCP server for developers. A GET request returns a PNG, JPEG, WebP, or PDF. For example, this cURL call saves a WebP screenshot; see the ScreenshotNeo API docs for options and response details:

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

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

FAQ

Can I use a different screenshot directory?

Yes. Set the capture script’s output directory and core.actualDir to the same path.

Does Puppeteer replace reg-suit?

No. Puppeteer captures browser images; reg-suit handles expected snapshots, comparisons, reporting, and configured publishing.

Should I use rate or pixel thresholds?

Both are documented options. Choose the one that best matches how your team defines an acceptable difference, then review reports to ensure the tolerance does not hide meaningful changes.

Can this workflow use a storage provider other than S3?

Yes. reg-suit lists publisher options including S3 and Google Cloud Storage. Configure the plugin that matches your storage setup and verify its current requirements.