A blank Playwright image usually means one of five things: the page had not rendered its content, transparency made the background invisible, the capture covered the wrong area, the application was not ready, or the browser environment differed from the one that produced a good image. Diagnose the saved file and the live page in that order. A missing automatic artifact is a separate configuration problem: Playwright Test does not capture screenshots unless you enable it.
Start with the file and the page
Do not assume a valid PNG is proof that the page rendered. Open the exact output file and inspect its dimensions, color uniformity, and alpha channel. A file that is one solid color may be a real viewport capture of an unrendered page; an image with transparent pixels can look empty in a viewer that uses a white canvas.
Immediately before the screenshot call, inspect the browser state as well:
- Read
page.url()and confirm that navigation reached the intended route. - Check visible text or a meaningful locator that the application should render.
- Confirm that the selector or element you intend to capture exists and has the expected bounds.
- Log application errors or failed data requests if your app exposes them.
These checks separate a capture problem from an application that never produced content. Playwright’s API documents how a capture works, but it cannot know what “ready” means for your application.
#1 Best Overall
Fix transparent or apparently white output
Look for omitBackground: true in the screenshot call, a shared helper, or test configuration. Playwright documents that this option hides the default white background and permits transparency. Its documented default is false, and it does not apply to JPEG output.
When transparency is accidental
Remove the option or set it explicitly:
await page.screenshot({ path: 'page.png', omitBackground: false });Use PNG or WebP when you need an alpha channel. JPEG cannot preserve transparency, so changing only the file extension will not fix a transparent-background workflow.
When transparency is intentional
Inspect the alpha channel or place the image over a dark and light contrasting background. A transparent page can look blank against a viewer canvas even though the foreground pixels are present. Check the actual pixel data before changing your capture code.
Check whether you captured the right area
page.screenshot() captures the current viewport by default. Content below the fold is not included in that image. For the complete scrollable page, request a full-page capture:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsRank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
await page.screenshot({ path: 'page-full.png', fullPage: true });Element and locator captures
If you call a locator or element screenshot, verify that the selector identifies the content you expect, not an empty wrapper, hidden template, or zero-sized node. Confirm that the element is visible and that its bounding box is non-zero. A page screenshot can be correct while an element screenshot appears blank because the target is wrong.
Viewport assumptions
Responsive layouts can hide or replace content at a narrow width. Set the viewport deliberately when reproducing a problem and record it with the image. A mobile breakpoint, an off-canvas menu, or a component that renders only after scrolling can all make a normal viewport capture look empty without indicating a Playwright failure.
Wait for the application’s ready state
Navigation completion is not the same as application readiness. Single-page apps often fetch data, hydrate components, load fonts, or remove a loading shell after goto() resolves. Wait for a signal that has meaning in your app, such as the main content becoming visible:
import { test, expect } from '@playwright/test';
test('capture rendered page', async ({ page }) => {
await page.goto('https://example.com');
await expect(page.getByRole('main')).toBeVisible();
await page.screenshot({ path: 'page.png' });
});Replace getByRole('main') with a locator that proves the data or component you need is ready. Other useful signals include a “results loaded” element, a completed application request that your test can observe, or the disappearance of a loading indicator.
Rank #3
Why a fixed sleep is a weak fix
waitForTimeout(5000) may hide a race on one machine and still fail on a slower CI runner. It also wastes time when the page is already ready. Prefer a state-based wait, and give the locator an explicit timeout appropriate for your application.
Do not confuse screenshot assertions with ordinary captures
Playwright Test’s screenshot assertion, expect(page).toHaveScreenshot(), waits until two consecutive screenshots produce the same result before comparing the last one with the expectation. That stability behavior belongs to the assertion. It is not an automatic readiness wait for every page.screenshot() call. An ordinary capture still needs your application-specific readiness check.
Compare local, headless and CI environments
If the image is blank only in CI or headless mode, compare the environments rather than adding random delays. Rendering can vary with the host operating system, browser version, Playwright version, browser settings, hardware, power source (battery versus adapter), and headless mode. Playwright recommends running visual tests in the same environment used to generate their baselines.
Make the comparison reproducible
- Use the same Playwright and browser versions; verify the installed browser revision in CI.
- Use the same operating-system image and viewport dimensions.
- Keep device scale factor, color scheme, reduced-motion preference, locale, timezone, and permissions consistent.
- Run headed and headless captures separately when diagnosing a difference.
- Ensure fonts and other browser assets are installed in the CI image.
- Check whether the machine is under resource pressure or whether a page request is blocked by the CI network.
Do not treat a screenshot that differs across environments as proof that the page is empty. First compare the page URL, visible text, console errors, and network outcome in both runs.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Check automatic Playwright Test screenshot settings
When the expected file is a test artifact rather than one created by your own page.screenshot() call, inspect the use.screenshot setting in your Playwright Test configuration. Automatic screenshots are off by default. Supported modes are:
| Mode | When Playwright captures | Use it for |
|---|---|---|
off |
Never automatically | Explicit captures only |
on |
Every test | Continuous visual or diagnostic artifacts |
only-on-failure |
Failed tests | Keeping successful runs small |
on-first-failure |
First failure in a retry sequence | Retry-aware diagnostics |
A disabled automatic capture produces a missing file, not a file whose pixels are blank. Check the artifact configuration before debugging image contents.
A complete diagnostic procedure
- Open the actual file. Record format, dimensions, alpha presence, and whether every pixel is the same color.
- Log page state immediately before capture. Print the URL, visible text, and the expected locator’s visibility and bounds.
- Remove accidental transparency. Set
omitBackground: falsetemporarily and use PNG. - Capture the viewport and full page separately. This reveals whether the content is simply below the fold.
- Wait for an app-specific locator. Replace arbitrary sleeps with a meaningful ready signal.
- Capture a known-simple page. If an example page works, focus on your app’s rendering, data, or selectors.
- Compare environments. Match browser, Playwright, OS, viewport, headless mode, fonts, and resources with the known-good run.
- Check automatic-capture configuration. Confirm that
use.screenshotis notoffwhen you expect artifacts.
Common symptoms and targeted fixes
| Symptom | Likely explanation | Action |
|---|---|---|
| Image is transparent or appears empty on white | omitBackground: true |
Inspect alpha; disable the option or view over a contrasting background. |
| Header is visible but body is missing | Data or hydration had not completed | Wait for a rendered-content locator or application data state. |
| Expected section is absent | Viewport capture excludes below-fold content | Use fullPage: true or capture the specific visible element. |
| Only an element screenshot is blank | Wrong, hidden, or zero-sized target | Verify selector, visibility, and bounding box. |
| Local image works; CI image is blank | Environment or resource difference | Match versions, OS, fonts, viewport, headless mode, and network conditions. |
| No image file is produced | Automatic screenshots are disabled | Set use.screenshot to on, only-on-failure, or on-first-failure, or call the API explicitly. |
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. It accepts a URL in one GET request and returns PNG, JPEG, WebP, or PDF. Before capture it accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.
Use the API documentation at https://screenshotneo.com/docs/ for authentication and options. The same endpoint supports full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets or any viewport, retina scale, PDF paper size/margins/landscape/page ranges, HTML/CSS input, custom JavaScript and CSS, pre-capture clicks, hidden selectors, waits for a selector/delay/network idle, blocking ads/trackers/requests/resource types, custom headers/cookies/user agents/Authorization, timezone and geolocation, transparent backgrounds, image resizing, configurable-TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, an OpenAPI specification, and compatibility with parameter names used by other screenshot APIs.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import 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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo has 1,000 shots per month free without a card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free. Every feature is included on every plan, and an MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Create a free ScreenshotNeo account to get the 1,000 monthly shots without entering a card.
FAQ
Does a blank screenshot prove Playwright failed?
No. A valid capture can show an unrendered viewport, a transparent background, or the wrong target. Inspect page state and image properties before blaming the browser.
Should I always use fullPage?
No. Use the default viewport for viewport behavior and fullPage: true when content outside the viewport is part of the required artifact.
Why does a visual assertion pass after waiting while my manual screenshot is blank?
The assertion waits for two stable consecutive screenshots. A manual page.screenshot() does not receive that assertion-specific wait, so add your own readiness condition.
Frequently Asked Questions
Can transparency affect JPEG screenshots?
No. Playwright’s documented transparency option applies to formats that support alpha; JPEG does not preserve transparency.
What should I record when reporting a blank screenshot bug?
Provide the image file, capture options, URL, locator or viewport, visible text before capture, browser and Playwright versions, operating system, and whether the run was headed or headless.
Quick Recap
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.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →
