agentic-playwright debugging.instructions.md

A set of instructions for investigating and fixing failed Playwright browser tests, including how to use error messages, assertions, waits, and retry traces.

In plain words
What is it for?
Use it to debug failing end-to-end tests, inspect Playwright errors and CI traces, and choose appropriate checks or response waits.
Why use it?
It prevents guessed fixes that hide the real problem, such as skipping tests, increasing timeouts, or adding fixed delays. It also requires reproducing failures locally before shipping a fix.

Instructions file for GitHub Copilot

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 instructions/idavidov13/agentic-playwright/debugging
Clone the repo
git clone --depth 1 https://github.com/idavidov13/agentic-playwright

Made for: GitHub Copilot.

Per session 4,500 This file is loaded in full into every session.
When invoked 4,500 The same file — it is already loaded in full.
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.04500 $0.04500
Opus 5 $0.02250 $0.02250
Sonnet 5 $0.00900 $0.00900
Haiku 4.5 $0.00450 $0.00450

Measured yesterday against content hash 624899e3208e, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

agentic-playwright debugging.instructions.md 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 yesterday.

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}` |
.github/instructions/debugging.instructions.md · 261 lines

How it starts

The opening of the file, as written. The whole thing — 261 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 · 261 lines

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. yesterday First seen · 261 lines · 4,500 tokens per session scan A 624899e3208e

Subscribe to this mod's changes

agentic-playwright debugging.instructions.md is an instructions file published in the GitHub repository idavidov13/agentic-playwright (134 stars, last pushed 5d ago), licensed MIT. It adds 4,500 tokens to every session, about $0.0225 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.