How to Use LambdaTest Screenshot with Playwright for Visual Testing
Use Playwright Test for screenshot baselines, run tests in LambdaTest browsers, and understand where SmartUI fits in a hosted visual review workflow.
Short answer: Playwright Test captures and compares visual baselines with await expect(page).toHaveScreenshot(). LambdaTest can run Playwright tests in cloud browser and operating system environments. For hosted visual review, LambdaTest SmartUI documents an API for uploading locally captured images and retrieving build and screenshot status. These are related but separate parts of a workflow: the available documentation does not establish a current one-step Playwright-to-SmartUI integration.
This guide shows the native Playwright workflow first, then how to run a test on LambdaTest and how a local screenshot upload can fit into SmartUI. Check LambdaTest’s current browser catalog and API documentation before using its configuration examples or endpoints: some cited materials are older. [LambdaTest Playwright guide] [Playwright visual comparisons] [LambdaTest SmartUI API reference]
1. Understand the parts of the workflow
Visual testing has two distinct jobs:
- Capture and comparison: Playwright Test takes a screenshot and compares it with a reference image stored with the test. The first run creates the baseline; later runs report differences.
- Browser execution: LambdaTest runs Playwright in configured cloud browser and platform combinations. That broadens the environments where the test can run, but does not by itself mean the screenshot is uploaded to SmartUI.
- Hosted visual review: SmartUI’s API describes uploading an image captured locally, then retrieving build and screenshot status for review. Treat this as a separate integration step and verify the current API contract.
Keep those steps explicit in your CI pipeline: run a browser test, capture or assert its screenshot, and, if required, upload the resulting image to a hosted comparison workflow.
2. Create a Playwright visual test
The example uses Playwright Test, which supplies the expect screenshot assertion. It assumes your project already has Playwright Test configured.
// tests/home.spec.ts
import { test, expect } from '@playwright/test';
test('home page matches its visual baseline', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('home.png');
});Run the test with:
npx playwright test tests/home.spec.tsOn the first run, Playwright creates the expected screenshot. Review and commit that image as the baseline. Subsequent runs compare the current capture with the committed reference and fail when the difference exceeds the configured threshold. Screenshot assertions wait for consecutive screenshots to stabilize before comparing them. [Playwright: Visual comparisons]
Make the page deterministic before capture
A screenshot test is only useful when it captures a stable state. Wait for the content that matters, use fixed test data, and avoid capturing during animations or while asynchronous content is changing. If the application supports a test mode, use it to hold timestamps, random values, and personalized content steady.
import { test, expect } from '@playwright/test';
test('product page has stable visual output', async ({ page }) => {
await page.goto('https://example.com/products/widget');
await page.getByRole('heading', { name: 'Widget' }).waitFor();
await expect(page).toHaveScreenshot('widget.png', {
animations: 'disabled',
});
});Use a locator assertion when a particular component is the subject of the check; use the page assertion when the page composition itself matters. The key operational rule is to keep the capture state and rendering environment consistent between baseline creation and comparison.
3. Tune screenshot comparisons and update baselines deliberately
Playwright documents screenshot comparison options including maxDiffPixels and stylePath. Use a difference allowance only when small rendering variation is acceptable for your test. A permissive threshold can conceal a real regression. A stylesheet can hide or normalize volatile elements when that is a deliberate part of the test.
await expect(page).toHaveScreenshot('dashboard.png', {
maxDiffPixels: 120,
stylePath: './tests/visual-normalize.css',
});Example normalization stylesheet:
/* tests/visual-normalize.css */
[data-testid="live-clock"],
[data-testid="random-avatar"] {
visibility: hidden !important;
}Only normalize content that is irrelevant to the visual contract being checked. Hiding a region can also hide a genuine layout or styling regression in that region.
When an intentional design change updates the expected output, use Playwright’s snapshot update command after reviewing the diff:
npx playwright test tests/home.spec.ts --update-snapshotsDo not update snapshots just to make a failing run green. Inspect the rendered result, confirm the change is intended, and include the new baseline in the same review as the code change. Playwright describes snapshot update behavior and options in its visual comparison documentation. [Playwright: Visual comparisons]
4. Run Playwright tests on LambdaTest
LambdaTest’s Playwright guide describes passing credentials through environment variables, configuring browser and platform projects, running the Playwright command, and reviewing results in the Automation dashboard. Use the currently supported platform identifiers from LambdaTest before copying a sample configuration: example browser versions and availability can change. [LambdaTest Playwright sample guide]
Set credentials in your shell or CI secret store. Do not commit the actual values:
export LT_USERNAME="your-lambdatest-username"
export LT_ACCESS_KEY="your-lambdatest-access-key"
A configuration should read the credentials from the environment and define the LambdaTest connection and target capabilities according to the current LambdaTest runner guide. The exact connection format and capability schema are service-specific; copy those fields from the maintained LambdaTest sample and select a browser/platform combination that is currently available.
Then run the configured Playwright command from the sample project, typically through its package script or Playwright Test CLI. Check the LambdaTest Automation dashboard for the execution result. A cloud run changes the browser execution environment; it does not automatically change Playwright’s baseline storage or prove that a SmartUI comparison was created.
Control the baseline environment
Screenshot output can vary with operating system, browser version, browser settings, hardware, power source, and headless mode. Generate and compare baselines in a consistent environment. If you intentionally compare multiple browser and OS combinations, maintain baselines appropriate to those environments instead of assuming one image is interchangeable across all of them. [Playwright: Visual comparisons]
5. Where LambdaTest SmartUI fits
LambdaTest’s SmartUI API reference documents uploading locally captured images for visual regression and retrieving build status and screenshots. Its overview describes baseline and comparison images and visual issue review. This supports a workflow where Playwright captures an image and a separate integration uploads it to SmartUI. The reviewed sources do not establish a maintained turnkey adapter for every language or test runner, so plan for an explicit upload step and verify current endpoint details, authentication, payload format, and limits in the live documentation. [SmartUI API reference] [Smart Visual UI testing overview]
Do not confuse SmartUI with LambdaTest’s older Screenshot API. That API describes starting screenshot tests and querying OS, browser, device, resolution, and results, but the available page is old and does not establish a current Playwright integration. Confirm its present availability and workflow before choosing it. [LambdaTest Screenshot API]
6. Choose the right comparison workflow
| Question | Playwright snapshots | LambdaTest SmartUI flow |
|---|---|---|
| Where does capture happen? | In the Playwright test environment, which may be local or cloud-hosted. | The documented workflow accepts images captured locally and uploaded through its API. |
| How are comparisons initiated? | toHaveScreenshot() compares with Playwright’s reference snapshot. |
An uploaded image participates in the SmartUI build and visual review workflow; verify current API steps. |
| Where are baselines and review managed? | Reference snapshots live with the test project and are updated through Playwright’s snapshot workflow. | SmartUI provides hosted build and screenshot status and visual issue review. |
| What does LambdaTest cloud execution add? | It can execute the test in configured cloud browser and OS environments. | Cloud execution and SmartUI upload are separate capabilities in the cited materials. |
| What needs maintenance? | Stable rendering setup, reviewed baseline changes, and environment consistency. | Those capture concerns plus API authentication, upload handling, and current endpoint compatibility. |
Pick repository-based snapshots when code review and versioned image baselines fit your team. Add SmartUI when hosted visual review and its build workflow fit your process. Use LambdaTest cloud execution when browser and platform coverage is the requirement. These choices can coexist, but the sources reviewed do not show that one automatically configures the others.
7. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| First screenshot assertion fails because no snapshot exists | The reference image has not been created yet. | Run the test to generate the baseline, inspect it, then commit it if it represents the expected page. |
| Snapshot changes on every run | Unstable page state or differences in browser, OS, settings, fonts, hardware, or headless mode. | Wait for meaningful content, disable animations, stabilize dynamic data, and keep baseline and comparison environments consistent. |
| Many unrelated pixels differ | The page is still loading, a popup or dynamic region changed, or a different rendering environment was used. | Wait for the target state, inspect the image diff, and normalize only irrelevant volatile content. |
| Snapshot update hides a regression | The expected image was replaced without reviewing the design change. | Restore the prior baseline or re-run the comparison, inspect the diff, and update only after approving the intended visual change. |
| LambdaTest authentication fails | Credentials are missing, incorrect, or unavailable to the CI job. | Check the secret names and job environment, rotate invalid credentials in LambdaTest, and keep secrets out of source control. |
| LambdaTest cannot start the requested browser/platform | The configured identifier may be outdated or unavailable. | Choose a currently supported value from LambdaTest’s browser/platform catalog and update the project configuration. |
| Test passes in one environment but differs in another | Different browser or OS rendering produced a legitimate pixel difference. | Keep environment-specific baselines where cross-platform appearance is part of the check, or compare in one controlled environment. |
| SmartUI has no expected image or build result | The separate image upload or status retrieval step may be missing, failing, or using an outdated API contract. | Inspect the upload response and authentication, then verify the current SmartUI endpoint and required build flow in its API documentation. |
8. Performance, reliability, and cost
Screenshot assertions add rendering and image comparison work to a test. Keep each assertion scoped to the visual contract it protects, and avoid repeatedly capturing a large page when a targeted component check answers the question. On cloud runs, total duration also depends on browser startup, navigation, network activity, and the configured LambdaTest environment; the sources reviewed provide no independent runtime benchmark.
For reliability, make the page state deterministic, pin or consistently select the rendering environment where possible, and review baseline diffs as part of code review. Cloud execution can expose differences across supported environments, but it also means platform availability and current configuration values matter. SmartUI adds an external upload and hosted review dependency; handle upload failures explicitly and verify current service limits before relying on them. A historical SmartUI API page listed a 100 MB screenshot upload maximum, but because that documentation is old, treat the figure as historical and confirm the current limit rather than designing around it. [SmartUI API reference]
The research materials do not establish current LambdaTest plan prices, included visual testing quotas, or SmartUI billing terms. Check current product and account pricing before estimating CI costs. Keep the number of browser/platform combinations and screenshots per change aligned with the regressions you need to catch.
Or skip the browser setup
If you need clean screenshots of pages for review or downstream tooling rather than Playwright assertions, ScreenshotNeo is a website screenshot API and MCP server for developers. It takes one GET request with a URL and returns PNG, JPEG, WebP, or PDF. Its cookie and consent flow accepts banners as a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Only clean shots are billed: bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with the result identified in X-Page-Verdict and X-Billed headers. Its MCP server gives AI agents tools for screenshots, page info, and PDF capture.
See the ScreenshotNeo API documentation for parameters and setup. This is a capture API, not a replacement for Playwright’s baseline assertion workflow.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. The MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.
FAQ
Does Playwright need LambdaTest to compare screenshots?
No. Playwright Test provides screenshot assertions and reference snapshots on its own. LambdaTest adds cloud browser execution when you need it.
Does a LambdaTest Playwright run automatically send screenshots to SmartUI?
The reviewed sources document cloud execution and SmartUI image upload separately. They do not establish an automatic one-step connection, so verify any adapter you plan to use.
Should every browser use the same baseline?
Not necessarily. Browser and operating system rendering can differ. Keep the environment consistent for a given baseline, and use environment-specific references when cross-platform output is part of the test.
Can I use LambdaTest’s older Screenshot API for this?
The surfaced API documentation is old and does not establish a current Playwright integration. Check current availability and documentation before adopting it.
