playwright by oakoss/agent-skills
npx skills add https://github.com/oakoss/agent-skills --skill playwrightPlaywright 是一个浏览器自动化框架,支持 Node.js 和 Python,通过单一 API 即可操作 Chromium、Firefox 和 WebKit。它提供自动等待、面向 Web 的断言和完整的测试隔离,以实现可靠的端到端测试。
使用场景: 浏览器自动化、网络爬虫、截图/PDF 生成、API 测试、配置 Playwright Test、排查 Playwright 错误、隐身模式和反机器人绕过。
不适用场景: 简单的 HTTP 请求(使用 fetch)、单元测试(使用 Vitest/Jest)、大规模无服务器爬虫(考虑 Cloudflare Browser Rendering)。对于端到端测试架构(页面对象模型、CI 分片、测试组织、身份验证模式),请使用 e2e-testing 技能。
| 模式 | API / 配置 | 关键点 |
|---|---|---|
| 基础测试 | test('name', async ({ page }) => {}) | 自动等待、面向 Web 的断言、测试隔离 |
| 定位器 | page.getByRole() / |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
page.locator()| 优先使用角色/标签/文本选择器,而非 CSS 选择器 |
| 断言 | expect(locator).toBeVisible() | 自动重试、可配置超时 |
| API 测试 | request 夹具 / apiRequestContext | 发送 HTTP 请求,验证响应 |
| ARIA 快照 | expect(locator).toMatchAriaSnapshot() | 通过 YAML 验证无障碍树结构 |
| 类断言 | expect(locator).toContainClass('active') | 匹配单个 CSS 类名 (v1.52+) |
| 可见性过滤器 | locator.filter({ visible: true }) | 仅匹配可见元素 (v1.51+) |
| 测试步骤 | test.step('name', async (step) => {}) | 超时、跳过和附件 (v1.50+) |
| 隐身模式 | playwright-extra + 隐身插件 | 修补 20 多个检测向量 |
| 身份验证会话 | context.cookies() + addCookies() | 保存/恢复 cookies 和 IndexedDB 以实现持久化 |
| 截图 | page.screenshot({ fullPage: true }) | 首先等待关键元素加载 |
| PDF 生成 | page.pdf({ format: 'A4' }) | 仅限 Chromium,设置 printBackground: true |
| 时钟 API | page.clock | 在测试中冻结、快进或模拟时间 |
| 无障碍断言 | toHaveAccessibleName, toHaveRole | 无需 axe-core 依赖的原生断言 |
| 视口断言 | expect(locator).toBeInViewport() | 断言元素在可见视口内 |
| 仅运行变更的测试 | --only-changed=$GITHUB_BASE_REF | 仅运行自基础分支以来发生变更的测试文件 |
| Docker | mcr.microsoft.com/playwright:v1.58.2-noble | 使用 --init --ipc=host 标志 |
| 调试方法 | page.consoleMessages() / page.requests() (v1.56+) | 无需事件监听器 |
| 速度面板 | HTML 报告器 (v1.57+) | 识别慢速测试和瓶颈 |
| Playwright 代理 | npx playwright init-agents | 用于 LLM 驱动测试的规划器、生成器、修复器 |
| 不稳定测试检测 | --fail-on-flaky-tests (v1.50+) | CI 中遇到不稳定测试时退出码为 1 |
| 修改实时响应 | route.fetch() + route.fulfill() | 拦截真实响应,调整 JSON,然后返回 |
| 软断言 | expect.soft(locator) | 失败时不停止测试,最后报告所有结果 |
| 重试块 | expect(async () => {}).toPass() | 默认超时为 0(永久)—— 务必设置一个 |
| 自定义匹配器 | expect.extend() / mergeExpects() | 定义或组合自定义断言方法 |
| 可操作性矩阵 | 每个操作的自动等待检查 | click: 全部 5 项检查, fill: 3 项, focus/blur: 无 |
| 测试修饰符 | test.fixme() / test.fail() / test.slow() | fixme=跳过+追踪, fail=断言失败, slow=3倍 |
| 并行模式 | test.describe.configure({ mode: 'serial' }) | serial, parallel, 或每个 describe 块的默认值 |
| 清理项目 | 在 setup 项目上设置 teardown 选项 | 在所有依赖项完成后自动清理 |
| 错误 | 正确模式 |
|---|---|
| 使用 CSS 选择器而非角色选择器 | 优先使用 getByRole、getByLabel、getByText 以提高健壮性 |
| 未关闭浏览器 | 始终在 finally 块中执行 await browser.close() |
使用 setTimeout 进行等待 | 使用定位器自动等待或 waitForLoadState |
CI 代码中遗留 page.pause() | 使用 if (!process.env.CI) 进行保护 —— 否则会导致 CI 无限期挂起 |
| 点击前未等待 | 使用内置自动等待的 locator().click() |
| 测试间共享状态 | 每个测试通过夹具获得全新的上下文 |
| 测试实现细节 | 断言用户可见的行为,而非 DOM 结构 |
| 为动态内容使用硬编码等待 | 等待选择器出现或内容稳定 |
断言缺少 await | 所有 expect() 断言都返回 Promise —— 必须使用 await |
| 所有爬虫使用相同用户代理 | 大规模爬虫时轮换用户代理 |
对时间相关测试使用 setTimeout | 使用 page.clock API 冻结/快进时间 |
| 为简单的无障碍检查安装 axe-core | 使用原生 toHaveAccessibleName/toHaveRole 断言 |
使用 toPass() 时未指定显式超时 | 始终传递 { timeout: 10_000 } —— 默认为 0(永久) |
Service worker 静默阻塞 page.route() | 使用 MSW 时,在上下文配置中设置 serviceWorkers: 'block' |
对自动完成/防抖输入使用 fill() | 使用 pressSequentially() 并可选延迟以实现逐按键处理 |
storageState 丢失 sessionStorage | storageState 仅保存 cookies + localStorage —— 通过 addInitScript() 注入 sessionStorage |
Explore 代理Task 代理code-reviewer 代理对于端到端测试架构、页面对象模型模式、CI 分片策略、身份验证流程、视觉回归工作流或测试组织,请使用
e2e-testing技能。
每周安装次数
131
代码仓库
GitHub 星标数
5
首次出现
2026年2月20日
安全审计
安装于
kimi-cli129
gemini-cli129
amp129
github-copilot129
codex129
opencode129
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.
| 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 |
| 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 |
Explore agentTask agentcode-reviewer agentFor E2E test architecture, Page Object Model patterns, CI sharding strategies, authentication flows, visual regression workflows, or test organization, use the
e2e-testingskill.
Weekly Installs
131
Repository
GitHub Stars
5
First Seen
Feb 20, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
kimi-cli129
gemini-cli129
amp129
github-copilot129
codex129
opencode129
Skills CLI 使用指南:AI Agent 技能包管理器安装与管理教程
40,000 周安装
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() |