agentsclimarketplace

Playwright debug

Skill iam-nazmul/playwrite_testkit_tool/skills/playwright-debug

Diagnose failing or flaky Playwright tests — trace viewer, UI mode, headed/debug runs, timeout triage, strict-mode violations, and flakiness root causes. Use when a test fails, passes locally but fails in CI, or fails intermittently.From its SKILL.md

Install
npx -y skills add iam-nazmul/playwrite_testkit_tool --skill playwright-debug

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.9 KB, as published. Nobody here has run it

Debugging Playwright tests

Read the failure before changing anything. Playwright's error messages name the locator, the assertion, and the timeout — most fixes follow directly from them, and a raised timeout is almost never the right fix.

Tools, in order of usefulness

npx playwright test --ui                       # time-travel runner: watch, step, inspect locators
npx playwright show-trace test-results/.../trace.zip   # post-mortem of a CI failure
npx playwright test --debug                    # Playwright Inspector, step through
npx playwright test --headed                   # watch it run in a real browser
npx playwright test path/to/file.spec.ts:12    # one test, by line number

UI mode is the right default while writing tests. Traces are the right tool for a failure you cannot reproduce locally — which is most CI failures.

Traces

use: { trace: 'on-first-retry' }   // recommended: cost only on failure

Other values: 'on' (always, slow and large), 'retain-on-failure', 'off'. With retries: 0 there is no first retry, so on-first-retry records nothing — pair them.

A trace gives you, per action: a DOM snapshot before/after, the network log, console output, the source line, and the exact locator. Open the failing action, click the locator, and check what was actually on the page at that instant. That usually ends the investigation.

CI: upload playwright-report/ (or test-results/) as an artifact, or traces are lost with the runner.

Reading common failures

Timeout 30000ms exceeded waiting for a locator — the element never reached the required state. Ask, in order: is it in an iframe (page.frameLocator)? Behind a different accessible name? Rendered only after a request that failed? Genuinely absent because the previous step silently no-op'd? Raise the timeout only when the app is legitimately slow, and prefer raising it for that one assertion (expect(...).toBeVisible({ timeout: 15_000 })) over globally.

strict mode violation: locator resolved to N elements — good failure; it caught real ambiguity. Narrow with .filter({ hasText }), scope to a container, or use .first() only if any match truly is acceptable.

Element is not visible / intercepts pointer events — an overlay, cookie banner, or sticky header is covering the target, or an animation is still running. Dismiss the overlay in setup; do not force: true your way past it, since that skips the checks that model whether a user could actually click.

Passes locally, fails in CI — nearly always one of: different viewport, missing --with-deps browsers, slower machine exposing a real race, timezone/locale differences, or animations. Pin viewport, locale, and timezoneId in the config to remove the variance.

Flaky tests

Reproduce first — a flake you cannot trigger is a flake you cannot verify fixed:

npx playwright test failing.spec.ts --repeat-each=20 --workers=4

Root causes, in rough order of frequency:

  1. A missing await. The test races ahead of the action. Enable @typescript-eslint/no-floating-promises; it catches these statically.
  2. Manual waits. waitForTimeout passes on a fast machine and fails on a loaded CI runner. Replace with an assertion on the end state.
  3. Non-retrying checks. expect(await locator.isVisible()).toBe(true) samples one instant. Use await expect(locator).toBeVisible().
  4. Shared state between tests. A user, record, or account mutated by another test running in parallel. Isolate the data per test or per worker.
  5. Asserting on animated/transitioning elements. Assert on the settled state, or disable animations in the test environment.
  6. Real third-party calls. Mock them with page.route.

retries is damage control, not a fix — a retried test still hides a real race that users can hit. Track flakes from the HTML report's flaky section and fix the cause.

Console and network noise

page.on('console', msg => console.log(`[${msg.type()}]`, msg.text()));
page.on('pageerror', err => console.log('page error:', err));
page.on('requestfailed', req => console.log('failed:', req.url()));

Attaching these temporarily often reveals that the real problem is an app-side exception, not the test.

Slowing things down

// playwright.config.ts — local investigation only, never commit
use: { launchOptions: { slowMo: 500 } }

Isolating a step

await page.pause();   // opens the Inspector at this point in the run

Remove page.pause(), slowMo, and test.only before committing — forbidOnly in the config catches the last one on CI.

Related: playwright-write-test, playwright-ci.

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.