playwright
Playwright browser automation API, web scraping, and tooling. Covers locator strategies, assertions, API testing, stealth mode, anti-bot bypass, authenticated sessions, screenshots/PDFs, Docker deployment, configuration, debugging, and MCP integration with AI agents. Prevents documented errors including CI timeout hangs, extension testing failures, and navigation issues. Use when automating browsers, scraping protected sites, bypassing bot detection, generating screenshots/PDFs, configuring Playwright Test, troubleshooting Playwright errors, or learning Playwright API patterns. For E2E test architecture, Page Object Models, CI sharding strategies, or test organization patterns, use the e2e-testing skill instead.
- Installs
- 453
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/oakoss/agent-skills --skill playwright- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads playwright automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Playwright
Overview
Playwright is a browser automation framework for Node.js and Python supporting Chromium, Firefox, and WebKit with a single API. It provides auto-waiting, web-first assertions, and full test isolation for reliable end-to-end testing.
When to use: Browser automation, web scraping, screenshot/PDF generation, API testing, configuring Playwright Test, troubleshooting Playwright errors, stealth mode and anti-bot bypass.
When NOT to use: Simple HTTP requests (use fetch), unit testing (use Vitest/Jest), serverless scraping at scale (consider Cloudflare Browser Rendering). For E2E test architecture (Page Object Models, CI sharding, test organization, authentication patterns), use the e2e-testing skill.
Quick Reference
| Pattern | API / Config | Key Points |
|---|---|---|
| Basic test | test('name', async ({ page }) => {}) | Auto-wait, web-first assertions, test isolation |
| Locator | page.getByRole() / page.locator() | Prefer role/label/text selectors over CSS |
| Assertion | expect(locator).toBeVisible() | Auto-retrying, configurable timeout |
| API testing | request fixture / apiRequestContext | Send HTTP requests, validate responses |
| Aria snapshot | expect(locator).toMatchAriaSnapshot() | Validate accessibility tree structure via YAML |
| Class assertion | expect(locator).toContainClass('active') | Match individual CSS class names (v1.52+) |
| Visible filter | locator.filter({ visible: true }) | Match only visible elements (v1.51+) |
| Test step | test.step('name', async (step) => {}) | Timeout, skip, and attachments (v1.50+) |
| Stealth mode | playwright-extra + stealth plugin | Patches 20+ detection vectors |
| Authenticated session | context.cookies() + addCookies() | Save/restore cookies and IndexedDB for persistence |
| Screenshot | page.screenshot({ fullPage: true }) | Wait for key elements to load first |
| PDF generation | page.pdf({ format: 'A4' }) | Chromium only, set printBackground: true |
| Clock API | page.clock | Freeze, fast-forward, or simulate time in tests |
| A11y assertions | toHaveAccessibleName, toHaveRole | Native assertions without axe-core dependency |
| Viewport assertion | expect(locator).toBeInViewport() | Assert element is within the visible viewport |
| Changed tests only | --only-changed=$GITHUB_BASE_REF | Run only test files changed since base branch |
| Docker | mcr.microsoft.com/playwright:v1.58.2-noble | Use --init --ipc=host flags |
| Debug methods | page.consoleMessages() / page.requests() (v1.56+) | No event listeners needed |
| Speedboard | HTML reporter (v1.57+) | Identifies slow tests and bottlenecks |
| Playwright Agents | npx playwright init-agents | Planner, generator, healer for LLM-driven testing |
| Flaky test detection | --fail-on-flaky-tests (v1.50+) | Exit code 1 on flaky tests in CI |
| Modify live responses | route.fetch() + route.fulfill() | Intercept real response, tweak JSON, return it |
| Soft assertions | expect.soft(locator) | Don't stop test on failure, report all at end |
| Retry block | expect(async () => {}).toPass() | Default timeout is 0 (forever) — always set one |
| Custom matchers | expect.extend() / mergeExpects() | Define or combine custom assertion methods |
| Actionability matrix | Per-action auto-wait checks | click: all 5 checks, fill: 3, focus/blur: none |
| Test modifiers | test.fixme() / test.fail() / test.slow() | fixme=skip+track, fail=assert failure, slow=3x |
| Parallel modes | test.describe.configure({ mode: 'serial' }) | serial, parallel, or default per-describe block |
| Teardown projects | teardown option on setup projects | Auto-cleanup after all dependents finish |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| Using CSS selectors over role selectors | Prefer getByRole, getByLabel, getByText for resilience |
| Not closing browser | Always await browser.close() in finally block |
Using setTimeout for waits | Use locator auto-wait or waitForLoadState |
page.pause() left in CI code | Guard with if (!process.env.CI) — hangs CI indefinitely |
| Clicking without waiting | Use locator().click() with built-in auto-wait |
| Shared state between tests | Each test gets fresh context via fixtures |
| Testing implementation details | Assert user-visible behavior, not DOM structure |
| Hardcoded waits for dynamic content | Wait for selector appearance or content stabilization |
Missing await on assertions | All expect() assertions return promises — must be awaited |
| Same user agent for all scraping | Rotate user agents for high-volume scraping |
Using setTimeout for time-dependent tests | Use page.clock API to freeze/fast-forward time |
| Installing axe-core for simple a11y checks | Use native toHaveAccessibleName/toHaveRole assertions |
Using toPass() without explicit timeout | Always pass { timeout: 10_000 } — default is 0 (forever) |
Service worker silently blocking page.route() | Set serviceWorkers: 'block' in context config when using MSW |
Using fill() for autocomplete/debounce inputs | Use pressSequentially() with optional delay for per-keystroke handling |
storageState losing sessionStorage | storageState only saves cookies + localStorage — inject sessionStorage via addInitScript() |
Delegation
- Selector troubleshooting: Use
Exploreagent - Test pattern review: Use
Taskagent - Code review: Delegate to
code-revieweragent
For E2E test architecture, Page Object Model patterns, CI sharding strategies, authentication flows, visual regression workflows, or test organization, use the
e2e-testingskill.
References
- Quick start and installation
- E2E testing patterns and assertions
- Selector strategies and best practices
- Configuration and Docker deployment
- Docker and CI
- Debug methods and performance analysis
- Common automation patterns
- Stealth mode and anti-bot bypass
- Known issues and solutions
- Site-specific blocking and bypasses
- Troubleshooting common problems
- Network testing, mocking, and API patterns
- Input patterns, actionability, and test modifiers
- Advanced assertions, polling, custom matchers, and annotations
- Advanced topics: MCP, AI agents, parallel contexts
FAQ
What does the playwright skill do?
Playwright browser automation API, web scraping, and tooling. Covers locator strategies, assertions, API testing, stealth mode, anti-bot bypass, authenticated sessions, screenshots/PDFs, Docker deployment, configuration, debugging, and MCP integration with AI agents. Prevents documented errors including CI timeout hangs, extension testing failures, and navigation issues. Use when automating browsers, scraping protected sites, bypassing bot detection, generating screenshots/PDFs, configuring Playwright Test, troubleshooting Playwright errors, or learning Playwright API patterns. For E2E test architecture, Page Object Models, CI sharding strategies, or test organization patterns, use the e2e-testing skill instead.
How do I install playwright?
Run npx skills add https://github.com/oakoss/agent-skills --skill playwright in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/playwright/ (personal) or .claude/skills/playwright/ (project).
Which AI agents can use playwright?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is playwright safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains playwright?
It is published by oakoss in oakoss/agent-skills. It has 453 recorded installs.
More from oakoss/agent-skills
ui-ux-polish
oakoss/agent-skills
Iterative UI/UX polishing workflow for web applications. Use when improving visual polish, refining desktop and mobile UX separately, running iterative enhancement cycles, applying design patterns like glassmorphism or bento grids, or auditing accessibility and WCAG compliance. Use for Stripe-level visual quality, responsive optimization, and design system alignment.
coolify
oakoss/agent-skills
Coolify self-hosted PaaS for deploying applications, databases, and services via REST API and Git integration. Covers API authentication, deployment triggers, build packs (Nixpacks, Dockerfile, Compose), CI/CD with GitHub Actions webhooks, environment management, and Traefik proxy configuration. Use when deploying apps to Coolify, triggering deployments via API, configuring build packs, setting up GitHub Actions CI/CD pipelines, managing environment variables, or troubleshooting deployment failures.
application-security
oakoss/agent-skills
Application security covering threat modeling (STRIDE), OWASP Top 10 (2025), OWASP API Security Top 10 (2023), secure coding review, authentication/authorization patterns, input validation, encryption, security headers, supply chain security, compliance (GDPR/HIPAA/SOC2/PCI-DSS), and security monitoring. Use when reviewing code for vulnerabilities, implementing auth patterns, securing APIs, configuring security headers, hardening supply chain, preventing injection attacks, or preparing for compliance audits.
find-skills
oakoss/agent-skills
Discovers and installs agent skills from the open ecosystem. Enriches search results with descriptions fetched from skills.sh. Use when a user asks "how do I do X", "find a skill for X", "is there a skill that can...", or wants to extend agent capabilities. Use for skill discovery, skill search, skill install, finding tools.
drizzle-orm
oakoss/agent-skills
Drizzle ORM for type-safe SQL with PostgreSQL, MySQL, and SQLite. Use when defining schemas, writing queries, managing relations, running migrations, or using drizzle-kit. Use for drizzle, orm, schema, query, migration, pgTable, relations, drizzle-kit, drizzle-zod.
brand-designer
oakoss/agent-skills
Creates cohesive brand identities including logos, color palettes, typography systems, and brand guidelines documents. Generates SVG logo components with variants, configures Tailwind color tokens, builds type scales, and produces social media and business card templates. Use when designing a logo, building a color palette, setting up typography systems, creating brand guidelines, generating social media templates, or organizing brand asset files. Use for branding, visual identity, logo design, brand guidelines, color systems.
Popular testing & qa skills
tdd
mattpocock/skills
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
grilling
mattpocock/skills
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
migrate-to-shoehorn
mattpocock/skills
Migrate test files from as type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace as in tests, or needs partial test data.
run-train
lllllllama/rigorpilot-skills
Rigor Train skill for deep learning research repositories. Use when a documented or selected training command should be run conservatively for startup verification, short-run verification, full kickoff, or resume, with command, config, seed, log, checkpoint, status, and metric evidence written to standardized trainoutputs/. Do not use for environment setup, exploratory sweeps, speculative idea implementation, or end-to-end orchestration.
test-driven-development
obra/superpowers
Use when implementing any feature or bugfix, before writing implementation code
finishing-a-development-branch
obra/superpowers
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work