mitao-su/dsh-playwright-cli

dsh-playwright-cli

DeepSeek Harness（DSH）host 插件：把 Playwright CLI 封装成 Agent 可一键调用的工具集 —— 探测版本、安装浏览器、跑测试、打开 HTML 报告，全程无需手敲 npx playwright ...。

- 运行面：host-only（无 client bundle，无 Web 依赖）。
- 执行缝：复用官方 shell 执行器（ctx.shell，与 bash/pwsh 工具同源），因此 sandbox 策略、DSH_* 环境变量、输出截断、超时/中止分类全部由组合提供。
- 分发：lib/ 已提交进 Git，安装不触发任何构建脚本，零交互。

工具

| 工具 | 作用 | 底层命令 |
|---|---|---|
| playwright_version | 探测目标项目里 CLI 是否可用并打印版本 | npx --no-install playwright --version |
| playwright_install | 安装浏览器（默认 chromium）；CLI 缺失且 autoInstallPackage 开启时先用 npm 脚手架 @playwright/test | npx --no-install playwright install [browsers...] |
| playwright_test | 运行测试套件，支持 --config/--project/--grep/--workers/--reporter/--headed/--trace/--retries/--list 等常用选项 | npx --no-install playwright test ... |
| playwright_show_report | 定位 HTML 报告：有 web server 时注册回环路由并返回 URL；否则返回文件绝对路径 | playwright-report/index.html 静态服务 |

所有命令默认在会话工作区（session cwd）中执行，非零退出报告而非报错，由模型自行判断下一步。

安装

要求：目标 profile 已挂载 shell 执行器（标准 web/headless 组合自带；DSH ≥ 0.1.0-rc.6）。

dsh plugin --profile web add github:mitao-su/dsh-playwright-cli

走 Git 分发：本仓库把构建产物 lib/ 提交进 Git，pnpm 不会执行任何 prepare 脚本，因此无需配置 allowBuilds。安装成功后重启目标 profile（dsh plugin 会自动把包加入 dsh.profile.bundles）。

受限网络备选（github: 依赖需要本机 git 可访问 GitHub）：也可直接用 GitHub tarball URL 安装，效果相同：

dsh plugin --profile web add https://github.com/mitao-su/dsh-playwright-cli/archive/refs/heads/main.tar.gz

本地路径/开发安装：

dsh plugin --profile web add ./dsh-playwright-cli   # 或 file: 前缀

使用示例

Agent 侧一次典型会话：

1. playwright_version（workdir 默认会话工作区）→ 确认 CLI 就绪；
2. playwright_test（files: ["tests/login.spec.ts"]，reporter: "html"）→ 跑测试，得到 reportDir；
3. playwright_show_report → 拿到 url，用户直接在浏览器打开报告。

配置（profile cordis.patch.yml 按 id: playwright-cli 整段覆盖）：

- insert:
- id: playwright-cli
name: dsh-playwright-cli
config:
timeoutMs: 600000          # 每次 CLI 调用的默认超时
reportDir: playwright-report
reportRoute: /playwright-report
autoInstallPackage: true   # CLI 缺失时自动 npm install -D @playwright/test

注意事项

- 沙箱与升级出口：命令走 shell 执行器的 sandbox。浏览器二进制下载到用户目录、playwright test fork worker 子进程等，都可能被文件沙箱拒绝——此时结果带 [sandbox: file access denied ...] 标记和升级提示。playwright_version / playwright_install / playwright_test 与官方 shell 工具一致，提供 sandbox_permissions + justification 参数：沙箱拒绝后，用能通过的最窄更宽模式重试同一条命令（如 danger-full-access），执行前会弹用户审批，获批后仅本次调用生效。
- 本地安装约束（避免双副本）：工具按 npx --no-install 解析，只认 workdir 里的本地 @playwright/test，不会用全局 CLI。若 workdir 的 spec 文件 require('@playwright/test') 解析到本地副本而 CLI 命中全局，会出现 test.describe() not expected here 之类的双副本错误——请把 workdir 指向装有本地 @playwright/test 的项目目录（可先用 playwright_install 脚手架）。
- 引号：参数按挂载 shell 的方言（bash/pwsh）自动安全引用；含单引号的路径请先重命名。
- 报告路由：playwright_show_report 每次调用注册一条 /playwright-report/ 回环路由，插件卸载时统一释放；同一报告可多次调用。
- 并发：playwright_test/playwright_install 声明为不可并发（共享 test-results/report 目录）。

开发

pnpm install
pnpm verify      # typecheck + build + git diff --check

License

MIT