Playwright Skill: Train Your AI Agent to Write Better Tests

I've been writing end-to-end tests with AI agents, and the output is still hit or miss.

Wrong selectors, broken auth, flaky CI runs.

The problem? Agents don't have context about your app. That's where skills come in, structured guides that tell the agent what patterns to follow instead of guessing.

After working across multiple Playwright projects and getting input from other experts, I created a set of high-quality Playwright skills covering auth flows, visual testing, CI setup and scaling tests. Better context in, better code out.

Get the Playwright Skill

Install 70+ production-tested skills with a single command:

npx skills add testdino-hq/playwright-skill

View on GitHub ↗ 

What is a Playwright Skill?

A Playwright Skill is a curated collection of markdown guides that teach AI coding agents (and humans) how to write production-grade Playwright tests.

Here is the problem it solves. Playwright's official documentation is excellent. But it is spread across dozens of pages. When you ask an AI agent like Claude Code or GitHub Copilot to write tests, it pulls from its general training data. The output works for tutorials. It falls apart on real sites.

A Skill changes this. It gives the AI agent a structured, battle-tested reference to draw from. Instead of guessing which locator strategy to use or how to handle auth flows, the agent reads the relevant guide and produces code that follows patterns proven in production.

The Playwright Skill is not just for AI agents, though. Every guide is written in plain markdown. Human developers can read them, bookmark them, and use them as a cheat sheet. Think of it as a testing knowledge base that works for both humans and machines.

Why structured skill guides beat scattered documentation

Documentation tells you what an API does. A skill guide tells you when to use it, when to avoid it, and what pattern to follow in a real project.

Every guide in the Playwright Skill follows the same structure:

• When to use: exact scenarios where the pattern applies

• Avoid when: anti-patterns and wrong use cases

• Quick reference: copy-paste code ready to go

• Full patterns: real-world implementations with context

• TypeScript and JavaScript examples for both camps

This consistency matters. Whether you are a junior tester opening Playwright for the first time or a senior engineer migrating a Cypress suite, you get the same structure and the same depth across all 70+ guides.

The Playwright Skill repository

The Playwright Skill is an open-source repository maintained by TestDino. It is MIT licensed. Use it however you want. Fork it. Customize it. Share it with your team.

The repo contains 70+ guides organized into five skill packs, each in its own folder:

playwright-skill/
├── core/                    # 46 guides. The foundation.
├── playwright-cli/          # 11 guides. CLI browser automation.
├── pom/                     # 2 guides. Page Object Model patterns.
├── ci/                      # 9 guides. CI/CD pipelines.
├── migration/               # 2 guides. Moving from Cypress or Selenium.
├── LICENSE                  # MIT
├── README.md
└── SKILL.md                 # Metadata for AI agent loading

The rest of this guide walks through each pack in order, from fundamentals to advanced topics.

Getting Started: Install the Playwright Skill

Prerequisite

You'll need an AI coding agent like Claude Code, Cursor, Windsurf, GitHub Copilot etc. installed before getting started.

Step 1: Install

The fastest way is using the skills CLI, you can watch below video to learn How to install Playwright Skill using Claude Code

# Install all 70+ guides
npx skills add testdino-hq/playwright-skill
# Or install individual packs
npx skills add testdino-hq/playwright-skill/core
npx skills add testdino-hq/playwright-skill/ci
npx skills add testdino-hq/playwright-skill/playwright-cli
npx skills add testdino-hq/playwright-skill/pom
npx skills add testdino-hq/playwright-skill/migration

You can also clone or fork the repository directly:

# Clone the repository
git clone https://github.com/testdino-hq/playwright-skill.git

Step 2: Understand the SKILL.md metadata

The root of the repo contains a SKILL.md file. This is the metadata that AI coding agents read to understand what the skill covers and how to use it. It tells the agent which guides are available, what topics they cover, and how to find them.

