dsh-playwright-cli

Readme

# dsh-playwright-cli

[DeepSeek Harness](https://github.com/deepseek-ai/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）。

```sh
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 安装，效果相同：

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

本地路径/开发安装：

```sh
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` 整段覆盖）：

```yaml
- 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/<nonce>` 回环路由，插件卸载时统一释放；同一报告可多次调用。
- **并发**：`playwright_test`/`playwright_install` 声明为不可并发（共享 test-results/report 目录）。

## 开发

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

## License

MIT