fix is a Playwright debugging skill for failing or flaky tests. It guides agents through reproduction, burn-in runs, trace capture, and taxonomy-based diagnosis for timing, isolation, environment, and infrastructure issues.
This skill scores 80/100, making it a solid listing candidate for directory users who want an agent to debug failing or flaky Playwright tests with less guesswork than a generic prompt. It has clear triggers and a usable troubleshooting taxonomy, though adoption clarity is limited by the lack of install/readme materials and by assumptions about the user's Playwright setup.
- Highly triggerable frontmatter lists concrete user phrases such as "fix test", "flaky test", "debug test", and "intermittent failure".
- Provides a practical diagnostic workflow: reproduce, burn-in with repeat runs, run with parallel workers, capture traces, and categorize the failure.
- Includes a separate flaky-test taxonomy with a decision tree and concrete Playwright fix patterns for timing, isolation, environment, and infrastructure issues.
- No install command, README, or metadata is provided in the skill directory, so users must infer installation from the broader repository context.
- Workflow assumes a Node/Playwright project using npx and gives limited guidance for projects with custom runners, configs, or nonstandard CI setups.
Overview of fix skill
What the fix skill does
The fix skill is a focused debugging workflow for failing or flaky Playwright tests. It helps an AI agent move from “this test is broken” to a likely root cause by reproducing the failure, capturing trace evidence, and classifying the issue with a flaky-test taxonomy instead of guessing from the assertion error alone.
Best fit for Playwright test debugging
Install this skill if you maintain end-to-end tests and regularly see messages such as “test failing,” “flaky test,” “passes locally but fails in CI,” or “intermittent failure.” It is especially useful for teams using Playwright in CI where failures may come from timing, test isolation, environment differences, or infrastructure pressure.
Why it is more useful than a generic prompt
A generic debugging prompt often jumps straight to code edits. The fix skill forces a better sequence: reproduce first, burn in if the failure disappears, capture traces, then map symptoms to categories. Its companion flaky-taxonomy.md gives concrete diagnostic branches and fix patterns, including missing await, shared state, CI-only viewport/font/timezone differences, browser crashes, and worker-related instability.
Important limitations before install
This is not a universal bug fixer. It is scoped to Playwright tests and assumes the agent can inspect your test file, run Playwright commands, and read output such as traces, screenshots, logs, or CI failure text. It has no helper scripts, so its value comes from the workflow and taxonomy rather than automation.
How to Use fix skill
fix install and files to inspect first
Install the skill in a compatible skills environment with:
npx skills add alirezarezvani/claude-skills --skill fix
After installing, read SKILL.md first for the execution workflow, then open flaky-taxonomy.md for the decision tree and common fixes. The repository path is engineering-team/playwright-pro/skills/fix, and the useful source files are intentionally small: there are no hidden scripts, rules, or metadata files to configure.
Inputs the fix skill needs
For best results, provide at least one of these inputs:
- Test file path, such as
e2e/login.spec.ts - Exact test name or
--grepstring - Failure message, stack trace, or assertion error
- Whether the failure happens locally, in CI, or both
- Whether it passes alone but fails in the full suite
- Trace, screenshot, video, or CI artifact path if available
- Relevant Playwright config, especially workers, retries, projects, viewport, timezone, and base URL
Weak prompt: “Fix my flaky checkout test.”
Stronger prompt: “Use the fix skill for Debugging e2e/checkout.spec.ts, test should submit paid order. It passes locally alone, fails in CI about 30% of runs, and the failure is Timeout 5000ms exceeded waiting for getByRole('button', { name: 'Pay' }). CI uses 4 workers and retries=2. Suggest the reproduction commands, likely category, and minimal code/config changes.”
Practical fix usage workflow
Start with the exact failing file:
npx playwright test <file> --reporter=list
If it passes, treat it as potentially flaky and run burn-in:
npx playwright test <file> --repeat-each=10 --reporter=list
If the issue appears only under concurrency, run with parallelism:
npx playwright test --fully-parallel --workers=4 --repeat-each=5
Then capture trace evidence:
npx playwright test <file> --trace=on --retries=0
Ask the agent to classify the failure before editing. The expected categories are timing/async, test isolation, environment, or infrastructure. This prevents common bad fixes such as adding arbitrary waitForTimeout, increasing global timeouts, or hiding a real race behind retries.
Prompt pattern for better results
Use a prompt that separates evidence from request:
“Use the fix skill. Diagnose before changing code. Test: <file> / <test name>. Reproduction result: <passes/fails command>. CI/local behavior: <details>. Trace or screenshot: <path or summary>. Current suspicion: <optional>. Please categorize using flaky-taxonomy.md, explain the evidence, propose the smallest safe fix, and list the command to verify it.”
This structure helps the skill produce a testable debugging plan instead of a speculative patch.
fix skill FAQ
Is fix only for flaky tests?
No. The fix skill handles both consistently failing Playwright tests and intermittent failures. For deterministic failures, it still starts with reproduction and trace capture. For intermittent failures, it adds burn-in and parallel-worker checks to expose timing, isolation, or infrastructure patterns.
When should I not use this skill?
Do not use it as the main tool for unit tests, backend integration tests, production bugs without Playwright coverage, or broad application architecture debugging. It may still provide general ideas, but its commands, taxonomy, and examples are written for Playwright end-to-end tests.
How does it compare with Playwright trace viewer alone?
Trace viewer shows what happened; the fix skill helps decide what the trace means. For example, a missing element could indicate an async race, leaked state from a previous test, a CI viewport difference, or a network dependency. The taxonomy turns artifacts into a diagnosis path and suggested fix type.
Is fix beginner-friendly?
Yes, if the user can run Playwright commands and share errors. Beginners benefit from the explicit command sequence and category table. However, the skill does not replace basic project setup knowledge: Playwright must already be installed, the test suite must be runnable, and artifacts must be accessible.
How to Improve fix skill
Give fix stronger failure evidence
The most important improvement is better input quality. Include exact commands already tried and their outcomes. “Fails in CI” is less useful than “fails in CI with 4 workers, passes locally with one worker, fails locally with --fully-parallel --workers=4 --repeat-each=5.” That single detail points toward isolation or parallelism rather than generic timing.
Avoid common debugging failure modes
Do not ask for a patch before diagnosis. Common bad outcomes include adding fixed sleeps, raising global timeouts, enabling more retries, or rewriting selectors without confirming the cause. Ask the skill to state the category, evidence, minimal fix, and verification command before editing code.
Iterate after the first fix
After applying a proposed change, rerun the smallest meaningful verification command. If the fix targeted timing, use burn-in. If it targeted isolation, compare single-test versus suite behavior. If it targeted CI environment, reproduce with closer CI settings such as Docker, workers, timezone, viewport, or mocked network services.
Extend the fix guide for your project
Teams can improve local results by adding project-specific notes near the skill workflow: common CI settings, known flaky services, required test data resets, standard fixtures, mock strategy, and preferred locator conventions. The fix skill works best when its taxonomy is combined with your repository’s real failure patterns.