You do not need to modify this file unless you are building a custom skill. But understanding it helps if you want to see how AI agents discover and load skill guides.

Step 3: Use it with Claude Code

Once the Playwright Skill is installed, Claude Code automatically loads the relevant guides when you ask it to write tests. For example:

• "Write E2E tests for my login page" triggers Claude to read authentication.md, locators.md, and assertions-and-waiting.md

• "Set up GitHub Actions for Playwright" pulls in ci-github-actions.md and parallel-and-sharding.md

• "Migrate my Cypress tests" loads from-cypress.md

The Skill works with any AI coding agent that supports the skills protocol. Claude Code, GitHub Copilot, and Cursor all support loading skills.

I tested this on a live e-commerce store, and the difference was massive. Without the Skill, Claude Code generated tutorial-quality code with brittle CSS selectors. With the Skill loaded, it used getByRole() locators, proper wait strategies, and structured test patterns that actually passed against a real site.

Step 4: Customize for your team

The repo is MIT licensed. Fork it and make it yours. Add your team's naming conventions, remove guides for frameworks you do not use, or add new guides for your internal tools. The structure stays the same. Your AI agent keeps working. But the output matches your team's standards.

1. Core Skill Pack (46 Guides)

The core/ folder is the foundation. It contains 46 guides covering every pattern you need for day-to-day Playwright testing.

Example: Locator priority

The locators.md guide teaches the locator order that makes tests resilient to DOM changes:

// Most stable to least stable
page.getByRole('button', { name: 'Submit' })    // 1. Role-based
page.getByText('Welcome back')                   // 2. Text-based
page.getByLabel('Email address')                 // 3. Label-based
page.getByTestId('login-form')                   // 4. Test ID
page.locator('.submit-btn')                      // 5. CSS (last resort)

Role-based locators survive redesigns. CSS selectors break the moment a developer renames a class.

Example: Authentication reuse

The authentication.md guide shows how to log in once and share the session across all tests:

async function globalSetup() {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('https://yourapp.com/login');
  await page.getByLabel('Email').fill('[email protected]');
  await page.getByLabel('Password').fill('password');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.context().storageState({ path: './auth.json' });
  await browser.close();
}

Every test starts logged in. No repeated login flows. No wasted time.

2. Playwright CLI Skill Pack (10 Guides)

The playwright-cli/ folder covers a different way to use Playwright. Instead of writing .spec.ts files, you drive a real browser through command-line instructions. Microsoft built playwright-cli playwright-cli specifically for AI coding agents because it is far more token-efficient than MCP-based approaches.

Example: Snapshot-based automation

The core idea is token efficiency. Instead of streaming the full accessibility tree to an AI agent, the CLI saves a snapshot with short element references. The agent then uses those references in subsequent commands:

# Open a browser and take a snapshot
playwright-cli open https://storedemo.testdino.com/
playwright-cli snapshot

# Interact using element references from the snapshot
playwright-cli click e15
playwright-cli fill e5 "[email protected]"
playwright-cli press Enter
playwright-cli screenshot

Each command is a single line. The AI agent spends tokens on reasoning, not on processing massive browser state dumps.

Page Object Model Skill Pack (2 Guides)

The pom/ folder covers one of the most common architectural decisions in Playwright projects.

Example: A basic Page Object

// pages/LoginPage.ts
export class LoginPage {
  constructor(private page: Page) {}
  async login(email: string, password: string) {
    await this.page.getByLabel('Email').fill(email);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Sign in' }).click();
  }
}

POM works best for pages with many interactions reused across test files. Fixtures are better for shared setup logic. Helpers are for one-off utility functions. The pom-vs-fixtures-vs-helpers.md guide walks through the decision criteria so you pick the right pattern.

3. CI/CD Skill Pack (9 Guides)

The ci/ folder covers every major CI platform and deployment pattern.

Example: GitHub Actions workflow

name: Playwright Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/

