dsh-test-runner

Readme

# dsh-test-runner

DeepSeek Harness 插件：结构化测试运行工具 **`test_run`**。

让 agent 用一次工具调用完成「改代码 → 跑测试 → 修」闭环：自动探测测试框架、执行测试、**只返回结构化摘要**（通过/失败统计 + 失败用例名称与错误信息 + 输出尾部），避免模型阅读整段原始测试输出（省 token、少一轮）。

## 功能

| 能力 | 说明 |
|---|---|
| 框架自动探测 | `package.json` 的 vitest/jest 依赖 → `vitest`/`jest`；`scripts.test` → `npm-test`；`pyproject.toml`/`pytest.ini`/`conftest.py` → `pytest`；`test/` 目录或 `*.test.*` 文件 → `node`（node:test） |
| 目标过滤 | `target` 指定文件/目录/用例模式（如 `tests/test_api.py::test_login`），多个目标空格分隔 |
| 失败摘要 | 每个失败用例提取名称 + 错误信息（vitest `×`/`→`、jest `●`、pytest `FAILED`、node:test TAP `not ok` + `error:` 块） |
| 只重跑失败 | `last_failed` → vitest `--lastFailed` / jest `--onlyFailures` / pytest `--lf` |
| 自定义命令 | `command` 完全覆盖默认命令（如 `pnpm vitest run`、`python -m pytest -x -q`） |
| 超时与取消 | `timeout_ms` 默认 120s；工具取消信号转发给子进程 |
| 沙箱合规 | 按调用会话解析 `sandboxPolicy`（会话覆盖 > 部署默认），与 bash 工具同一策略 |

## 安装

```sh
dsh plugin --profile web add ./dsh-test-runner        # 本地目录
# 或从 GitHub（需要 prepare 脚本 + allowBuilds 放行）
dsh plugin --profile web add github:you/dsh-test-runner
```

重启 `dsh --profile web` 后生效。管理面板：设置 → 插件。

## 使用示例

模型侧直接调用：

- `test_run`（自动探测，跑全部）
- `test_run(target="src/utils.test.ts")`（跑单文件）
- `test_run(framework="pytest", target="tests/test_api.py::test_login")`
- `test_run(last_failed=true)`（只重跑上次失败）
- `test_run(command="pnpm vitest run --coverage")`

返回结构：

```json
{
  "ok": false,
  "framework": "node",
  "command": "node --test",
  "exitCode": 1,
  "durationMs": 800,
  "summary": { "total": 6, "passed": 5, "failed": 1, "skipped": 0 },
  "failures": [
    { "name": "string: broken case (intentional failure)",
      "message": "Expected values to be strictly equal: | 'WORLD' !== 'WRLD' | ..." }
  ],
  "outputTail": "<原始输出尾部 3000 字符>"
}
```

## 兼容性

- DSH mainline 持续快速演进，本插件只依赖 `shell` / `fs` / `sandboxPolicy` 三个稳定服务 seam 与 `ctx.tools` 注册接口。
- 验证日期：2026-08（Windows + PowerShell 执行器 + node:test 实测）。
- **退化安全**：解析器匹配不到失败摘要时不崩溃，退化为 `exitCode + 输出尾部`——最坏不比直接用 bash 跑测试差。

## 规范合规

对照官方开发文档（`docs/user/develop/basic/tool.md`、`docs/cookbook/adding-a-tool.md`、`docs/user/develop/framework/index.md`、`docs/user/develop/practice/index.md`）逐条核验：

### execute 契约

| 规范要求 | 状态 | 实现位置 |
|---|---|---|
| args 由 `defineTool` 校验；手检非空/正数 | ✅ | `timeout_ms` 正数校验（参考 bash `validateArgs`） |
| 返回单一 canonical JSON value | ✅ | execute 返回纯 object，不含 content blocks |
| infra 失败 throw；domain 结果正常返回 | ✅ | shell resolve/run 失败 `throw`；测试失败(exit≠0) 正常返回 value |
| Honor `exec.signal` | ✅ | 传给 `shell.resolve({ signal: exec.signal })` |
| `output.schema` 声明规范值 | ✅ | `{ type: 'json' }`，render 与 presentationMeta 派生自 value |

### UI 卡片（硬规则）

| 规范要求 | 状态 | 实现位置 |
|---|---|---|
| presentCall/presentResult 纯函数（无 I/O、无 session state、无 clock/random） | ✅ | 只读 args / result.meta |
| UI 格式不进 canonical value | ✅ | value 为纯结构化 JSON；卡片格式在 presentResult |
| terminal 卡片 title 是命令 | ✅ | 已知 framework 时 `buildCommand` 重建真实命令；auto 退回 generic 卡片（不伪造命令） |
| presentResult 返回 `undefined` 做 generic 兜底 | ✅ | isError 或无 meta 时返回 undefined |
| presentationMeta 派生 replayable JSON | ✅ | `{ exitCode, timedOut, outputText }` 从 value 派生 |

### 生命周期与依赖

| 规范要求 | 状态 | 实现位置 |
|---|---|---|
| 注册 effect-based，fiber 卸载自动注销 | ✅ | `ctx.tools.register(defineTool(...))` |
| 副作用可逆 | ✅ | 无自定义资源需手动清理（shell/fs 为共享服务） |
| 硬依赖 `inject`；可选服务 `ctx.get` + undefined 检查 | ✅ | `inject: ['tools']`；shell/fs/sandboxPolicy 用 `ctx.get` 检查 |
| `isConcurrencySafe` 声明 | ✅ | `() => false`（测试改状态，独占执行） |

### 能力分层与配置

| 规范要求 | 状态 | 说明 |
|---|---|---|
| 不过早拆分 Service Definition/Provider/Consumer | ✅ | 单包工具，未拆（practice 明确说 simple tool 不拆） |
| 可调值进 Config Schema | ✅ | 无部署间可调值（框架/命令由模型参数传入） |

### 打包

| 规范要求 | 状态 | 实现位置 |
|---|---|---|
| bundle 声明 `dsh.bundle.patch` | ✅ | `package.json` |
| cordis.patch.yml 按包名引用 | ✅ | `name: dsh-test-runner` |
| 语法校验 | ✅ | `node --check` 通过 |

### 已知边界（诚实声明）

- 解析器正则匹配当前主流版本的**默认 reporter 输出**；框架升级改格式 → 退化安全（不崩，返回 exitCode + 尾部）。
- 已验证：vitest/jest/pytest/node:test 默认输出；go test / cargo test 等未覆盖，退化为原始输出。
- 仅在 Windows + PowerShell 执行器实测；命令本身跨方言（`npx`/`python`/`node`），bash 下理论可行但未验证。

## 开发

```sh
# 本地覆盖层开发
pnpm dsh web --patch ./cordis.patch.yml
```

## License

MIT