Archon 浏览器自动化指南用 playwright-cli run-code 执行任意 Playwright 代码【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本指南讲解 Archon 仓库内置的playwright-cli技能中run-code命令的完整用法。当 CLI 内置命令click、fill、goto等无法覆盖你的高级浏览器自动化场景时run-code允许你直接执行任意 Playwright 代码用于地理位置模拟、权限授予、媒体仿真、跨页面数据抓取等复杂任务。读完本文你将掌握run-code的语法约束、常用 API 组合以及从登录到数据采集的完整实战方案。run-code 是什么CLI 内置命令之外的逃生舱playwright-cli是 Archon 仓库中随.claude/skills/分发的浏览器自动化技能定义见 SKILL.md它把常见操作封装成了open、goto、click、fill、snapshot等命令并支持--raw输出与管道组合。但真实网页场景无穷无尽——动态渲染、权限弹窗、文件下载、iframe 嵌套、剪贴板读写……这些需求无法靠固定命令穷举。run-code就是为此设计的通用通道它把一段 Playwright 代码字符串交给 CLI 执行让你在保持 CLI 会话上下文同一个浏览器实例、同一个 Page 对象的前提下自由调用 Playwright 的全部 API。这与本技能其他参考文档如 storage-state.md 中高级多条 Cookie 操作请用 run-code、request-mocking.md 中的网络拦截形成互补——凡是 CLI 没有直接命令的复杂操作都收敛到run-code。语法与执行约束基础语法run-code接受一段以page为参数的 async 箭头函数CLI 会在内部将其包裹在(...)中求值并调用playwright-cli run-code async page { // 你的 Playwright 代码 // 通过 page.context() 访问浏览器上下文操作 }从文件加载代码较长时可写入文件用--filename参数加载playwright-cli run-code --filename./my-script.js关键约束代码必须是一个单一函数表达式single function expression不能是语句序列会被包裹在(...)中求值因此不支持import/export/require语法——依赖的 API 全部来自 Playwright 全局可用对象page、page.context()等函数默认接收page参数所有浏览器上下文操作通过page.context()获取 BrowserContext 实例。提示在 CLI 参数中传入多行代码时注意 shell 的引号转义在 Windows 的cmd.exe/PowerShell 中如代码含等特殊字符需按 SKILL.md 的说明转义。地理位置模拟Geolocation需要测试定位类应用地图、门店搜索、地区化内容时先用grantPermissions授予geolocation权限再调用setGeolocation设置经纬度# 授予地理位置权限并设置位置旧金山 playwright-cli run-code async page { await page.context().grantPermissions([geolocation]); await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 }); } # 设置为伦敦 playwright-cli run-code async page { await page.context().grantPermissions([geolocation]); await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 }); } # 清除地理位置覆盖 playwright-cli run-code async page { await page.context().clearPermissions(); }注意clearPermissions()会清空全部已授予的权限如果只需要移除地理位置覆盖而保留其他权限可重新只授予所需权限集合。该能力在 SKILL.md 的 DevTools 一节中也有对应示例grantPermissions([geolocation])是位置敏感型功能回归测试的标准做法。浏览器权限授予Permissions批量授予多个权限playwright-cli run-code async page { await page.context().grantPermissions([ geolocation, notifications, camera, microphone ]); }针对特定源Origin授予权限权限通常按 origin 隔离测试第三方嵌入内容时可限定范围playwright-cli run-code async page { await page.context().grantPermissions([clipboard-read], { origin: https://example.com }); }授予后会弹出系统权限提示的网站通知、摄像头、麦克风、地理位置、剪贴板等都可以用这一模式静默授权避免自动化流程被原生弹窗卡死。媒体仿真Media Emulation无需真机即可验证深色模式、减少动效、打印样式等响应式表现# 模拟深色配色 playwright-cli run-code async page { await page.emulateMedia({ colorScheme: dark }); } # 模拟浅色配色 playwright-cli run-code async page { await page.emulateMedia({ colorScheme: light }); } # 模拟减少动效reduced motion无障碍测试常用 playwright-cli run-code async page { await page.emulateMedia({ reducedMotion: reduce }); } # 模拟打印媒体类型 playwright-cli run-code async page { await page.emulateMedia({ media: print }); }emulateMedia的media选项支持screen/print结合playwright-cli pdf --filenamepage.pdf见 SKILL.md 的 Save as 一节可以完整走通打印样式验证 → PDF 导出的链路。等待策略Wait StrategiesSPA 页面渲染时机多变正确等待是稳定性的关键# 等待网络空闲 playwright-cli run-code async page { await page.waitForLoadState(networkidle); } # 等待某个元素消失如 loading 指示器 playwright-cli run-code async page { await page.locator(.loading).waitFor({ state: hidden }); } # 等待函数返回 true如应用状态就绪标记 playwright-cli run-code async page { await page.waitForFunction(() window.appReady true); } # 带超时等待默认 30 秒这里显式给 10 秒 playwright-cli run-code async page { await page.locator(.result).waitFor({ timeout: 10000 }); }实战建议优先用waitForFunction等待业务就绪标志如window.appReady而非固定setTimeout元素等待时显式设置timeout可以避免慢速环境下的误报超时。Frames 与 Iframes嵌套页面广告位、第三方支付、OAuth 弹窗 iframe需要切换 frame 上下文# 进入 iframe 内部操作 playwright-cli run-code async page { const frame page.locator(iframe#my-iframe).contentFrame(); await frame.locator(button).click(); } # 列出页面所有 frame 的 URL playwright-cli run-code async page { const frames page.frames(); return frames.map(f f.url()); }第二个示例很适合自动化排查页面里有几个 iframe、各来自哪个域名返回值可以直接被 CLI 展示配合--raw还能喂给其他工具做断言。文件下载处理下载类功能导出报表、下载合同用事件驱动的方式处理playwright-cli run-code async page { const downloadPromise page.waitForEvent(download); await page.getByRole(link, { name: Download }).click(); const download await downloadPromise; await download.saveAs(./downloaded-file.pdf); return download.suggestedFilename(); }要点必须先注册waitForEvent(download)再触发点击避免竞态saveAs把文件保存到本地工作目录suggestedFilename()返回服务器建议的文件名适合作为返回值做后续校验。剪贴板读写# 读取剪贴板需要 clipboard-read 权限 playwright-cli run-code async page { await page.context().grantPermissions([clipboard-read]); return await page.evaluate(() navigator.clipboard.readText()); } # 写入剪贴板 playwright-cli run-code async page { await page.evaluate(text navigator.clipboard.writeText(text), Hello clipboard!); }剪贴板权限同样属于 浏览器权限授予 一节所说的 origin 限定权限若页面运行在https上下文之外navigator.clipboard可能不可用需结合实际情况评估。页面信息获取快速获取当前页面状态用于断言或日志# 获取页面标题 playwright-cli run-code async page { return await page.title(); } # 获取当前 URL playwright-cli run-code async page { return page.url(); } # 获取页面完整 HTML playwright-cli run-code async page { return await page.content(); } # 获取视口尺寸 playwright-cli run-code async page { return page.viewportSize(); }这几个示例返回值简洁特别适合配合 SKILL.md 中的--raw选项使用例如playwright-cli --raw run-code async page page.url()把 URL 直接喂给管道中的下一个命令。在页面中执行 JavaScriptpage.evaluateevaluate是run-code里最常用的 API可以在页面上下文中运行任意脚本并取回结果# 执行 JS 并返回对象 playwright-cli run-code async page { return await page.evaluate(() { return { userAgent: navigator.userAgent, language: navigator.language, cookiesEnabled: navigator.cookieEnabled }; }); } # 向 evaluate 传参第二参数会作为函数入参传入 playwright-cli run-code async page { const multiplier 5; return await page.evaluate(m document.querySelectorAll(li).length * m, multiplier); }注意evaluate的序列化边界传参和返回值都必须是可序列化的值JSON 兼容类型不能传递 DOM 元素或函数引用。run-code所在 CLI 作用域的变量如multiplier可以自由引用但会作为参数显式传入页面上下文。错误处理try-catch 容错页面元素可能因条件渲染而不存在用 try-catch 把失败变成可控结果playwright-cli run-code async page { try { await page.getByRole(button, { name: Submit }).click({ timeout: 1000 }); return clicked; } catch (e) { return element not found; } }这种探测式写法非常适合做分支逻辑按钮存在则点击、不存在则返回标记调用方再根据返回值决定后续流程。超时时间{ timeout: 1000 }让探测快速失败而不是等待默认 30 秒。复杂工作流实战登录并保存会话状态登录后把 storage state 存成文件后续会话直接复用与 storage-state.md 的state-save/state-load配合playwright-cli run-code async page { await page.goto(https://example.com/login); await page.getByRole(textbox, { name: Email }).fill(userexample.com); await page.getByRole(textbox, { name: Password }).fill(secret); await page.getByRole(button, { name: Sign in }).click(); await page.waitForURL(**/dashboard); await page.context().storageState({ path: auth.json }); return Login successful; }要点waitForURL(**/dashboard)用 glob 匹配跳转后的 URL避免等待固定地址造成偶发失败storageState写入的auth.json可供playwright-cli state-load auth.json在后续新会话中恢复实现一次登录、处处复用。请遵循 storage-state.md 的安全建议包含认证令牌的状态文件不要提交进版本库建议加入.gitignore并在自动化结束后删除。跨多页抓取数据playwright-cli run-code async page { const results []; for (let i 1; i 3; i) { await page.goto(\https://example.com/page/\${i}\); const items await page.locator(.item).allTextContents(); results.push(...items); } return results; }模板字符串模板字面量中的${i}在 shell 双引号内可能被 shell 展开CLI 使用反引号包裹以保证安全。返回的results数组可直接被 CLI 展示对大规模抓取建议每次goto之间结合上文等待策略中的waitForLoadState(networkidle)确保渲染完成。小结run-code 在 Archon 技能体系中的定位在 Archon 的浏览器自动化技能体系.claude/skills/playwright-cli/SKILL.md中run-code是最后手段也是最强手段固定命令负责高频操作与可读性run-code负责无限扩展。它与本技能其余参考文档——playwright-tests.md测试运行调试、request-mocking.md网络拦截、storage-state.md存储状态、tracing.md追踪——共同覆盖了现代 Web 自动化从权限、定位、等待、媒体到下载、存储、网络的完整场景。掌握本文的代码模式后你可以把任意 Playwright 脚本迁移为run-code命令让浏览器自动化真正指哪打哪。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考