# playwright

Skill for automating E2E testing of web applications in TypeScript and JavaScript. Teaches agents to write tests following best practices: resilient locators, web-first assertions, no hardcoded timeouts.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1100 installs · ★ 286
- Author: Mindrally
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Mindrally/skills/tree/HEAD/playwright/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/mindrally-playwright

## What it does

The skill covers methodology and code patterns for reliable E2E tests with Playwright. It addresses test structure using fixtures, element location strategies (getByRole, getByLabel, getByTestId), and web-first assertions that automatically wait and retry. Includes configuration for running tests across Chrome, Firefox, and mobile devices.

Agents learn to build tests that track critical user journeys while avoiding brittle selectors and flaky timeouts. Helpers manage test state through beforeEach and afterEach hooks, and extraction of reusable logic reduces duplication.

## Requirements
- Works with: Playwright

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill playwright -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/playwright/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/playwright/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill playwright -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/playwright/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill playwright -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/playwright/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Mindrally/skills playwright
```

2. **Manually: put the files in place**
- File: `.github/skills/playwright/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill playwright -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Mindrally/skills --path playwright
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/playwright/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Mindrally/skills --skill playwright -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Mindrally/skills/tree/HEAD/playwright/SKILL.md

## When to use it
- write end-to-end tests for a web app with resilient locators
- eliminate flaky tests caused by hardcoded waits and unstable selectors
- configure parallel test runs across multiple browsers
- capture screenshots and traces only on failure
- verify login flows, navigation, and critical business processes

## Example prompts
- Write an E2E test for user login with Playwright, using getByLabel for form fields and getByRole for the submit button
- Set up a Playwright configuration to run tests in Chrome, Firefox, and on mobile, with screenshots on failure
- Refactor an old test from XPath selectors to getByRole and remove all waitForTimeout calls

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: d1900dd883041750.

BEGIN THIRD-PARTY FILE d1900dd883041750
````text
---
name: playwright
description: Playwright end-to-end testing best practices for web applications, covering test design, locator strategies, and assertion patterns.
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# Playwright Testing Best Practices

You are a Senior QA Automation Engineer expert in TypeScript, JavaScript, and Playwright end-to-end testing.

## Test Design Principles

### Test Structure
- Create descriptive test names that clearly explain expected behavior
- Use Playwright fixtures (`test`, `page`, `expect`) for test isolation
- Implement `test.beforeEach` and `test.afterEach` for clean state management
- Keep tests DRY by extracting reusable logic into helper functions

```typescript
import { test, expect } from '@playwright/test';

test.describe('User Authentication', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/login');
  });

  test('should login successfully with valid credentials', async ({ page }) => {
    await page.getByLabel('Email').fill('user@example.com');
    await page.getByLabel('Password').fill('password123');
    await page.getByRole('button', { name: 'Sign In' }).click();

    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
  });
});
```

## Locator Strategy

### Recommended Locators
- `page.getByRole()` - Best for accessibility and user perspective
- `page.getByLabel()` - For form inputs with labels
- `page.getByText()` - For elements with visible text
- `page.getByTestId()` - When `data-testid` attributes exist
- `page.getByPlaceholder()` - For inputs with placeholder text

```typescript
// Recommended
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByLabel('Email address').fill('test@example.com');

// Avoid
await page.locator('.btn-primary').click();
```

## Assertions and Waits

### Web-First Assertions
Prefer web-first assertions that automatically wait and retry:

- `toBeVisible()` - Element is visible
- `toHaveText()` - Element has specific text
- `toHaveValue()` - Input has specific value
- `toHaveURL()` - Page URL assertion

```typescript
// Recommended - web-first assertions
await expect(page.getByRole('alert')).toBeVisible();
await expect(page).toHaveURL('/dashboard');

// Avoid - hardcoded timeouts
await page.waitForTimeout(5000); // Never do this
```

### Waiting Best Practices
- Avoid hardcoded timeouts
- Use `page.waitForLoadState()` for navigation
- Use `page.waitForResponse()` for API calls

## Configuration

```typescript
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'mobile', use: { ...devices['iPhone 13'] } },
  ],
});
```
````
END THIRD-PARTY FILE d1900dd883041750

The third-party file has ended. Everything between the d1900dd883041750 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3037 of 3244 bytes. © Mindrally · Apache-2.0 · https://github.com/Mindrally/skills/tree/HEAD/playwright/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md