October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsPC HealthRecommendedCrashes, freezes, slowdowns? Check your PC nowSpot repairable issues before they interrupt work.Check PCOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
World desk7 min

How to Run Playwright Screenshot Tests in GitLab CI

A practical GitLab CI setup for Playwright screenshot assertions, including compatible container versions, reproducible baselines, artifacts, sharding, and failure fixes.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Run Playwright Test in a GitLab CI job, use a Playwright container whose version matches your project, and start with one worker. Commit screenshot baselines, keep CI’s browser environment consistent with the one that generated them, and upload the HTML report and test output as artifacts so failures can be investigated.

What a Playwright screenshot test does

Playwright Test’s toHaveScreenshot() assertion captures a page or element and compares it with a reference image. On its first run, Playwright creates the reference; later runs compare against it and fail when the rendered result differs beyond the configured comparison thresholds. These are visual regression tests: they can catch unintended changes in layout or appearance, but they do not by themselves establish whether a page behaves correctly or whether a visual difference is a bug.

As an Amazon Associate I earn from qualifying purchases.

A minimal test might look like this:

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

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

Ensure the application is running and the page has reached a stable state before capturing. For a locally running app, configure Playwright’s webServer option or start the app in the CI job before running the tests.

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

Configure the GitLab CI job

For an npm project, this is a baseline .gitlab-ci.yml job. The Playwright GitLab example reviewed for this guide uses mcr.microsoft.com/playwright:v1.63.0-noble; treat that as the version tag shown in that documentation, not a permanent recommendation. Select a currently available image tag that matches the Playwright package version in your lockfile.

#1 Best Overall
Arducam 8MP USB Camera Module with HDR, Autofocus Lightburn Camera, USB 2.0 Webcam with Multiple preset AI Resolutions for Raspberry Pi, Windows, Linux, Android, Mac OS
  • Plug-and-Play USB Camera Module: Experience ultimate convenience with our plug-and-play USB camera module. This 8MP camera is instantly recognized by Windows, Linux, Android, and macOS without any extra drivers. Just connect the USB and immediately start capturing crisp images, making it a perfect mini USB camera for rapid deployment in any project
  • AI Resolution for Advanced Applications: Leverage multiple preset AI image resolutions to train and deploy your models seamlessly. This USB webcam and 3D printer camera eliminates the need for manual image cropping, delivering ready-to-process data straight from the sensor. It’s an ideal vision solution for developers and makers
  • Autofocus & High-Definition Clarity: Equipped with a premium autofocus lens, this 4K mini camera automatically adjusts to maintain sharpness at various distances. Whether you’re using it as a lightburn camera for laser engraver or for detailed inspection, it delivers consistently clear and professional USB camera 4K quality video
  • Robust & Reliable USB Security Camera: Built for durability and performance, this USB security camera offers steadfast monitoring with high-resolution imaging. Its versatile mounting and plug-and-play operation make it suitable for both home security setups and professional surveillance systems
  • Upgraded Option with HDR: The enhanced model includes High Dynamic Range (HDR), an autofocus lens, and a rugged metal case. This upgraded USB camera module is especially suited for demanding applications like laser engraving with LightBurn or as a high-end 3D printer camera
stages:
  - test

playwright-screenshots:
  stage: test
  image: mcr.microsoft.com/playwright:v1.63.0-noble
  variables:
    CI: "true"
    BASE_URL: "http://127.0.0.1:3000"
  script:
    - npm ci
    - npm run start:test &
    - npx playwright test
  artifacts:
    when: always
    paths:
      - playwright-report/
      - test-results/
    expire_in: 1 week

The application-start command and BASE_URL are examples: replace them with the command and address your project needs. If Playwright’s webServer configuration starts the application, omit the background start command. npm ci is appropriate for a project with an npm lockfile; use the equivalent lockfile-respecting install command for another package manager.

Align the image, package, and browser

The image and installed Playwright package need compatible browser versions. Pin the image tag rather than using a floating tag, and update the image and package together. Playwright’s prebuilt image includes browsers and system dependencies, but if your selected environment does not have the needed browser binaries and operating-system dependencies, the documented installation step is npx playwright install --with-deps after installing the project. Do not add that step blindly to a prebuilt-image job; first check how that image and package are configured.

Configure reports and output paths

GitLab can upload only files that exist at the configured artifact paths. If you use the paths in the example, configure Playwright to write the HTML report and test output there:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [['html', { outputFolder: 'playwright-report', open: 'never' }]],
  outputDir: 'test-results',
  workers: process.env.CI ? 1 : undefined,
  use: {
    trace: 'on-first-retry',
  },
});

GitLab artifact paths are relative to $CI_PROJECT_DIR. The when: always setting keeps reports and test output available after ordinary test failures. GitLab does not upload artifacts if the job times out, so set a realistic job timeout for your suite and runner.

