dotfiles/home/.config/opencode/skills/playwright-cli/SKILL.md

name, description

name

description

playwright-cli

Use when the user asks to test a web app in a real browser, automate browser clicks/form submissions, take screenshots of flows, verify a UI works end-to-end, or do end-to-end (E2E) testing. Triggers on keywords like "browser test", "E2E test", "click through", "playwright", "verify the flow", "screenshot the page". Installs and drives the Playwright CLI to let the agent act as a real browser user.

Playwright CLI — agent-driven browser testing

The agent should not say "looks good to me" about a UI it never opened. Use Playwright to actually click through the flow, fill forms, assert outcomes, and screenshot the result.

Install (first use)

If playwright is not on PATH, install it:

npm install -g @playwright/mcp@latest
npx playwright install --with-deps

npx playwright install downloads the browser binaries (chromium, firefox, webkit). --with-deps installs OS libraries they need (Linux only; on macOS it's a no-op for the deps portion).

Verify: npx playwright --version.

Core CLI commands

Task	Command
Scaffold a new test project	npm init playwright@latest (creates tests/, playwright.config.ts)
Run all tests	npx playwright test
Run one file	npx playwright test tests/login.spec.ts
Run by title grep	npx playwright test -g "logs in"
Run headed (see the browser)	npx playwright test --headed
Run with browser visible + slow	npx playwright test --headed --workers=1
UI mode (interactive watcher)	npx playwright test --ui
Trace viewer (post-mortem)	npx playwright show-trace trace.zip
Codegen a flow by clicking	npx playwright codegen <url>
Codegen to a file	npx playwright codegen <url> -o tests/flow.spec.ts
Screenshot a page	npx playwright screenshot --browser chromium <url> out.png
PDF a page	npx playwright pdf <url> out.pdf
Open a page in a real browser	npx playwright open <url>

When to use

• User says "test the login flow", "verify the checkout works", "click through and make sure nothing breaks"
• User asks to record a new E2E test from a manual flow → playwright codegen
• User wants a screenshot/PDF of a rendered page for verification
• After touching auth, forms, navigation, or anything with state, run the relevant spec instead of asserting "should work"

When NOT to use

• Unit testing component logic → use the project's existing unit test runner (vitest, jest, etc.)
• API/endpoint testing → use curl/httpie or the API test framework already in the repo
• Load testing → Playwright is functional, not perf; suggest k6 or similar

Writing tests (codegen first, edit second)

The fastest path to a working test is codegen, not hand-writing:

npx playwright codegen http://localhost:3000 -o tests/auth.spec.ts

Click through the flow in the browser that pops up; Playwright writes the spec live. Then edit the generated file to add assertions (expect(locator).toHaveText(...), expect(page).toHaveURL(...)) and clean up selectors (prefer getByRole, getByLabel over CSS).

Assertions quick reference

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

test('user can log in', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('user@example.com');
  await page.getByLabel('Password').fill('secret');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page).toHaveURL(/dashboard/);
  await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
});

Debugging a failing test

1. npx playwright test tests/x.spec.ts --headed --workers=1 — watch it run.
2. If still unclear, add --trace on then npx playwright show-trace trace.zip.
3. page.pause() in the spec drops into the Playwright Inspector (step through, try selectors live).

Source

Referenced in https://x.com/heyshruti7/status/2069083108092350823 — "Playwright CLI — your agent tests the browser itself. No more 'looks good to me.' It actually clicks through the flow."