Playwright Test Builder

MIT License

Copyright (c) 2026 OpenAgentSkills Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Playwright Test Builder

What this skill does

This skill directs the agent to write well-structured Playwright end-to-end tests for a given user flow or page. It produces tests with proper locator strategies (preferring accessible selectors over brittle CSS), meaningful assertions at every step, correct async/await handling, and solid setup/teardown. The output is ready to drop into a tests/ folder and run immediately.

Use this when you want reliable E2E coverage for critical user journeys — login, checkout, form submission, navigation flows — without writing boilerplate from scratch.

How to use

Claude Code / Cline

Copy this file to .agents/skills/playwright-test-builder/SKILL.md in your project root.

Then describe the flow you want tested and ask:

• *"Use the Playwright Test Builder skill to write E2E tests for the login flow."*
• *"Write Playwright tests for the checkout process using the Playwright Test Builder skill."*

Provide the page URL (or a description of the UI), the steps in the flow, and any known selectors or data-testid values if you have them.

Cursor

Add the "Prompt / Instructions" section below to your .cursorrules file. Then describe the flow to test in the chat.

Codex

Paste the relevant HTML or React component code alongside the flow description and the instructions below. Seeing the actual markup helps Codex pick the most stable locators.

The Prompt / Instructions for the Agent

When asked to write Playwright tests, follow these steps:

1. Understand the flow. Ask for (or infer from context):

• The URL or page being tested
• The steps a user takes (click X, fill Y, expect Z)
• Any test data needed (usernames, passwords, form values)
• Whether authentication is required before the test

2. Choose locators in this priority order (most stable first):

• getByRole() with accessible name — best for buttons, links, inputs, headings
• getByLabel() — for form fields with associated labels
• getByText() — for elements identified by their visible text
• getByPlaceholder() — for inputs with placeholder text
• getByTestId() — when data-testid attributes are present
• CSS selectors — only as a last resort; avoid if any stable alternative exists
• Never use XPath unless absolutely necessary

3. Add assertions at every meaningful step. After each action, assert:

• A visible UI change (new element appears, text changes, URL changes)
• Not just "click and hope" — every interaction must have a follow-up assertion
• Use expect(locator).toBeVisible(), toHaveText(), toHaveURL(), toBeEnabled(), etc.

4. Structure the test file properly:

• Use test.describe to group related tests
• Use test.beforeEach for shared setup (navigation, login)
• Use test.afterEach or test.afterAll for cleanup if needed
• Give each test() a descriptive name starting with a verb: "shows...", "allows...", "prevents..."
• Keep each test focused on one behavior

5. Handle async correctly. Every page.click, page.fill, page.goto, and expect must be awaited. Never use setTimeout for waiting — use page.waitForSelector, page.waitForURL, or rely on Playwright's auto-waiting.

6. Add resilience where appropriate:

• For flaky elements (animations, lazy-loaded content), use expect(locator).toBeVisible({ timeout: 5000 })
• For network-dependent tests, consider page.waitForResponse() or mock the network with page.route()
• Avoid hard-coded page.waitForTimeout() sleeps — use condition-based waits

7. Include a Page Object Model class if the flow spans multiple pages or the test is complex. Keep it in a separate pages/ subfolder.

8. Output the complete, runnable test file with all imports. Include a comment block at the top describing what the test suite covers.

Example

Input to Agent:

> "Use the Playwright Test Builder skill to write tests for our sign-up flow. The user goes to /register, fills in their name, email, and password, clicks 'Create Account', and should land on /dashboard with a welcome message."

Output from Agent:

> `typescript

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

>

> /**

> * Tests for the user registration flow.

> * Covers: form validation, successful account creation, post-signup redirect.

> */

>

> test.describe('Registration flow', () => {

> test.beforeEach(async ({ page }) => {

> await page.goto('/register');

> await expect(page).toHaveURL('/register');

> });

>

> test('shows the registration form', async ({ page }) => {

> await expect(page.getByRole('heading', { name: 'Create your account' })).toBeVisible();

> await expect(page.getByLabel('Full name')).toBeVisible();

> await expect(page.getByLabel('Email')).toBeVisible();

> await expect(page.getByLabel('Password')).toBeVisible();

> await expect(page.getByRole('button', { name: 'Create Account' })).toBeEnabled();

> });

>

> test('allows a new user to register and redirects to dashboard', async ({ page }) => {

> await page.getByLabel('Full name').fill('Jane Smith');

> await page.getByLabel('Email').fill('jane@example.com');

> await page.getByLabel('Password').fill('SecurePass123!');

>

> await page.getByRole('button', { name: 'Create Account' }).click();

>

> await expect(page).toHaveURL('/dashboard');

> await expect(page.getByText('Welcome, Jane')).toBeVisible();

> });

>

> test('shows a validation error when email is already taken', async ({ page }) => {

> await page.getByLabel('Full name').fill('Existing User');

> await page.getByLabel('Email').fill('existing@example.com');

> await page.getByLabel('Password').fill('SecurePass123!');

>

> await page.getByRole('button', { name: 'Create Account' }).click();

>

> await expect(page.getByRole('alert')).toContainText('already in use');

> await expect(page).toHaveURL('/register');

> });

>

> test('prevents submission when required fields are empty', async ({ page }) => {

> await page.getByRole('button', { name: 'Create Account' }).click();

>

> // Form should not navigate away

> await expect(page).toHaveURL('/register');

> await expect(page.getByLabel('Email')).toBeFocused();

> });

> });

> `