Skip to content
Get packs

Guide · Agent skill

How to use the Playwright Pro Testing Toolkit agent skill (pw)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The pw skill is a Playwright testing toolkit for AI coding agents. Once it is installed, the agent knows how to write, review, repair and migrate Playwright end-to-end tests for web apps, and it follows a built-in set of testing best practices. This guide explains what an agent skill is, how to install pw, how to trigger it with plain requests, and what it needs and what to watch out for.

Playwright Pro Testing Toolkitalirezarezvani/claude-skills · MIT

Quick start

  1. 1Download and unzip the skill. Download the pw ZIP from this page and unzip it. You will get the skill folder with SKILL.md and its reference and template files.
  2. 2Place the skill folder. Put it in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one project. Alternatively, upload it in the Claude apps under Settings → Capabilities → Skills.
  3. 3Check Node.js and Playwright. Make sure Node.js is installed and your project runs Playwright tests with npx playwright test.
  4. 4Ask for a test in plain language. Describe the flow or user story you want covered and, if you have one, the URL or component. The skill activates from the request.
  5. 5Review the generated tests. Ask the agent to review the new files for weak locators and missing assertions, then read the changes yourself.
  6. 6Run the suite locally. Run npx playwright test, adding --headed to watch the browser, and confirm the tests pass before committing.
  7. 7Fix failures when CI turns red. Point the agent at the failing or flaky test and ask it to diagnose and repair it, then re-run the full suite.

What an agent skill is and what pw makes the agent do

An agent skill is a folder of instructions and reference files that an AI coding agent loads when a task matches the skill's description. The agent reads the skill and follows its rules, so you do not have to explain the same testing conventions in every conversation.

With pw installed, the agent works on Playwright end-to-end tests for web apps. It can generate test files from a user story or URL, review tests for weak locators and missing assertions, diagnose and repair failing or flaky tests, and help move suites from Cypress or Selenium to Playwright.

  • Generate tests from a user story, URL or component
  • Review tests for anti-patterns and coverage gaps
  • Diagnose and fix failing or flaky tests
  • Migrate Cypress or Selenium suites to Playwright
  • Optionally sync with TestRail or run on BrowserStack (extra setup required)

Install the pw skill from the ZIP or the Claude apps

Download the ZIP of the pw skill from this page and unzip it. Place the resulting skill folder in one of two locations: ~/.claude/skills/ to make it available across your projects, or .claude/skills/ inside a specific project to limit it to that project.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the skill there.

The slash commands (/pw:...) listed in the skill are available when it is installed as a Claude Code plugin. Installing the files alone gives the agent the skill's instructions and reference material.

  • Option A: unzip into ~/.claude/skills/ (all projects)
  • Option B: unzip into a project's .claude/skills/ folder (one project)
  • Option C: upload in the Claude apps under Settings → Capabilities → Skills

Prerequisites: Node.js and Playwright

The skill's commands rely on Node.js and Playwright being present in your project. Tests are run with npx playwright test, which is the check the skill's own workflow uses after changes.

The TestRail and BrowserStack features are optional. They need a TestRail URL, user and API key, or a BrowserStack username and access key, plus a manual MCP server setup. Without that setup, the TestRail and BrowserStack commands fail.

  • Node.js and Playwright installed in the project
  • Claude Code plugin install if you want to use the /pw: commands
  • Optional: TestRail URL, user and API key
  • Optional: BrowserStack username and access key
  • Optional: manual MCP server setup (npm install in the integrations folder)
export TESTRAIL_URL="https://your-instance.testrail.io" export TESTRAIL_USER="your@email.com" export TESTRAIL_API_KEY="your-api-key" export BROWSERSTACK_USERNAME="your-username" export BROWSERSTACK_ACCESS_KEY="your-access-key"

Trigger the skill with natural requests

You do not need to type a command to use the skill. The skill is written to activate when you mention Playwright tests, end-to-end testing, browser automation, flaky tests, test migration, CI/CD testing or test suites. Describe what you want in plain language and name the file or page where it matters.

If you are using the Claude Code plugin, the same work can be triggered with explicit commands such as /pw:generate, /pw:pw-review, /pw:fix, /pw:migrate and /pw:coverage.

  • "Write Playwright tests for the login flow in this app"
  • "Review tests/auth/login.spec.ts for weak locators and missing assertions"
  • "This Playwright test is flaky in CI, find out why and fix it"
  • "Migrate the Cypress checkout tests to Playwright"
  • "Check which pages our Playwright suite does not cover yet"
