Guide · Agent skill
How to use the Playwright Test Reviewer agent skill (pw-review)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The pw-review skill is an agent skill that reviews your Playwright test files for quality problems. It checks each file against a list of 20 common anti-patterns, gives it a score from 1 to 10, lists the issues with line numbers, and offers to apply the fixes once you approve them. This guide explains what the skill does, how to install it, how to trigger it, and what to watch for, so you can run your first review on a real test suite.
Playwright Test Revieweralirezarezvani/claude-skills · MIT Download the skill Quick start
- 1Check your project. Confirm you have a playwright.config.ts file and *.spec.ts or *.spec.js test files.
- 2Download and unzip. Download the pw-review ZIP from this page and unzip it so the pw-review folder is ready to copy.
- 3Place the skill folder. Put pw-review in ~/.claude/skills/ for personal use, or in your project's .claude/skills/ folder for one project.
- 4Ask for a review. Use a phrase such as "audit tests" or "review tests", and name a file, a folder, or nothing for the whole project.
- 5Read the report. Check each file's score and its Critical, Warning, and Suggestions items with line numbers.
- 6Approve or decline fixes. Answer Yes to apply the fixes with Edit, after reviewing the changes.
What is an agent skill, and what does pw-review do?
An agent skill is a folder containing a SKILL.md file that tells an AI agent how to perform a specific task. The agent loads the skill when your request matches the skill's description.
The pw-review skill tells the agent to read your Playwright test files and check them for anti-patterns, missed best practices, and coverage gaps. Its anti-pattern checklist is in a companion file, anti-patterns.md, which the agent loads during the review.
- Critical issues (must fix): fixed-time waits such as waitForTimeout(), non-web-first assertions such as expect(await ...), hardcoded URLs instead of baseURL, CSS or XPath selectors when a role-based locator exists, missing await on Playwright calls, shared mutable state between tests, and test execution order dependencies.
- Warnings (should fix): tests longer than 50 lines, magic strings without named constants, missing error or edge case tests, page.evaluate() used for things locators can do, nested test.describe() more than 2 levels deep, and generic test names like "should work".
- Info (consider): no page objects for pages with 5+ locators, inline test data instead of a factory or fixture, missing accessibility assertions, no visual regression tests for UI-heavy pages, unchecked console errors, network idle waits, and missing test.describe() grouping.
- Coverage gaps: pages or features that have no tests.
What do you need before you install it?
The skill is built for one kind of project. Check these requirements first.
You need a Playwright test project that has a playwright.config.ts file and *.spec.ts or *.spec.js test files. You also need an agent that supports SKILL.md skills and has file read and edit tools.
The skill does not run scripts and does not use the network, according to its listing.
How do you install the pw-review skill?
Download the pw-review ZIP from this page and unzip it. Then put the pw-review folder in one of these locations:
For a personal skill available in all your projects, unzip it into ~/.claude/skills/.
For a skill that only applies to one project, unzip it into that project's .claude/skills/ folder.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/pw-review/
- Project install: <your-project>/.claude/skills/pw-review/
- Claude apps: Settings → Capabilities → Skills
How do you trigger a Playwright test review?
You do not need a special command. The skill loads when your request includes a phrase from its description. These phrases include "review tests", "check test quality", "audit tests", "improve tests", "test code review", and "playwright best practices check".
You can also point the review at a scope. The skill accepts a file path to review one test file, a directory to review every test file in it, or nothing, which reviews all tests in the project's testDir.
- Review this test file: tests/login.spec.ts
- Audit tests in the tests/checkout/ folder
- Check test quality for the whole project
- Run a playwright best practices check on tests/dashboard.spec.ts
What does a review report look like?
The agent writes a report for each file. Each report has a score and lists issues under Critical, Warning, and Suggestions headings, with line numbers. The skill's template shows this format:
- Score ranges: 9-10 production-ready; 7-8 good with minor improvements; 5-6 functional but has anti-patterns; 3-4 significant issues, likely flaky; 1-2 needs rewrite.
- The summary includes total files, average score, critical issue count, a fix list, and coverage gaps.
## <filename> — Score: X/10
### Critical
- Line 15: `waitForTimeout(2000)` → use `expect(locator).toBeVisible()`
- Line 28: CSS selector `.btn-submit` → `getByRole('button', { name: "submit" })`
### Warning
- Line 42: Test name "test login" → "should redirect to dashboard after login"
### Suggestions
- Consider adding error case: what happens with invalid credentials?How do you review a large test suite?
For a whole test suite, the skill can start sub-agents to review files in parallel, up to 5 at a time. For very large suites, it can use /batch instead.
Parallel review and automatic edits can change many files at once. Read the proposed changes before you accept them.
- Start with one folder or one file to see how the output looks.
- Review the aggregated summary table before asking for fixes.
How do you apply the suggested fixes?
For each critical issue, the agent provides corrected code and asks: "Apply these fixes? [Yes/No]". If you answer yes, it applies all fixes using the Edit tool.
Because the skill edits files, check the diff in your version control before you commit. Answer no if the proposed changes do not match what you want.
What people use it for
- Cleaning up a flaky end-to-end suite by finding fixed-time waits and fragile selectors.
- Checking a single new spec file for shared state, test order dependencies, or generic test names before a merge.
- Finding pages or features that have no tests, using the coverage gap list.
- Getting a consistent quality check across a team's Playwright tests.
- Learning web-first assertions and role-based selectors by reading the suggested replacements.
Frequently asked questions
Is the pw-review skill free to use?
The skill is published under the MIT licence, according to its listing. Check the repository's licence file for the full terms before you use or redistribute it.
How do I install the pw-review agent skill?
Download the ZIP from this page and unzip it. Put the pw-review folder in ~/.claude/skills/ for personal use or in your project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills.
What does the playwright test reviewer check for?
It checks each test file against 20 anti-patterns, including waitForTimeout() calls, non-web-first assertions, hardcoded URLs, CSS or XPath selectors, and tests that depend on each other. It also flags coverage gaps where pages or features have no tests.
Does the skill work with projects that don't use Playwright?
No. The listing says the anti-patterns and checks are specific to Playwright, so the skill is for Playwright test projects only.
Does pw-review change my test files automatically?
Not without asking. It offers the fixes and asks Yes or No first. If you say yes, it applies them with the Edit tool, so review the diffs before you accept.
What do I need to run the pw-review skill?
You need a Playwright test project with playwright.config.ts and *.spec.ts or *.spec.js files, plus an agent that supports SKILL.md skills and has file read and edit tools. The listing says it runs no scripts and uses no network.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use pw-review if you maintain a Playwright suite that has become flaky or hard to read, or if your team wants one consistent quality check before merging. Skip it if you do not use Playwright, if you are not comfortable reading test code, or if you plan to let it rewrite a very large suite without reviewing the diffs first.
Download the skill