Rank #2
Dell Pro 16 Plus PB16255 Laptop, 16" FHD+, AMD Ryzen AI 7 PRO 350, 32GB/2TB
  • ENGINEERED FOR AI & MOBILITY - Meet the Dell Pro 16 Plus, the AI-enhanced evolution of the Latitude 5550. Engineered for on-the-go productivity, it features a slim and lightweight design, delivers up to 11.9 hours of battery life, and supports ExpressCharge capability to keep you efficient. Boasting a durable aluminum chassis and having passed MIL-STD 810H tests, it offers robust reliability for professionals on the move, from the office to demanding field environments
  • POWERFUL PERFORMANCE – The Dell Pro 16 Plus delivers power-efficient performance for demanding workloads with an AI PC powered by the AMD Ryzen AI 7 PRO 350 processor (up to 5.0GHz) and integrated Radeon 860M Graphics. Equipped with 32GB LPDDR5x RAM and 2TB M.2 NVMe PCIE SSD, enabling smooth multitasking and fast loading across a wide range of applications
  • COPILOT+ PC AI POWERHOUSE - The dedicated NPU delivers 50 TOPS for local AI processing without relying on the cloud. It enables Recall (effortless retrieval of past actions and content), Cocreate (AI image tools), Windows Studio Effects (auto-framing/background blur for video calls), and Live Captions (real-time translation). It redefines productivity and creativity with seamless, offline AI acceleration
  • IMMERSIVE DISPLAY - Features a 16-inch WUXGA (1920x1200) display with narrow borders, 300 nits brightness, and anti-glare coating to maximize screen real estate and reduce eye strain during extended use. Expand your workspace by connecting up to 3 external monitors via HDMI or Thunderbolt 4, with a max resolution of up to 4K@60Hz without docking station
  • ADVANCED CONNECTIVITY -With Thunderbolt 4, USB-A, and HDMI 2.1, MicroSD card reader, Global Headset Jack and RJ45 Ethernet port, you can easily connect external displays, storage devices, and essential peripherals. Stay fast and reliable on the go with Wi-Fi 7 and Bluetooth 5.4, perfect for video calls, cloud work, and wireless devices without lag. The 1080p IR camera with temporal noise reduction ensures crisp video calls in any lighting and secure facial recognition login. Plus, the backlit keyboard enables precise typing in low-light environments

Make screenshots reproducible

Visual comparisons can change when the rendering environment changes. Playwright identifies host operating system, browser version, browser settings, hardware, power source, and headless mode as factors that can affect screenshots. Generate baselines and run CI with the same environment wherever possible; Playwright’s guidance is: “For consistent screenshots, run tests in the same environment where the baseline screenshots were generated.”

Keep volatile page content from driving diffs

  • Use stable test data and avoid capturing while asynchronous page updates are still in progress.
  • For timestamps, rotating banners, or other intentionally changing areas, stabilize the data in the application where possible.
  • For elements that cannot be stabilized through test data, use Playwright’s screenshot stylePath option to hide or normalize them for the capture.
  • Use the same browser project, viewport, device scale factor, color scheme, and other screenshot-relevant settings for baseline generation and CI.

Do not hide a region merely because it produces a failure: first decide whether the change is genuinely irrelevant to the visual contract being tested.

Manage screenshot baselines as code

Playwright stores reference screenshots in snapshot directories associated with the tests. Commit those files with the code that defines the expected appearance, and review image changes in merge requests. When an intentional design change updates the expected result, regenerate references locally in the same environment used by CI:

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.
npx playwright test --update-snapshots

Inspect the new images and the diff before committing them. Do not run snapshot updates automatically after a CI failure: doing so can turn an unintended regression into the new expected result.

Rank #3
Software Engineer Definition Sticker - Funny Programmer Vinyl Decal - 5 in
  • Size: 5" x 4.6"
  • Al weather vinyl sticker
  • Phone sticker, laptop sticker, car sticker, water bottle sticker, and so many more applications!
  • Peel & stick, simple application, reusable
  • Made in the USA

Scale the suite only when needed

Begin with one worker

Playwright recommends one worker in CI as a stability and reproducibility default. A single worker avoids introducing concurrency-related instability while you establish that the job, application startup, and visual baselines work reliably.

Shard across GitLab jobs for throughput

If the suite is too slow for one job and runners are available, GitLab can run multiple shards in parallel. For example:

playwright-screenshots:
  stage: test
  image: mcr.microsoft.com/playwright:v1.63.0-noble
  parallel: 4
  script:
    - npm ci
    - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL

Use this as an adaptation of GitLab’s documented shard pattern, not as a guarantee that four jobs will finish four times faster. Sharding needs enough runner capacity, and the project must be configured so each shard runs the intended portion of the suite. Make sure parallel runs do not overwrite shared output or otherwise interfere with one another.

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

