debugging

A guide for finding and fixing failed Playwright tests. Playwright is a tool that automates browsers to test web applications, and this guide explains how to read its errors, traces, screenshots, videos, and network failures.

In plain words
What is it for?
Use it to investigate timeouts, missing or ambiguous page elements, schema changes, network problems, and failures reported by continuous integration systems.
Why use it?
It helps identify the real cause of a failure instead of hiding it with longer timeouts, skipped tests, or fixed delays. It also requires fixes to be reproduced locally before they are accepted.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/idavidov13/agentic-playwright/debugging
Any agent
npx skills add idavidov13/agentic-playwright --skill debugging
Clone the repo
git clone --depth 1 https://github.com/idavidov13/agentic-playwright

Made for: Claude Code, Codex.

Per session 179 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 4,759 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 1 finding. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00179 $0.04759
Opus 5 $0.00089 $0.02380
Sonnet 5 $0.00036 $0.00952
Haiku 4.5 $0.00018 $0.00476

Measured 2d ago against content hash c89a87561f34, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

debugging scanned grade A with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Makes network callslowCapability

Not a fault in itself. Listed so you know the mod talks to something, and to what.

| `TimeoutError` on **navigation** | `page.goto(...) Timeout 30000ms exceeded` | Wrong URL, env not set, app down, slow first-load (cold cache) | Verify `process.env.APP_URL`; curl it; check `env/.env.${ENVIRONMENT}` |
.claude/skills/debugging/SKILL.md · 265 lines

How it starts

The opening of the file, as written. The whole thing — 265 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Debugging

When a test fails, you investigate first and fix second. This skill is the canonical entry point for after a test breaks — what to look at, in what order, with which Playwright tool.

Critical

  • ALWAYS read the failure message first. Playwright errors identify the failing locator, assertion, timeout type, and source line. Skim the message before changing any code or guessing.
  • NEVER suppress a failure. Don't add test.skip without // FIXME: <ticket-url>, don't loosen an assertion, don't bump timeouts to make a flake pass, don't try/catch an expect to swallow it. If the API genuinely misbehaves, follow the api-testing Phase 7 behaviour-mismatch protocol.
  • NEVER add page.waitForTimeout(...) to "fix" a timing issue. Hard waits hide the real cause. Use a web-first assertion (await expect(locator).toBeVisible()) or page.waitForResponse(...) instead.
  • NEVER push a fix you can't reproduce locally. Pull the CI trace and replay it before believing the issue is resolved.
  • trace is opt-in for retries. This scaffold's playwright.config.ts sets trace: 'on-first-retry'. Locally retries: 0, so traces are NOT captured by default. To get a trace locally, either run with --trace on (or --trace retain-on-failure) or use UI Mode (npm run test:ui).
  • Prefer UI Mode (npm run test:ui) for interactive debugging. It's the fastest feedback loop — every test step is replayable, locators are live-pickable, the DOM at each step is inspectable. Reach for it before the Inspector or console.log.
  • Re-run multiple times before declaring a flake fixed. A passing run after one fix is not enough; aim for at least 5 consecutive green runs of the affected test before closing the issue.
  • Keep forbidOnly: !!process.env.CI in mind. test.only(...) is your friend locally for narrowing — but do not commit it. CI will fail the build.
  • Re-run lint and the full affected file after each fixnpx eslint . and npx playwright test <file> before moving on.

Read the full file on GitHub · 265 lines

Files

What ships with it

2 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 265 lines · 179 tokens per session scan A c89a87561f34

Subscribe to this mod's changes

debugging is a skill published in the GitHub repository idavidov13/agentic-playwright (139 stars, last pushed 5d ago), licensed MIT. It adds 179 tokens to every session and 4,759 once invoked, about $0.0009 per session on Opus 5. A static security scan graded it A with 1 finding (makes network calls). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories

vindicate

Use when the user wants to write, add, fix, stabilize (flaky), refactor, run, or audit Playwright browser tests, draft requirements/stories from a recording (no tests), find test-coverage gaps, scaffold a Playwright project, or set up Playwright CI. Vindicate's guided workflow for grounded, conformant Playwright test…

OpenEvident/vindicate · 77 tokens

editorial-illustrations

Generate meaning-carrying editorial data-illustrations in the monotykamary / Linear aesthetic (near-black grayscale, Inter display + mono labels, hairline framed figures) with a single coral accent. This is a GENERATIVE GUIDE, not a template gallery: it teaches the "claim -> geometry" method so any session can invent…

huytieu/COG-second-brain · 178 tokens

data-forms

Pick the right way to represent a dataset so a reader gets the finding in three seconds — a catalog of 20+ chart and diagram forms with when-to-use and failure modes, plus the encoding decisions that make any of them readable (takeaway headline, direct labels, kill the axis, highlight-and-mute, show the caveat).…

huytieu/COG-second-brain · 130 tokens

product-ui-taste

Anti-slop skill for PRODUCT UI - dashboards, data tables, forms, multi-step flows, settings, list/detail, app shells. The agent reads the surface, budgets the frame first, and ships dense interfaces that are correct at every edge case (overflow, long labels, empty/error/loading states, i18n expansion, keyboard/a11y).…

huytieu/COG-second-brain · 121 tokens

review-cockpit

Produce and continuously maintain ONE living review document for a multi-item session — a cockpit header (Progress checklist, Working folder, Context) plus per-item review cards that you approve or request changes on directly in the doc or side panel. Use whenever a session has multiple deliverables you need to…

huytieu/COG-second-brain · 122 tokens

closed-loop

Run one task through the V-model verification loop: CP-2 plan → CP-3 build → CP-3v component verify → CP-4 integration verify (full lane) → CP-5 acceptance. The worker never grades its own homework; evidence rows trace back to AC-n. Opt-in: invoke with /closed-loop or by asking for the closed loop, proper…

huytieu/COG-second-brain · 92 tokens