How to debug Playwright and Puppeteer tests: first isolate the failing test, then gather evidence from the part of the stack that could be failing. For Playwright, use --debug or UI Mode to inspect actions and locators, and collect traces for CI failures. For Puppeteer, make the browser visible, forward page logs, and choose Node’s inspector, browser DevTools, or process logs based on where the suspect code runs. These workflows and their trace formats are different.
Start by narrowing the failure
Before changing timeouts or adding waits, reduce the run so you can reproduce the failure with less noise. A failure can come from the test runner, test code, page JavaScript, browser behavior, or differences between your local and CI environments.
- Run only the failing test or file. In Playwright, pass a test file, a file-and-line selector, or a project name. For example:
npx playwright test example.spec.ts:10 --project=chromium. To compare browser-specific behavior, repeat with the relevant project rather than changing several variables at once. See the Playwright command-line reference. - Keep the original failure conditions where possible. Note the browser project, test configuration, environment variables, and whether the failure is consistent. A narrowed run helps locate a fault but does not establish its cause.
- Make the sequence observable. Use Playwright Inspector or UI Mode, or launch Puppeteer in headed mode. Visibility helps identify unexpected page state; it does not by itself prove why the test failed.
Debug Playwright tests interactively
Use the Inspector to step through a test
Run the suite, a file, or a specific test line with --debug:
npx playwright test --debug
npx playwright test example.spec.ts --debug
npx playwright test example.spec.ts:10 --debugThis opens the Playwright Inspector and a headed browser. Step through actions, inspect locator matches and actionability information, edit or pick locators, and pause at the point where the page state diverges from expectations. The official Debug Tests guide also documents adding await page.pause() to stop at a deliberate point in a test.
#1 Best Overall
- 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.
Use UI Mode for a wider view of the run
Run npx playwright test --ui to open UI Mode. It lets you walk through test steps and inspect errors, logs, network requests, DOM snapshots, and locators. This is useful when the terminal stack trace identifies where a test failed but leaves unclear what happened before it. The running and debugging tests guide covers UI Mode and test selection.
Read locator actionability evidence
When an action times out or behaves unexpectedly, check whether the locator matched the element you intended and whether that element was visible, enabled, and stable. The Inspector’s actionability information can reveal that a locator matched nothing, matched more than one element, or remained unable to act. Fix the selector or the page-state assumption before adding a longer timeout; a longer wait can hide a race without correcting it.
Turn on API or browser logs when needed
For more detail about Playwright API calls, set DEBUG=pw:api. For browser launch diagnostics, use DEBUG=pw:browser:
DEBUG=pw:api npx playwright test
DEBUG=pw:browser npx playwright testThese environment-variable examples use POSIX shell syntax. On other shells or operating systems, set the environment variable using that shell’s syntax before running the command. Logs add context, but can be noisy; enable the relevant category for a narrowed run.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRank #2
- 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.
Use Playwright traces to diagnose failures, especially in CI
A trace preserves an action timeline and related evidence such as snapshots, network activity, and logs. It is more useful than a screenshot alone when you need to reconstruct a sequence of interactions. To open a saved trace, run:
npx playwright show-trace trace.zipFor CI, configure Playwright Test to record a trace on the first retry of a failed test, rather than recording every test on every run. The Playwright best-practices guidance recommends traces for CI failures and warns that tracing every test can add substantial performance overhead. Playwright Test’s configuration can retain test-runner context, including assertions; the lower-level context tracing API alone does not record test assertions. See the Tracing API.
If the issue appears only in CI, compare the browser project, test configuration, environment, and captured logs alongside the trace. A headed Linux run in CI requires Xvfb, as documented in Playwright’s CI guide. A local headed run that passes does not, on its own, explain a CI-only failure.
Choose the right Puppeteer debugging tool
Puppeteer runs through a Node.js script that controls a browser, while application code may also run inside the page. First identify which execution context is implicated; the Puppeteer debugging guide distinguishes Node.js code, page code, and browser-process behavior.
Rank #3
- 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.
Make interactions visible and slower
Launch in headed mode and add slowMo to make actions easier to observe:
const browser = await puppeteer.launch({ headless: false, slowMo: 250 });
const page = await browser.newPage();
// Navigate and run the test actions you need to inspect.Headed mode and slow motion are observation aids, not fixes. They can change timing, so a pass in this mode does not rule out a race in a normal or CI run.
Forward page console messages to Node
Listen for page console events so client-side messages appear in the script’s output:
page.on('console', msg => console.log('PAGE LOG:', msg.text()));This helps when the test runner is quiet but the page reports errors or diagnostic messages.
Rank #4
- 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
Debug Node code and page code separately
- Node-side test code: put
debuggerin the script and run Node with--inspect-brk, then attach a Node inspector to step through the test’s control flow. - Page-side JavaScript: launch with
devtools: trueand placedebuggerinside the callback passed topage.evaluate(). Inspect that code in the browser’s DevTools.
A breakpoint in Node will not pause JavaScript running in the page, and a browser DevTools breakpoint will not trace the Node script that issued the command.
Inspect browser-process and protocol output carefully
Set dumpio: true in Puppeteer’s launch options to forward browser process output to the Node process. For lower-level protocol diagnostics, the guide documents NODE_DEBUG="puppeteer:*". Protocol debug output may contain sensitive information, so do not share it publicly without reviewing and redacting it.
Understand Puppeteer locators and traces
Check whether a selector waits or fails immediately
Puppeteer’s locator API waits for elements and checks action preconditions. Do not assume lower-level selector methods behave identically or retry in the same way. When an element is missing or not ready, verify which API the test uses and what waiting behavior it provides. The page interactions guide explains locator behavior and lower-level selector methods.
Record a browser timeline
Puppeteer can record a browser trace with page.tracing.start() and page.tracing.stop(), then open the resulting trace in Chrome DevTools or a timeline viewer. This is a browser/timeline artifact, not the same artifact as a Playwright Test trace with runner context and assertions. The Puppeteer Tracing class reference documents its tracing API.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
- 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.
Common debugging problems and what to try
| Symptom | Likely area to inspect | Next step |
|---|---|---|
| Playwright action times out | Locator match and actionability state | Use Inspector or UI Mode to check match count, visibility, enabled state, and stability. Correct the locator or state assumption before increasing timeouts. |
| Playwright passes locally but fails in CI | Environment, browser project, or timing differences | Collect a trace on failure or first retry; compare configuration, project, environment, and logs. For headed Linux CI, provide Xvfb. |
| Puppeteer test runs but page output is unclear | Page-side console or browser state | Forward console events to Node, then inspect the page in headed mode or DevTools. |
| Puppeteer breakpoint does not stop | Wrong execution context | Use Node’s inspector for Node code; use browser DevTools and a page-side debugger for code inside page.evaluate(). |
| Browser launch or process behavior is suspect | Browser process or protocol communication | Enable dumpio or documented protocol logging, and review output for sensitive data before sharing it. |
| Selector behaves differently than expected in Puppeteer | Locator versus lower-level selector API | Check the API’s documented waiting and precondition behavior; do not assume all selector methods retry alike. |
Or skip the browser setup
For a clean screenshot of a URL without setting up a browser capture flow, make one GET request. This is useful for checking the rendered page as evidence, though a screenshot does not replace a test trace when you need the full interaction timeline.
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 request options. ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server gives AI agents screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Try ScreenshotNeo free.
Frequently Asked Questions
Can I use Playwright trace files with Puppeteer?
No. They are framework-specific artifacts with different contents and inspection workflows.
Does running a test in headed mode prove that a CI failure is fixed?
No. It makes behavior visible, but local and CI environments can differ.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