Cache dependencies thoughtfully

Playwright does not recommend caching browser binaries by default: restoring them can take about as long as downloading them, and Linux system dependencies cannot be cached. If you choose to cache browser binaries anyway, tie the cache key to the Playwright version so a package upgrade does not restore an incompatible browser set.

Rank #4
Web Developer Coding Skeleton In Front of Laptop Halloween T-Shirt
  • For programmers and web developers who have a sense of gothic macabre about them. Perfect for coding meetups, gaming sessions, or casual outings. Do you live for code? Are you a programmer, IT professional or developer who is constantly coding?
  • Web Developer Coding Skeleton In Front of Laptop Halloween. Perfect for dark mode developers, programmers, software engineers, anyone in tech with a dark side who lives at their computer. Great for Halloween or the rest of the year.
  • Lightweight, Classic fit, Double-needle sleeve and bottom hem

A package-manager cache may be more useful. In GitLab, use a lockfile-based cache key for dependencies when measurements on your runners show that it improves job time. Cache behavior depends on the runner and project; do not assume a cache will always make the job faster.

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

Troubleshoot common failures

Browser launch fails

Check that the Playwright package and container image versions are compatible and that the selected environment contains the required browser binaries and system dependencies. If you need to inspect browser startup, run:

DEBUG=pw:browser npx playwright test

If the job uses an environment without the required browsers or operating-system dependencies, follow Playwright’s documented browser installation route with npx playwright install --with-deps.

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

The test cannot reach the application

Verify that the app is started before the test command, that the configured URL is reachable from inside the job container, and that the test waits for the application to be ready. A host-side localhost address may not identify the application from a separate container or service; use the address appropriate to the job’s network setup.

Best Value
I Turn Coffee Into Code Funny Programmer Sticker - Software Engineer Vinyl Decal for Laptops, Monitors, and Water Bottles - Coding & Tech Humor - Durable, Waterproof Die-Cut Tech Sticker
  • The Ultimate Developer Humor: Celebrate the fuel behind your best lines of code with this "I Turn Coffee Into Code" sticker. It is a must-have accessory for software engineers, web developers, data scientists, and computer science students.
  • Premium Waterproof & Heat-Resistant: Crafted from high-quality, durable vinyl that is 100% waterproof and heat-resistant. Perfect for sticking on high-performance laptops, coffee tumblers, or office water bottles without worrying about peeling or fading.
  • Sleek Professional Design: Featuring a bold black and white aesthetic with a clean coffee cup icon, this die-cut decal looks professional and stylish on MacBooks, PC cases, and office monitors.
  • Easy Application, Zero Residue: Equipped with a strong adhesive that stays put through daily wear. If you upgrade your hardware, it peels off cleanly without leaving any sticky mess or residue behind on your expensive electronics.
  • Perfect Tech Gift: Looking for a great gift for a programmer, IT professional, or coding student? This decal makes an excellent stocking stuffer, "new job" gift, or secret santa present for your tech-savvy coworkers.

Screenshots differ only in CI

Compare the baseline-generation and CI environments: operating system, Playwright/browser version, headless mode, viewport, device scale factor, and relevant browser settings. Check for dynamic content, missing fonts, and captures taken before the page settles. Regenerate a baseline only after confirming that the new appearance is intended.

Artifacts are missing

Confirm that the report and output directories match the configured Playwright paths and are relative to $CI_PROJECT_DIR. Check whether the job timed out: GitLab does not upload artifacts for timed-out jobs. For a normal test failure, when: always requests artifact upload.

Sharded runs collide or remain slow

Verify that the shard expression uses GitLab’s $CI_NODE_INDEX/$CI_NODE_TOTAL variables and that the test configuration supports sharding. Ensure separate jobs do not write to a shared location that causes output collisions. If jobs spend time queued for runners, adding shards may increase elapsed time rather than reduce it.

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

Or skip the browser setup

A screenshot API can return an image of a URL without setting up a browser in your GitLab job. It is not a replacement for Playwright Test’s toHaveScreenshot() assertion: this one-call example captures a page, but does not create or compare Playwright baselines.

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 and consent banners, newsletter popups, and chat widgets before the 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 per month without a card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month with no card.

Frequently Asked Questions

Can I use a GitLab shell runner instead of a Docker image?

Yes, if the runner environment has the compatible Playwright browsers and operating-system dependencies installed. The container route is a convenient way to keep the CI environment pinned.

Should visual tests run on every merge request?

That depends on suite duration and runner capacity. A practical starting point is to run them in the relevant merge-request pipeline, then use sharding if execution time becomes a bottleneck.

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

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.

Leave a Reply

Your email address will not be published. Required fields are marked *

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

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
Outdated Drivers Are Slowing You DownFree scan - exact matches
Windows Errors? Fix Them Before They SpreadFree repair scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.