Playwright CLI 使用指南 —— 现代浏览器自动化利器

Playwright CLI 使用指南 —— 现代浏览器自动化利器Playwright CLI 是微软推出的命令行浏览器自动化工具专为现代编码代理Coding Agents优化。它通过简洁的 CLI 命令暴露浏览器工作流相比 MCP 协议更加 Token 高效是开发调试、自动化测试、数据采集的利器。一、项目简介GitHub 仓库microsoft/playwright-cliPlaywright CLI 基于 Playwright 框架提供了一套完整的浏览器自动化命令行接口。其核心设计哲学是CLI 优先所有操作通过命令行完成适合与 AI 代理、脚本管道集成Snapshot 驱动通过页面快照获取元素引用ref无需手写选择器代码自动生成每次操作自动输出对应的 Playwright TypeScript 代码Token 高效避免将大型工具模式和冗长的可访问性树加载到模型上下文中二、安装方式环境要求项目要求Node.js18 或更高版本包管理器npm / npx编码代理可选Claude Code、GitHub Copilot 等全局安装推荐npminstall-gplaywright/clilatest playwright-cli--help本地使用无需安装npx --no-install playwright-cli--version# 之后所有命令用 npx playwright-cli 代替 playwright-cli安装 Skills编码代理集成playwright-cliinstall--skills安装浏览器引擎npx playwrightinstall三、浏览器支持浏览器命令参数说明Chromium默认--browserchromium最稳定推荐日常使用Chrome--browserchrome需系统安装 ChromeMicrosoft Edge--browsermsedge需系统安装 EdgeFirefox--browserfirefox独立引擎适合跨浏览器测试WebKit--browserwebkitSafari 内核适合 macOS/iOS 兼容性测试# 使用 Firefox 打开playwright-cliopen--browserfirefox https://example.com# 使用 Edge 打开playwright-cliopen--browsermsedge https://example.com四、运行模式无头模式默认浏览器在后台运行不显示界面适合服务器环境和 CI/CD。playwright-cliopenhttps://example.com有头模式–headed显示真实浏览器窗口适合调试和演示。playwright-cliopenhttps://example.com--headed持久化模式–persistent默认情况下浏览器配置文件保存在内存中关闭即销毁。使用--persistent将配置持久化到磁盘。# 自动持久化到默认位置playwright-cliopenhttps://example.com--persistent# 指定自定义配置目录playwright-cliopenhttps://example.com--profile/path/to/profile组合使用playwright-cliopenhttps://example.com--headed--persistent五、核心命令详解5.1 浏览器控制playwright-cliopen[url]# 打开浏览器可选导航到 URLplaywright-cli close# 关闭当前浏览器playwright-cli close-all# 关闭所有浏览器playwright-cli kill-all# 强制终止所有浏览器进程playwright-cli delete-data# 删除用户数据playwright-cli list# 列出所有会话5.2 页面导航playwright-cli gotourl# 导航到 URLplaywright-cli go-back# 后退playwright-cli go-forward# 前进playwright-cli reload# 刷新页面5.3 元素交互playwright-cli snapshot# 获取页面快照获取元素引用playwright-cli clickref# 点击元素playwright-cli dblclickref# 双击元素playwright-cli fillreftext# 填充文本playwright-cli fill e5usermail.com--submit# 填充并提交playwright-clitypetext# 逐字符输入playwright-cli hoverref# 悬停playwright-cliselectrefvalue# 下拉选择playwright-cli checkref# 勾选复选框playwright-cli uncheckref# 取消勾选playwright-cli dragref1ref2# 拖拽playwright-cli uploadfile# 上传文件5.4 元素定位方式Playwright CLI 支持三种元素定位方式# 1. 通过 Snapshot 中的 ref推荐playwright-cli snapshot# 获取 e1, e2, e3... 引用playwright-cli click e15# 2. CSS 选择器playwright-cli click#main button.submit# 3. Playwright Locatorplaywright-cli clickgetByRole(button, { name: Submit })playwright-cli clickgetByTestId(submit-button)5.5 JavaScript 执行# 执行 JS 表达式playwright-clievaldocument.title# 对元素执行 JSplaywright-clievalel el.textContente5 playwright-clievalel el.ide55.6 键盘操作playwright-cli press Enter# 按键playwright-cli press ArrowDown playwright-cli keydown Shift# 按住playwright-cli keyup Shift# 释放5.7 鼠标操作playwright-cli mousemove150300# 移动到坐标playwright-cli mousedown# 按下支持 left/right/middleplaywright-cli mouseup# 释放playwright-cli mousewheel0100# 滚轮5.8 截图与 PDFplaywright-cli screenshot# 截取视口playwright-cli screenshot e5# 截取元素playwright-cli screenshot--filenamepage.png# 保存到文件playwright-cli pdf--filenamepage.pdf# 导出 PDF六、标签页管理playwright-cli tab-list# 列出所有标签页playwright-cli tab-new# 新建标签页playwright-cli tab-new https://example.com/page# 在新标签页打开 URLplaywright-cli tab-close# 关闭当前标签页playwright-cli tab-close2# 关闭指定索引标签页playwright-cli tab-select0# 切换到指定标签页七、存储管理Cookie 操作playwright-cli cookie-list# 列出所有 Cookieplaywright-cli cookie-list--domainexample.com# 按域名筛选playwright-cli cookie-get session_id# 获取指定 Cookieplaywright-cli cookie-set session_id abc123# 设置 Cookieplaywright-cli cookie-set session_id abc123--domainexample.com--httpOnly--secureplaywright-cli cookie-delete session_id# 删除 Cookieplaywright-cli cookie-clear# 清除所有 CookieLocalStorage / SessionStorageplaywright-cli localstorage-list playwright-cli localstorage-get theme playwright-cli localstorage-set theme dark playwright-cli localstorage-delete theme playwright-cli localstorage-clear playwright-cli sessionstorage-list playwright-cli sessionstorage-get step playwright-cli sessionstorage-set step3playwright-cli sessionstorage-delete step playwright-cli sessionstorage-clear状态保存与加载playwright-cli state-save auth.json# 保存完整存储状态playwright-cli state-load auth.json# 加载存储状态八、网络请求拦截Mock基础 Mock# 模拟 404playwright-cli route**/*.jpg--status404# 返回 JSONplaywright-cli routehttps://api.example.com/**--body{mock: true}--content-typeapplication/json# 添加自定义 Headerplaywright-cli route**/api/data--body{ok:true}--headerX-Custom: value# 移除请求头playwright-cli route**/*--remove-headercookie,authorization# 管理路由playwright-cli route-list playwright-cli unroute**/*.jpgplaywright-cli unroute# 移除所有路由高级 Mock通过 run-code# 条件响应playwright-cli run-codeasync page { await page.route(**/api/login, route { const body route.request().postDataJSON(); if (body.username admin) { route.fulfill({ body: JSON.stringify({ token: mock-token }) }); } else { route.fulfill({ status: 401, body: JSON.stringify({ error: Invalid }) }); } }); }# 模拟网络故障playwright-cli run-codeasync page { await page.route(**/api/offline, route route.abort(internetdisconnected)); }# 延迟响应playwright-cli run-codeasync page { await page.route(**/api/slow, async route { await new Promise(r setTimeout(r, 3000)); route.fulfill({ body: JSON.stringify({ data: loaded }) }); }); }九、调试与性能分析控制台与网络playwright-cli console# 查看控制台消息playwright-cli console warning# 仅查看警告playwright-cli network# 查看网络请求追踪Tracingplaywright-cli tracing-start# 开始追踪# ... 执行操作 ...playwright-cli tracing-stop# 停止并保存追踪文件视频录制playwright-cli video-start video.webm# 开始录制playwright-cli video-chapterChapter--descriptionDetails--duration2000# 添加章节标记playwright-cli video-stop# 停止录制十、会话管理命名会话每个会话拥有独立的 Cookie、Storage、缓存和历史记录。# 创建命名会话playwright-cli-sauthopenhttps://app.example.com/login playwright-cli-spublicopenhttps://example.com# 操作指定会话playwright-cli-sauth fill e1userexample.complaywright-cli-spublic snapshot# 列出所有会话playwright-cli list环境变量exportPLAYWRIGHT_CLI_SESSIONmysessionplaywright-cliopenexample.com# 自动使用 mysession十一、–raw 模式管道输出--raw选项剥离页面状态、生成代码和快照部分只返回结果值方便管道处理。# 提取页面标题耗时playwright-cli--rawevalJSON.stringify(performance.timing)|jq.loadEventEnd - .navigationStart# 导出所有链接playwright-cli--rawevalJSON.stringify([...document.querySelectorAll(a)].map(a a.href))links.json# 快照对比playwright-cli--rawsnapshotbefore.yml playwright-cli click e5 playwright-cli--rawsnapshotafter.ymldiffbefore.yml after.yml十二、配置文件默认配置路径.playwright/cli.config.json{browser:{browserName:chromium,isolated:true,launchOptions:{headless:true},contextOptions:{}},outputDir:.playwright-cli,console:{level:info},timeouts:{action:5000,navigation:60000},testIdAttribute:data-testid}使用配置文件playwright-cliopen--configmy-config.json十三、使用场景总结场景说明Web 自动化测试自动生成 Playwright 测试代码交互式探索后一键生成调试 Playwright 测试通过--debugcli暂停测试用 CLI 探索页面状态数据采集/爬虫多会话并发采集支持 Cookie/Storage 管理API Mock 测试前后端联调时拦截和模拟 API 响应AI 编码代理集成为 Claude Code、GitHub Copilot 等代理提供浏览器操作能力UI 截图/录制批量截图、PDF 导出、视频录制A/B 测试多会话对比不同变体的用户体验十四、实用示例表单提交playwright-cliopenhttps://example.com/form playwright-cli snapshot playwright-cli fill e1userexample.complaywright-cli fill e2password123playwright-cli click e3 playwright-cli close多标签页工作流playwright-cliopenhttps://example.com playwright-cli tab-new https://example.com/other playwright-cli tab-list playwright-cli tab-select0playwright-cli snapshot playwright-cli close并发抓取playwright-cli-ssite1openhttps://site1.complaywright-cli-ssite2openhttps://site2.complaywright-cli-ssite3openhttps://site3.comwaitplaywright-cli-ssite1 snapshot playwright-cli-ssite2 snapshot playwright-cli-ssite3 snapshot playwright-cli close-all十五、最佳实践使用语义化会话名-sgithub-auth优于-ss1用完即关闭养成playwright-cli close的习惯避免资源泄漏先 snapshot 再操作理解页面结构后再进行交互定期清理数据使用delete-data释放磁盘空间优先使用 ref 定位比 CSS 选择器更稳定善用 --raw 模式管道输出与其他工具协作参考资料GitHub 仓库https://github.com/microsoft/playwright-cliPlaywright 官方文档https://playwright.devnpm 包https://www.npmjs.com/package/playwright/cli本文使用playwright-cli --headed --persistent模式访问 GitHub 官方仓库结合官方文档和 Skill 文档整理而成。