wdio-session 是 WebdriverIO 提供的命令行工具，核心用途是让一个 WebdriverIO 会话在多条短 shell 命令之间持续存活，从而在真实浏览器、移动应用或桌面应用上观察和操作 UI、验证改动，并把已经跑通的步骤转成测试。若问题只涉及 HTTP API，资料建议改用 curl 或 fetch。
主要能力
- 打开会话：如 npx wdio session open chrome https://example.com，浏览器默认无头运行，open 会打印页面的可交互元素，可直接操作；也支持 firefox、edge、safari、android、ios、electron <app> 等。
- 基于引用操作元素：元素以类似 button "Add to cart" [ref=e3] 的形式展示，引用在元素存在期间保持有效。
- 动作反馈：每个动作会报告发生的变化，包括新增或变化的行及其引用（如状态 "Saved"），或导航后的新页面元素，通常无需单独快照。
- 链式执行：可用 && 在一次 shell 调用中串联多步，失败即中断；但展示结果的步骤建议单独调用。
- 大页面处理：find <text> 只打印匹配部分并滚动到可见位置；长快照用 --offset <line> 分页读取；read 提取文章文本；snapshot --viewport 仅显示屏幕内内容（Web 上不更新 diff 基线，需先运行普通 snapshot 或 snapshot -i）。
- 无需 head、grep、sed、重定向或 sleep，输出可直接阅读；可用 find、snapshot --offset、wait 2000 代替。
- 回答前把页面停留在能证明结论的位置，屏幕内容即为证据；空闲时会话自动关闭，仅需重新开始时才运行 close。
动作示例（资料所列）
- 查看：snapshot -i、snapshot、find "Add to cart"、read、screenshot
- 点击：click e3、click e3 --double、hover e3、scroll down、scroll e3
- 文本：fill e2 Ada Lovelace（替换）、type e2 more（追加）、press Enter、press ArrowRight --times 5
- 取值：fill e4 65 可设置滑块、日期和颜色
- 表单：select e4 Pro、check e5、uncheck e5、upload e6 ./file.pdf
- 读取：get text e9、get value e2、get url、get title、is visible e3
- 等待：wait e3、wait --text "Saved"、wait --url /done、wait 2000
- 导航：navigate https://…、back、reload、tabs、tabs switch 1
- 框架：iframe 内的引用可直接使用；frame e1 将快照限定到 iframe e1；frame top 返回
- 代码：exec -e 'console.log(await $("h1").getText())' 仅在动作失败或需要未列出的参数时，才运行 npx wdio session <action> --help。
使用方式
- 需要循环、条件与断言时使用 exec，在 Node 中运行，作用域内有 browser 和 $；页面内代码放入 await browser.execute(() => …)。较长的代码可通过 stdin 传入。
- 遵循 WebdriverIO v10 规则：命令始终 await；$ 只返回一个元素，匹配多个会抛 StrictSelectorError；代码用单引号包裹，避免 shell 执行 $(…)。
把步骤转成测试 每个动作会打印其执行的 WebdriverIO 代码（→ …），export 可将这些步骤写为 spec，例如 npx wdio session export --out test/specs/cart.e2e.ts，再用 npx wdio run wdio.conf.ts --spec test/specs/cart.e2e.ts 运行。若还没有 wdio.conf.ts，可用 npm init wdio@latest . -- --yes --typescript --framework mocha --browsers chrome --reporters spec 初始化。
调试失败测试 可运行 npx wdio run wdio.conf.ts --debug=agent，再用 npx wdio session -s debug-0-0 snapshot -i 查看，最后 npx wdio session -s debug-0-0 resume 恢复。
限制与错误 退出码含义：1 表示动作或代码失败，2 表示用法错误，3 表示缺少依赖或凭据，4 表示没有该名称的会话。错误会在下一行打印提示，npx wdio session doctor 可检查机器环境。资料未提供收费、价格及平台支持范围之外的更多信息。