/pw:generate "As a user I can log in with email and password" /pw:pw-review tests/auth/login.spec.ts /pw:fix tests/auth/login.spec.ts

Follow the recommended workflow: generate, review, fix

The skill's suggested sequence is to scaffold with /pw:pw-init, generate tests from a spec or URL, review them, and fix anything that fails. Review after every generate, because the review step flags locator anti-patterns and missing assertions.

After a fix, re-run the full suite locally with npx playwright test to check for regressions. After a migration, run /pw:coverage to compare the new suite with the old one before you retire Cypress or Selenium tests.

  • After generate: run review before committing
  • After fix: run npx playwright test across the full suite
  • After migrate: run coverage to confirm parity before decommissioning the old suite
npx playwright test tests/auth/login.spec.ts --headed

Know the built-in best-practice rules

The skill applies a set of golden rules. It prefers role-based locators such as getByRole() and falls back to CSS or XPath only as a last resort. It uses web-first assertions, which retry until they time out, instead of fixed waits such as waitForTimeout().

Other rules cover isolating each test, using baseURL in config instead of hardcoded URLs, and mocking only external services, never your own app. The reference files explain the locator priority, assertions, fixtures and common pitfalls in more detail.

  • Locator priority: getByRole, getByLabel, getByText, getByPlaceholder, getByTestId, then page.locator
  • Never use page.waitForTimeout(); use web-first assertions
  • Use expect(locator) rather than checking text once with await locator.textContent()
  • Retries set to 2 in CI and 0 locally; traces set to on-first-retry
  • Use fixtures via test.extend() for shared state
await page.goto('/login'); await expect(page.getByText('Welcome')).toBeVisible();

Safety notes: scripts, network and production systems

The skill runs scripts and uses the network. Its optional TestRail and BrowserStack integrations send requests to external services using the credentials you provide, so only set those variables when you intend to use them.

Generated or auto-fixed tests are edited directly in your project. Review them before committing, and do not run them against production systems without checking them first.

  • Keep API keys in environment variables, not in committed files
  • Review every generated or auto-fixed test before committing
  • Do not point generated tests at production without review
  • The TestRail and BrowserStack MCP servers are not auto-registered and must be enabled manually

What people use it for

  • Generate a first set of login or checkout tests from a user story
  • Review an existing Playwright suite for anti-patterns before a release
  • Repair flaky tests that use fixed waits by swapping in web-first assertions
  • Plan and convert a Cypress or Selenium suite to Playwright, then check coverage against the old tests
  • Set up Playwright config, CI and a smoke test in a new project with /pw:pw-init

Frequently asked questions

How do I install the pw Playwright agent skill?

Download the pw ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.

Is the Playwright Pro skill free to use?

The skill is published under the MIT licence. The source does not mention pricing, so check the licence and your own Claude plan for any costs of using the agent itself.

What do I need before using the pw skill?

You need Node.js and Playwright in your project, since tests run with npx playwright test. The /pw: commands require installing it as a Claude Code plugin. TestRail and BrowserStack are optional and need extra credentials and manual MCP setup.

Why do the TestRail or BrowserStack commands fail?

Those MCP servers are not registered automatically. Setting the environment variables is not enough; you must enable the server manually by running npm install in the integrations folder and registering it in your own MCP config. Until then, the commands report that the tool is not found.

Can pw migrate my Cypress or Selenium tests?

Yes, the skill includes migration guides with Cypress and Selenium mapping tables and a /pw:migrate command. Run /pw:coverage afterwards to confirm the new suite matches the old one before you retire the old tests.

Does pw work with tools other than Playwright?

No. The skill is specific to Playwright and to web apps or browser-based UIs. It is not the right choice for projects that have no browser-based interface to test.

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

pw suits developers who want Playwright tests written and reviewed to a consistent standard, teams fixing flaky end-to-end tests in CI, and engineers moving a Cypress or Selenium suite to Playwright. It is a poor fit if you have no browser-based UI, or if you need the TestRail or BrowserStack integrations without doing the extra setup, and you should always review generated or auto-fixed tests before committing them.

Download the skill