Free tools Windows power users keep installed
One-click scans. No signup required.
Debug a headless-browser failure by preserving the evidence around the action that failed: the test error and call log, the page’s DOM state, browser console output, network requests, and a recorded trace. In Playwright, start with a focused reproduction in the Inspector when you need to interact with the test; use Trace Viewer when you need to inspect a past or CI run. A headed run can reveal what the page looks like, but it changes the conditions, so verify any fix again in the original headless setup.
What to inspect when a headless test fails
Headless means the browser runs without a visible browser window. It does not mean the page has no DOM, console, network activity, or render state to inspect. The practical challenge is collecting enough of that evidence to distinguish a faulty locator from a slow or broken page, a failed request, or an environment-specific problem.
Playwright’s documentation says browsers run headless by default. Its debugging tools let you either pause and examine an interactive run or review a trace after the run has finished. Choose based on the evidence you need rather than treating one mode as universally better.
| Need | Start with | Inspect |
|---|---|---|
| Step through one test | Playwright Inspector / debug mode | Current action, locator, actionability log, source line |
| See rendered behavior directly | Headed run, such as headless: false |
Visible page and browser developer tools |
| Understand a past or CI failure | Recorded trace and Trace Viewer | Timeline, DOM snapshots, action log, source, errors, console, network, screenshots |
| Understand framework control flow or launch behavior | Verbose framework logs | API or browser launch messages |
| Use Puppeteer | Puppeteer’s debugging guide | Its framework-specific browser and Node.js debugging workflow |
For a useful diagnosis, ask four questions: can the failure be reproduced locally; do you need to retain the actual CI conditions; do you need interactive control or post-run evidence; and is the suspected issue in page state, browser output, network activity, or framework startup?
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems#1 Best Overall
Start with the failing test and its original evidence
- Read the error before changing settings. Note the assertion, expected and received values, call log, and source line. A timeout or locator error is a symptom; the call log helps identify which action was being attempted.
- Narrow the reproduction. Run only the failing test, and keep its original browser mode and relevant configuration. A smaller reproduction makes the action sequence easier to follow without discarding the conditions that may trigger the failure.
- Locate the first unexpected action. Work from the earliest failed or stalled action, not just the final assertion. Later failures may be consequences of a click, navigation, or request that did not complete as expected.
- Preserve a trace for failures you cannot watch live. This is especially useful for CI: inspect evidence captured from the environment where the failure occurred instead of assuming a successful local run explains it.
Playwright’s Debugging Tests guide documents the Inspector, headed debugging, and verbose logs. Its Trace viewer guide describes the evidence available in a trace and its use for CI failures. These pages do not state a fixed publication date or framework version, so check the documentation that matches the Playwright version installed in your project.
Debug interactively with the Playwright Inspector
Use the Inspector when you can reproduce the failure and want to pause, step through the test, or test a locator against the current page. In a terminal, run the focused test in debug mode:
npx playwright test path/to/example.spec.ts --debugReplace the path with the test file in your project. Debug mode opens the browser visibly and launches the Inspector. The Inspector supports stepping through the test, live locator edits, locator picking, and actionability logs. These features help answer whether a target exists at the relevant moment and why an action could not proceed.
- Use the Inspector’s step controls to advance to the action that fails.
- Check the actionability log and the locator that the test is using.
- Use locator picking or a live locator edit to compare the intended target with the page’s current structure.
- Inspect the page state at that action, then change the test or application only when the evidence supports that change.
Debug mode sets the default timeout to zero. That is useful when you want to control the pace manually, but it means a stalled step may wait indefinitely until you act or stop the run. Do not mistake that behavior for proof that the application would eventually succeed under the ordinary test timeout.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Make a normal run visible
If you want to observe the browser without using the Inspector, set headless: false in the browser launch options. Playwright also documents slowMo as a way to make actions visible at a slower pace. For example:
import { chromium } from '@playwright/test';
const browser = await chromium.launch({
headless: false,
slowMo: 250,
});
const page = await browser.newPage();
await page.goto('https://example.com');
// Run the interaction you want to observe here.
await browser.close();This is an illustrative launch pattern; place it in the setup or script appropriate to your project rather than adding a second browser launch inside a test that already manages its browser. A visible run helps observe layout and interaction, but it changes execution conditions. Re-run the test headlessly after a diagnosis or fix.
Use Trace Viewer for CI and after-the-fact diagnosis
A trace preserves a time-ordered view of a run. Playwright Trace Viewer can show actions, DOM snapshots, action details, source locations, errors, test and browser console messages, network requests, and screenshots when screenshot recording was enabled. These are separate clues, not an automatic root-cause verdict.
- Configure the test run to record a trace, commonly on failure, using the trace settings supported by your installed Playwright version.
- Retain the trace artifact from the failing local or CI run.
- Open that artifact in Trace Viewer using the method documented for your version.
- Move to the failed action and compare its before/after state, action log, source location, console messages, and related network activity.
The exact configuration and opening command are version-sensitive; consult the official Trace viewer documentation for the installed version instead of copying an old configuration verbatim. For intermittent CI failures, preserve the trace from the actual failing job. A successful headed run on a developer machine does not establish what happened in CI.
Rank #3
Correlate, do not guess
- If a locator fails, inspect the DOM snapshot and action log at that point. Check whether the target exists, is unique, and is actionable in that state.
- If content is missing, inspect the requests associated with the action and their responses, then compare console messages for related errors.
- If the page looks visually wrong, compare snapshots or recorded screenshots around the action. A screenshot establishes visible state, not why it occurred.
- If the trace shows a timing difference, identify what event or state the test should wait for rather than automatically adding a longer fixed delay.
Turn on verbose logs when the sequence is unclear
For unclear Playwright API control flow, the debugging guide documents this command:
DEBUG=pw:api npx playwright testFor a browser launch failure, Playwright’s CI guidance identifies DEBUG=pw:browser as helpful. These are environment-variable examples for a shell; exact behavior can depend on the installed version and environment. Check current official documentation before relying on a debug namespace in a different version or platform.
Use logs to clarify what the framework attempted and when. They complement, rather than replace, a trace: logs may explain framework calls, while the trace can connect actions with DOM snapshots, console output, and network requests.
Common headless debugging problems
The locator or action fails
Inspect the action log and DOM snapshot at the failed step, then use the Inspector’s picker or live locator editing to see whether the selector matches the intended element. Check that the page has reached the state the action assumes. Prefer a locator tied to stable page semantics over one that depends on fragile layout details.
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
The page looks wrong
Compare snapshots or screenshots before and after the relevant action, and use a headed run if direct observation would help. A screenshot can show that the page differs; it cannot, by itself, identify whether the reason is application state, CSS, timing, or a missing resource.
Data or assets are missing
Inspect the relevant network requests and responses in the trace, along with console output. A missing image or data record could be downstream of a failed request, but confirm the connection in the captured evidence before changing waits or application code.
The browser fails to launch or the test stalls early
Separate a launch problem from a page-level failure. Inspect framework logs and the execution environment; for Playwright, the browser-focused debug namespace may provide launch detail. Check installed browser dependencies and the version-specific CI guidance. Avoid adopting launch flags from anecdotes without checking their current documentation and security implications.
It fails only in CI
Open the trace captured by the failing CI run and inspect that run’s own timeline, requests, console output, and snapshots. Local headed success is useful comparative evidence, not proof of the CI root cause. If no trace was retained, adjust the test configuration to record one for a future failure.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
When to use a screenshot API instead of a test debugger
A screenshot API is useful when the task is to capture a URL’s page state for a report, visual review, or downstream workflow. It is not a substitute for a Playwright trace when you need the failed test’s action history, source location, or the sequence of browser and network events. If you need a clean page image rather than an interactive test diagnosis, ScreenshotNeo is a website screenshot API and MCP server; it removes cookie/consent banners, newsletter popups, and chat widgets before capture, and only clean shots are billed.
Or skip the browser setup
For a one-off page capture, make one GET request. This cURL example writes the returned image to a file:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for the request options and response details. Replace YOUR_API_KEY with your key and change the target URL as needed.
ScreenshotNeo accepts cookie banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up free for ScreenshotNeo.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Reliability, performance, and cost: keep the diagnosis honest
- Preserve the failing conditions. A headed run is an observation aid, not a replacement for repeating the test in its original headless environment.
- Prefer captured evidence for intermittent failures. A trace from the failing CI run can retain the action and page evidence that may disappear when rerunning locally.
- Do not infer cause from a single artifact. A screenshot, console message, or failed request is a clue; correlate it with the action and page state.
- Be cautious with added waits. A longer timeout may mask a race without identifying what state the test should wait for.
- Keep verbose logs targeted. Enable them when launch or API flow is unclear, then return to the ordinary configuration once the diagnosis is complete.
The cited Playwright and Puppeteer documentation establishes debugging capabilities and workflows, not comparative speed, failure rates, or performance benchmarks. No universal timing or cost figure follows from these tools alone.
Frequently Asked Questions
Does headless mode mean the browser cannot be debugged?
No. Playwright supports interactive debugging and post-run trace inspection while its browser is otherwise headless by default.
Can a screenshot prove why a test failed?
No. It shows visual state; use action details, DOM snapshots, console output, and network evidence to investigate the cause.
Should I fix a failure based only on a successful headed run?
No. Re-run under the original headless conditions to verify the diagnosis and fix.
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.
