Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use Playwright Test’s built-in toHaveScreenshot() assertion to compare page screenshots with checked-in reference images, then run those tests in CI with the same browser and rendering environment used to establish and review the references. Start with one CI worker for predictable results; add parallel workers or sharding only when the runner and reporting workflow support them.

How Playwright screenshot tests work

Playwright Test provides visual comparisons through await expect(page).toHaveScreenshot(). On first use, the assertion creates a reference screenshot; Playwright’s documented capture process waits for two consecutive screenshots to match before saving the result. On later runs, it compares the new capture with that reference and reports differences.

A screenshot assertion checks rendered pixels, not application behavior. Keep functional assertions for things such as navigation, form submission, and accessible state. A visual difference may be an intended design change, while a page can look correct despite a broken interaction.

Make the page reproducible before capturing

Visual tests are only useful when the page reaches the same state reliably. Control the inputs that affect the rendered result before you create a baseline:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
Elebase USB to USB C Adapter for iPhone 18 Pro Max,USBC Car Charger Adapter
  • Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
  • Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
  • Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
  • Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
  • 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
  • Navigation: use a stable route and ensure the test waits for the relevant content rather than relying on a short arbitrary delay.
  • Viewport: set an explicit viewport so responsive layout does not depend on runner defaults.
  • Test data: use predictable fixtures or seeded data; avoid content that changes between runs.
  • Page readiness: wait for the page or key element to be ready before taking the screenshot.
  • Execution environment: use the same operating system, browser version, fonts, and rendering dependencies when generating, reviewing, and comparing references.

These controls reduce accidental diffs, but cannot make every rendering difference a defect. Inspect the initial image and every meaningful diff rather than automatically accepting changed references.

Add a screenshot assertion to a Playwright test

In a project already configured for Playwright Test, a minimal visual test can look like this:

Rank #2
Anker USB-C Hub, 5-in-1 USB Hub for Laptops, 4K HDMI Multiport Adapter
  • 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
  • 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
  • Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
  • 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
  • What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
import { test, expect } from '@playwright/test';

test('home page matches its visual reference', async ({ page }) => {
  await page.setViewportSize({ width: 1280, height: 800 });
  await page.goto('http://127.0.0.1:3000/');
  await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
  await expect(page).toHaveScreenshot('home.png');
});

Replace the local URL and heading with values from your application. The explicit viewport and readiness assertion make the intended capture conditions clearer; your app must also be running or started by your Playwright configuration.

Establish and maintain the baseline

  1. Run the test in the intended baseline environment. On first use, Playwright creates the reference image after its documented stable-capture check.
  2. Open and inspect the generated reference. Confirm that it shows the intended page state, not a loading screen, error, or transient overlay.
  3. Commit the reviewed reference alongside the test so subsequent runs have a comparison target.
  4. When a later run reports a difference, inspect the actual image, reference, and diff. Decide whether the change is an intended design update or a regression.
  5. Update the reference only after deciding that the new appearance is correct. Treat the reference update as a code review change, not a way to silence a failing test.

Playwright documents its visual comparison workflow at Visual comparisons.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
Sale
Anker USB C Hub, 7in1 Multi-Port USB Adapter, 4K@60Hz USBC to HDMI Splitter
  • Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
  • Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
  • Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
  • Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
  • What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.

Run Playwright screenshot tests in CI

The provider-independent sequence is to install packages from the project lockfile, install the Playwright browsers and operating-system dependencies, then run the tests. The following GitHub Actions example follows that sequence; adapt the runner and application startup to your project. Playwright’s official CI guidance recommends one worker by default in CI to prioritize stability and reproducibility.

name: Playwright tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npm run build
      - run: npm run start &
      - run: npx playwright test --workers=1

Use the Node version and build/start commands your application requires; the versions and commands in this example are not universal requirements. The official Playwright CI documentation gives provider-specific setup details: Continuous Integration.

Rank #4
Sale
UGREEN USB to USB C Adapter Combo 4-Pack, 10Gbps USB C Converter Space Gray
  • Dual Converters, Infinite Potential:Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
  • Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
  • Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
  • Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
  • Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft

Keep the baseline environment consistent

Screenshot rendering can differ across operating systems and browser installations. Create, review, and compare reference images in a consistent environment. A container can help keep the environment consistent across operating systems. If local development uses a different environment from CI, avoid treating every resulting pixel difference as an application regression; either align the environments or review the discrepancy deliberately.

Save useful failure evidence

Make the test report and failure evidence available from the CI run when they help reviewers inspect a difference. Keep enough information to identify the test, the changed image, and its reference. Retain only what your team needs and follow your organization’s rules for artifacts that may contain page content.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Best Value
Anker USB C Hub, 5-in-1 USBC to HDMI Splitter with 4K Display
  • 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
  • Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
  • Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
  • HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
  • What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.

Scale execution carefully

Start with one worker on a shared CI runner. If runtime becomes a problem, add workers when runner capacity permits or shard tests across CI jobs. More parallelism can make runs faster, but it also requires a reliable way to collect and inspect results across jobs. Playwright discusses workers and sharding in its CI guidance.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Choose built-in snapshots or hosted visual review

Consideration Playwright built-in comparison Percy integration
Where snapshots go Playwright snapshot references are managed in the test workflow. The integration uploads snapshots to Percy.
Review workflow Review test output and image differences in your local or CI workflow. Use Percy’s hosted visual review workflow.
Operational setup Manage reference images and keep the rendering environment consistent. Configure the integration, an external account, and a project token.
Cost and data handling Depends on your existing infrastructure and policies. Check current plan terms, retention, access controls, and what page content is uploaded before adopting it; the integration documentation does not establish these terms.

Percy’s integration documents a token-based CLI workflow for Playwright snapshots: Percy Playwright integration. Choose it when a hosted review workflow fits your team; choose built-in references when keeping the comparison inside Playwright better suits your process.

Troubleshoot common CI visual-test failures

  • Many unrelated pixels differ: check that the baseline and CI use the same operating system, browser version, fonts, and rendering dependencies. Align the environments before refreshing references.
  • The screenshot captures a loading or incomplete page: wait for the specific content or state the test needs, and make sure the application is actually running before the test begins.
  • A new baseline appears unexpectedly: confirm that the reference images are available to the job and that the test is running in the expected project and environment. Inspect any newly generated reference before committing it.
  • Tests are inconsistent under parallel load: begin with one worker in CI. If increasing workers, check runner capacity and whether tests share mutable data or resources.
  • Sharded runs are hard to review: ensure each job’s output can be identified and collected or inspected together, rather than relying on one shard’s report as the whole run.
  • Percy does not accept a run: check the project-token configuration and integration command against the current Percy integration instructions; do not expose the token in logs or public artifacts.

Or skip the browser setup

If you need a rendered screenshot without maintaining a browser-install step in your own job, ScreenshotNeo offers a website screenshot API and MCP server. A single GET request captures a URL; for example, cURL can save a WebP response like this:

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

See the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. This produces captures, not Playwright baseline comparisons, so it does not replace the review-and-assertion workflow described above. Sign up free for 1,000 screenshots a month with no card.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Frequently Asked Questions

Do screenshot tests replace functional tests?

No. They detect visual changes; retain functional assertions for behavior such as navigation and form submission.

Can I run Playwright visual tests on a CI provider other than GitHub Actions?

Yes. The install-browsers-and-dependencies, then run-tests sequence is provider-independent; the official guide also documents CI setup.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.