The guide covers caching browser binaries to speed up CI and configuring retries for CI-only flakiness.

Example: Sharding across machines

strategy:
  matrix:
    shard: [1/4, 2/4, 3/4, 4/4]
steps:
  - run: npx playwright test --shard=${{ matrix.shard }}

4. Migration Skill Pack (2 Guides)

Lot of teams are moving to Playwright right now - some are coming from Selenium, some others from Cypress.

The migration/ folder maps your existing framework knowledge to Playwright equivalents.

Instead of learning everything from scratch, these guides show you what changes and what stays the same, so your agent rewrites tests using the right Playwright patterns instead of carrying over old habits.

If you're still deciding which tool fits your team, check out the Selenium VS Cypress VS Playwright comparison.

Cypress to Playwright: quick reference

Selenium to Playwright: quick reference

The biggest shift for Selenium users is auto-waiting. Playwright handles element readiness automatically, so most explicit waits can be removed entirely.

5. Last step: Integrate TestDino for Real-Time Streaming

You have the Playwright Skill loaded. Your tests are written, running, and passing in CI. But there is a gap.

npx playwright test generates an HTML report on your machine. That report disappears after the CI pipeline finishes. Your team cannot see it. You cannot compare it against last week's run. And when a test fails at 2 AM, you are digging through CI logs instead of looking at a dashboard.

This is where TestDino fits.

What is TestDino?

TestDino is a Playwright-first AI reporting and analytics platform. It takes your existing Playwright test output and gives it a permanent home with real-time result streaming, AI-powered failure categorization (Bug, Flaky, or UI Change), flaky test tracking over time, GitHub PR integration with AI summaries, one-click Jira and Linear ticket creation, and Slack notifications when tests fail.

Quick setup

The integration takes about two minutes.

1. Install the package

npm install @testdino/playwright

2. Run tests with the TestDino wrapper

# Replace npx playwright test with:
npx tdpw test -t "your-api-token"

Every Playwright CLI flag works the same. --project, --grep, --workers, --shard, --headed. Nothing changes except results now stream to the TestDino dashboard in real time.

3. For CI, use an environment variables

- name: Run Playwright Tests
  run: npx tdpw test --project=desktop-chrome
  env:
    TESTDINO_TOKEN: ${{ secrets.TESTDINO_API_KEY }}

That is it. Your test results now have a permanent, searchable dashboard. AI categorizes every failure. Your team sees results as tests finish, not after the entire suite completes.

For a detailed walkthrough with screenshots and advanced configuration, see our full TestDino integration guide full TestDino integration guide.

Conclusion

With 70+ production-tested guides across five skill packs, the Playwright Skill provides a complete reference for building reliable Playwright test suites. It covers everything from element locators and authentication to CI pipelines and framework migrations.

The repository is open source and fully customizable, allowing teams to adapt it to their workflows. AI coding agents also benefit by using structured guides instead of generic examples, which improves the quality of generated tests.

By providing clear patterns, proven practices, and organized coverage of all key testing areas, the Playwright Skill helps teams scale Playwright testing with confidence and maintain long-term test reliability.

FAQs

The  Playwright Skill is open source and maintained by TestDino. Contributions, feedback, and pull requests are welcome.

Pratik Patel

Founder & CEO

Pratik Patel is the founder of TestDino, a Playwright-focused observability and CI optimization platform that helps engineering and QA teams gain clear visibility into automated test results, flaky failures, and CI pipeline health. With 12+ years of QA automation experience, he has worked closely with startups and enterprise organizations to build and scale high-performing QA teams, including companies such as Scotts Miracle-Gro, Avenue One, and Huma.

Pratik is an active contributor to the open-source community and a member of the Test Tribe community. He previously authored Make the Move to Automation with Appium and supported lot of QA engineers with practical tools, consulting, and educational resources, and he regularly writes about modern testing practices, Playwright, and developer productivity.

View all posts →