Reg Suit with Playwright Screenshots: How-To

This guide shows you how to use reg-suit, a visual regression testing tool, to compare Playwright screenshots. You’ll learn to set up a project, capture baseline images, run comparisons, and integrate it into your workflow. By the end, you’ll have automated visual checks that catch unintended UI changes before they reach production.

What You’ll Need

• Node.js (v14 or later) installed
• A Playwright project with tests that can capture screenshots
• Basic familiarity with the command line
• An S3 bucket or other storage provider (for storing snapshots) – optional but recommended for team use

Step-by-Step

1. Install reg-suit and its plugins – In your project root, run:

   npm install -D reg-suit reg-cli

   This installs the core CLI and the comparison plugin. If you plan to use S3 for storage, also install reg-suit-plugin-s3.

2. Initialize reg-suit – Run npx reg-suit init. It will ask a few questions: choose your storage provider (e.g., S3, local), the bucket name (if S3), and the directory for snapshots. This creates a regconfig.json file.
3. Create a Playwright script to capture screenshots – Write a script (e.g., screenshot.js) that uses Playwright to navigate to your pages and take full-page screenshots. Save them to a folder like snapshots/actual. Example:

   const { chromium } = require('playwright');
   (async () => {
     const browser = await chromium.launch();
     const page = await browser.newPage();
     await page.goto('https://example.com');
     await page.screenshot({ path: 'snapshots/actual/home.png', fullPage: true });
     await browser.close();
   })();

4. Set up the expected directory – reg-suit compares two folders: the expected (baseline) and the actual (current). By default, reg-suit uses snapshots/expected for the baseline. Create this folder and copy your initial screenshots into it.
5. Run the comparison – Execute npx reg-suit run. This will compare the files in the expected and actual directories. If differences are found, it generates a report in .reg folder and prints a summary.
6. View the report – Open .reg/index.html in your browser to see a side-by-side diff view with highlighted changes.
7. Update the baseline – When you intentionally change the UI, run npx reg-suit run --update to replace the expected images with the current actual ones.
8. Integrate into CI – For continuous integration, run your Playwright script to generate actual screenshots, then run reg-suit run. If the command exits with a non-zero code, the build fails. Configure reg-suit to upload the report to S3 for easy review.

Common Mistakes

• Not using fullPage: true – If you only capture the viewport, changes below the fold go unnoticed. Use fullPage: true for complete coverage.
• Ignoring dynamic content – Animations, carousels, or ads cause flaky diffs. Freeze them or wait for them to settle before taking the screenshot.
• Mismatched file names – reg-suit matches files by relative path. Ensure the expected and actual folders have the same structure and file names.
• Forgetting to update the baseline – After intentional changes, always run with --update; otherwise, every run will fail.
• Using a different browser or viewport – Screenshots must be taken with the same browser engine and viewport size to avoid false positives.

Tips

• Use a fixed viewport – Set the viewport size in your Playwright script (e.g., 1280×720) to ensure consistency.
• Wait for network idle – Use page.waitForLoadState('networkidle') before capturing to avoid missing late-loading assets.
• Organize screenshots by feature – Create subfolders like home, pricing, etc., to keep the report manageable.
• Set a threshold – In regconfig.json, you can set a threshold (e.g., 0.01) to ignore tiny pixel differences caused by antialiasing.
• Use Git hooks – Run the comparison on pre-commit to catch visual regressions early.

Troubleshooting

• Error: “No such file or directory” – Make sure the expected folder exists and contains the baseline images. Create it if needed.
• Report says “0 differences” but you know there are changes – Check that the actual screenshots were actually updated. Re-run your Playwright script to regenerate them.
• Diff images are all red – This often means the entire page changed, possibly due to a different viewport or a missing wait. Compare the dimensions of the images.
• reg-suit hangs on S3 upload – Verify your AWS credentials and bucket name in regconfig.json. Also ensure the bucket region is set correctly.
• Command not found – If npx reg-suit fails, try installing globally: npm install -g reg-suit.

Frequently Asked Questions

Can I use reg-suit with Playwright’s built-in screenshot feature?

Yes, Playwright’s page.screenshot() is exactly what you use to capture images. reg-suit just compares them.

Do I need an S3 bucket?

No, you can use local storage for solo projects. S3 is useful for sharing reports with your team.

How do I ignore a specific area of the page?

reg-suit doesn’t support masking areas directly. Instead, you can exclude certain files by name or use a custom script to crop out dynamic regions.

What is the difference between reg-suit and Playwright’s visual comparisons?

Playwright has a built-in toHaveScreenshot() for simple assertions. reg-suit provides a more robust workflow with HTML reports, baseline management, and CI integration.

Can I run reg-suit on multiple browsers?

Yes, but you need to store screenshots from each browser in separate folders (e.g., snapshots/chromium, snapshots/firefox) and run reg-suit for each.

Is reg-suit free?

Yes, reg-suit is open-source and free to use.

Related

• Open-Source Alternatives to AI Agent Security Platforms
• Claude Managed Agents vs LangGraph: Which Should You Use?
• Radio Telescopes: How They Detect Black Hole Jets