AI 技能浏览器控制GUI 自动化测试【免费下载链接】playwright-cliCLI for common Playwright actions. Record and generate Playwright code, inspect selectors and take screenshots.项目地址https://gitcode.com/GitHub_Trending/pl/playwright-cli点击查看免费下载本篇指南聚焦 playwright-cli 的run-code命令——它允许你在当前浏览器会话中执行任意 Playwright 代码用来处理 CLI 内置命令覆盖不到的高级场景如精确的地理位置模拟、特定源权限授权、跨页面数据抓取等。读完本文你将掌握run-code的调用语法、代码运行环境的边界约束并能用它与 BrowserContext、Page 的完整 API 组合出登录态保存、iframe 操作、下载处理等真实可用的自动化方案。为什么需要 run-codeplaywright-cli 提供了一套面向 Agent 和命令行操作的高度封装命令goto、click、fill、snapshot、route等足以覆盖日常的浏览器交互。但当需求超出这些命令的表达范围时——比如一次性授予多种浏览器权限、等待一个自定义的 JavaScript 条件成立、或者在一个循环里遍历多个页面——逐条调用 CLI 命令会变得低效甚至不可能。此时run-code就是出口。它把 Playwright 的完整编程能力注入命令行你写的回调函数会直接拿到当前会话的page对象因此page.context()、page.locator()、page.evaluate()等全部 API 都可用。这一点在该技能手册中也有明确定位run-code位于 DevTools 命令分类之下见 skills/playwright-cli/SKILL.md并在 README.md 中被描述为 run playwright code snippet / run playwright code from a file。基本语法与两种调用方式run-code接受一个单一的 async 函数表达式函数的第一个参数即当前页面的page对象playwright-cli run-code async page { // Your Playwright code here // Access page.context() for browser context operations }除了内联传入还可以把代码保存成文件后加载执行playwright-cli run-code --filename./my-script.js两种方式等价--filename更适合较长、需要复用的脚本——例如在录制视频时官方建议把关键操作写成脚本文件再通过run-code --filename执行见 skills/playwright-cli/references/video-recording.md。运行环境约束隔离上下文理解run-code的运行模型对写出不踩坑的脚本至关重要原文档明确了两条硬性规则代码必须是单个函数表达式它会被包裹在(...)中求值。因此像function foo() {}这样的命名声明、const fn async page {}这样的赋值语句都不能直接作为内联参数传入。运行在隔离上下文中而非完整的 Node.js 环境import/export/require语法均不支持require、process以及所有 Node.js 模块都不可用。不过一批常用的 Web 平台能力被刻意保留了下来可以直接使用定时器setTimeout、setInterval网络fetch数据URL、Buffer、crypto异步控制AbortController编码TextEncoder、TextDecoder这意味着在脚本内部你可以安全地使用fetch调用接口做数据预处理用URL解析地址或通过crypto.randomUUID()生成随机 ID——这些都是浏览器自动化中常见的需求。脚本返回的 Promise 会被run-code等待并输出为结果。从项目实现看run-code是 playwright-cli.js 入口命令体系的一部分该入口加载playwright-core的 CLI 客户端程序playwright-core/lib/tools/cli-client/program所有命令包括run-code都在 Playwright 的完整运行时之上执行所以代码中能用到的 API 范围与 Playwright 官方文档一致回调函数拿到的page也是当前会话中真实活动的页面。场景一地理位置Geolocation模拟测试地图、天气、本地生活类页面时经常需要把浏览器定位到某个城市。run-code可以同时完成权限授予与坐标设置两步# Grant geolocation permission and set location playwright-cli run-code async page { await page.context().grantPermissions([geolocation]); await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 }); } # Set location to London playwright-cli run-code async page { await page.context().grantPermissions([geolocation]); await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 }); } # Clear geolocation override playwright-cli run-code async page { await page.context().clearPermissions(); }要点grantPermissions([geolocation])必须在setGeolocation之前调用否则浏览器会因缺少权限而拿不到定位最后一个示例用clearPermissions()清除所有权限覆盖让页面恢复默认的权限询问行为。场景二权限Permissions精细控制除了地理位置浏览器上下文还支持摄像头、麦克风、通知、剪贴板等权限的批量授予# Grant multiple permissions playwright-cli run-code async page { await page.context().grantPermissions([ geolocation, notifications, camera, microphone ]); } # Grant permissions for specific origin playwright-cli run-code async page { await page.context().grantPermissions([clipboard-read], { origin: https://example.com }); }第二个示例演示了origin选项默认情况下权限作用于整个上下文传入origin后则只对指定站点生效。这在需要只允许 example.com 读取剪贴板其他站点照常询问的测试场景中非常有用。grantPermissions支持的权限名与浏览器 Permission API 一致如geolocation、notifications、camera、microphone、clipboard-read、clipboard-write等。场景三媒体仿真Media EmulationemulateMedia用来模拟 CSS 媒体特性是验证深色模式、打印样式、无障碍偏好时的利器# Emulate dark color scheme playwright-cli run-code async page { await page.emulateMedia({ colorScheme: dark }); } # Emulate light color scheme playwright-cli run-code async page { await page.emulateMedia({ colorScheme: light }); } # Emulate reduced motion playwright-cli run-code async page { await page.emulateMedia({ reducedMotion: reduce }); } # Emulate print media playwright-cli run-code async page { await page.emulateMedia({ media: print }); }emulateMedia的选项可以组合传入例如{ colorScheme: dark, reducedMotion: reduce }。如果你只需要单项仿真而不想写脚本playwright-cli 也提供了等价的专用命令如set-color-scheme dark、set-reduced-motion reduce、set-media print见 skills/playwright-cli/SKILL.md 的 Emulation 小节——run-code的价值在于可以自由组合与按条件动态切换。场景四等待策略Wait Strategies页面加载状态是自动化中最容易出错的一环run-code提供四种常用等待手段# Wait for network idle playwright-cli run-code async page { await page.waitForLoadState(networkidle); } # Wait for specific element playwright-cli run-code async page { await page.locator(.loading).waitFor({ state: hidden }); } # Wait for function to return true playwright-cli run-code async page { await page.waitForFunction(() window.appReady true); } # Wait with timeout playwright-cli run-code async page { await page.locator(.result).waitFor({ timeout: 10000 }); }waitForLoadState(networkidle)等待页面网络请求基本停歇注意单页应用或长连接页面可能永远达不到该状态需谨慎使用locator.waitFor({ state: hidden })等待某个元素变为隐藏常用于加载中转圈消失后再继续waitForFunction等待页面内 JS 表达式返回真值适合等待 SPA 应用挂载完成如window.appReadytimeout选项给等待加上限避免脚本无限挂起。场景五Frames 与 Iframes 操作内嵌 iframe 中的元素位于独立文档普通的 locator 匹配不到。run-code可以切换到 iframe 上下文操作# Work with iframe playwright-cli run-code async page { const frame page.locator(iframe#my-iframe).contentFrame(); await frame.locator(button).click(); } # Get all frames playwright-cli run-code async page { const frames page.frames(); return frames.map(f f.url()); }第二个示例遍历page.frames()返回所有 frame包括主框架的 URL可用于确认页面是否存在广告 iframe、第三方组件 iframe或者排查 frame 是否加载成功。场景六文件下载处理测试下载按钮时需要先注册下载事件监听再触发点击最后决定保存位置# Handle file download 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(); }这段代码展示了run-code的完整返回值链路先用waitForEvent(download)预注册事件点击触发下载拿到download对象后用saveAs(./downloaded-file.pdf)把文件保存到当前工作目录最后返回suggestedFilename()作为命令输出——你可以直接在终端看到下载的文件名。场景七剪贴板读写剪贴板权限默认不授予因此读写前先要授权# Read clipboard (requires permission) playwright-cli run-code async page { await page.context().grantPermissions([clipboard-read]); return await page.evaluate(() navigator.clipboard.readText()); } # Write to clipboard playwright-cli run-code async page { await page.evaluate(text navigator.clipboard.writeText(text), Hello clipboard!); }注意读取剪贴板readText在非用户手势场景下受浏览器安全策略限制需先通过grantPermissions([clipboard-read])授权而写入writeText通过evaluate的第二个参数把值传入页面函数这也是page.evaluate传递参数的规范写法。场景八获取页面信息快速探查当前页面状态# Get page title playwright-cli run-code async page { return await page.title(); } # Get current URL playwright-cli run-code async page { return page.url(); } # Get page content playwright-cli run-code async page { return await page.content(); } # Get viewport size playwright-cli run-code async page { return page.viewportSize(); }这些返回值都会作为命令结果输出。结合全局--raw选项只输出结果值、剥离页面状态与快照部分可以把它接到其他命令行工具中做进一步处理例如playwright-cli --raw run-code async page page.title()场景九JavaScript 执行与参数传递在页面上下文中执行任意 JS并支持把外层变量传入页面# Execute JavaScript and return result playwright-cli run-code async page { return await page.evaluate(() { return { userAgent: navigator.userAgent, language: navigator.language, cookiesEnabled: navigator.cookieEnabled }; }); } # Pass arguments to evaluate playwright-cli run-code async page { const multiplier 5; return await page.evaluate(m document.querySelectorAll(li).length * m, multiplier); }page.evaluate的第一个参数是页面内执行的函数第二个参数起为传入该函数的参数。由于值会被序列化到页面中传入的参数必须是可序列化的字符串、数字、数组、普通对象等。场景十错误处理run-code支持标准的 try-catch让失败成为可控结果而不是命令报错# Try-catch in run-code playwright-cli run-code async page { try { await page.getByRole(button, { name: Submit }).click({ timeout: 1000 }); return clicked; } catch (e) { return element not found; } }这里对按钮点击设置了 1 秒超时找不到按钮时捕获异常并返回可读的字符串结果。这让按钮可能不存在这类场景可以优雅降级而不是中断整个会话。场景十一复杂工作流run-code的真正威力在于把多步操作压缩为一次调用。下面两个示例是典型的实战组合# Login and save state 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; } # Scrape data from multiple pages 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; }第一个示例完成了登录 → 等待跳转到 dashboard → 保存 storage state 到 auth.json的完整链路。保存的auth.json是 Playwright 标准的存储状态文件之后可以用playwright-cli state-load auth.json见 skills/playwright-cli/references/storage-state.md在后续会话中复用登录态免去重复登录。第二个示例在循环中访问多个分页并汇总文本内容返回的数组会作为命令输出呈现——这是一个轻量级的采集器雏形。与其他技能的配合run-code在技能库的其他主题中也被推荐为高级场景的解法请求 Mock 的进阶当route命令不足以表达复杂的拦截逻辑时可在run-code中用page.route()配合自定义回调做动态响应详见 skills/playwright-cli/references/request-mocking.md存储状态批量操作一次性添加多个 Cookie、批量设置 localStorage 值时直接写run-code脚本比多次调用 CLI 更高效见 skills/playwright-cli/references/storage-state.md视频录制录制演示视频时官方建议将操作整理为脚本文件后用playwright-cli run-code --filename your-script.js执行以获得稳定可复现的画面见 skills/playwright-cli/references/video-recording.md。实战建议与注意事项优先用 CLI 命令run-code 处理增量对于单步交互点击、填写、导航click、fill、goto等命令更简洁、输出更利于 Agent 理解run-code用在多步、循环、需要返回值或异常分支的场景。保持脚本单一函数、无依赖由于隔离上下文不支持require脚本应自包含需要共享逻辑时提前做成模板文件再--filename引用。善用返回值与--rawrun-code的返回值会进入命令输出配合--raw可以只取结果方便管道化处理或写入文件。注意等待与超时网络相关的等待networkidle对长连接页面可能永不满足对可能不存在的元素务必加timeout或 try-catch。环境要求项目要求 Node.js 18 及以上见 package.json。全局未安装时可先执行npx --no-install playwright --version检查本地版本或通过npm install -g playwright/clilatest安装后使用详见 README.md。结语run-code是 playwright-cli 从命令集合走向完整自动化平台的关键能力它以最小的语法成本把 Playwright 的 Page 与 BrowserContext 全部 API 开放给命令行与 Agent。掌握它之后无论是权限、媒体、地理位置这类环境仿真还是登录态复用、数据采集这类组合流程都只需一个函数表达式即可完成——这也是技能库中多个主题请求 Mock、存储状态、视频录制在面对复杂需求时不约而同指向它的原因。赞分享AI 技能浏览器控制GUI 自动化测试【免费下载链接】playwright-cliCLI for common Playwright actions. Record and generate Playwright code, inspect selectors and take screenshots.项目地址https://gitcode.com/GitHub_Trending/pl/playwright-cli点击查看免费下载相关推荐Playwright CLI run-code 深度实战在 playwright-cli 会话中执行任意 Playwright 代码Playwright CLI run code 深度实战在 playwright cli 会话中执行任意 Playwright 代码 run code 是 p测试开发工具浏览器控制VoltAgent 实战playwright-cli 浏览器会话管理Session Management完全指南VoltAgent 实战playwright cli 浏览器会话管理Session Management完全指南 本文以 VoltAgent 开源仓库中人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音VoltAgent 工作区技能实战使用 playwright-cli run-code 运行自定义 Playwright 代码VoltAgent 工作区技能实战使用 playwright cli run code 运行自定义 Playwright 代码 playwright cli人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇Crystal Grafast深度指南Operation Plan规划与执行引擎是如何工作的下一篇MobileNetV4 小型卷积模型代码实现解析深入理解timm库中的模型架构创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考