gxinxing/dsh-tool-test-runner

@deepseek-ai/dsh-tool-test-runner

test_runner 工具插件，为 DSH 模型提供跨测试框架的自动发现、执行、失败分析、覆盖率统计与测试生成建议能力。

插件简介

该插件向 DSH Agent 注册一个名为 test_runner 的工具，使模型能够：

- 自动识别项目中的测试框架（jest / vitest / pytest / mocha / playwright）
- 在指定路径执行测试并解析结构化结果
- 对失败测试做根因分类与定位建议
- 读取并汇总覆盖率报告
- 基于源代码导出符号，建议缺失的测试用例

所有操作均返回结构化 JSON，便于模型在工具链中串联使用。

安装与注册

通过 cordis.patch.yml 注册插件：

cordis.patch.yml
dsh-tool-test-runner bundle patch: registers the test_runner tool plugin.
- insert:
- id: tool-test-runner
name: '@deepseek-ai/dsh-tool-test-runner'
config:
testRunnerTimeoutMs: 120000
testRunnerMaxOutputBytes: 1048576

cordis.patch.yml 会被 DSH 构建系统自动发现并注入。包入口为 lib/index.js，类型定义入口为 lib/types/index.d.ts。

配置参数

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| testRunnerTimeoutMs | number | 120000 | 测试命令超时时间（毫秒） |
| testRunnerMaxOutputBytes | number | 1048576 | 单次 stdout / stderr 最大捕获字节数 |

5 种 Action 详解

1. discover

自动扫描当前工作区，检测测试框架、配置文件与测试文件。

调用示例

{
"action": "discover",
"target": "tests/unit"
}

返回示例

{
"action": "discover",
"framework": "vitest",
"configFile": "/workspace/vitest.config.ts",
"command": "npx vitest run tests/unit",
"testFiles": [
"/workspace/tests/unit/combat.test.ts",
"/workspace/tests/unit/player.test.ts"
],
"coverage": {
"reportDir": "coverage",
"reportPattern": "coverage/coverage-summary.json"
},
"warnings": []
}

行为说明

- 按优先级扫描以下文件来识别框架：

| 框架 | 识别文件 |
| --- | --- |
| jest | jest.config.js, jest.config.ts, jest.config.cjs, package.json |
| vitest | vitest.config.js, vitest.config.ts, vite.config.js, vite.config.ts, package.json |
| pytest | pytest.ini, pyproject.toml, tox.ini, setup.cfg |
| mocha | .mocharc.js, .mocharc.cjs, .mocharc.json, mocha.config.js, package.json |
| playwright | playwright.config.js, playwright.config.ts |

- 递归收集 .test / .spec（JS/TS）与 test_*.py（Python）文件。
- 若未检测到配置，仍返回 unknown 框架并给出警告。

2. run

执行测试并返回结构化运行结果。

调用示例

{
"action": "run",
"target": "tests/unit/combat",
"timeout_ms": 120000,
"max_output_bytes": 1048576
}

返回示例

{
"action": "run",
"framework": "vitest",
"command": "npx vitest run tests/unit/combat",
"durationMs": 3214,
"stdout": "[vitest]...\nTests 3 | Passed 2 | Failed 1\n",
"stderr": "",
"summary": {
"passed": 2,
"failed": 1,
"skipped": 0,
"total": 3,
"exitCode": 1,
"timedOut": false
},
"testResults": [
{
"file": "/workspace/tests/unit/combat.test.ts",
"name": "Combat rounds apply damage",
"status": "passed",
"durationMs": 120,
"error": null
},
{
"file": "/workspace/tests/unit/combat.test.ts",
"name": "Player death when health  (combat.test.ts:45)",
"assertionDiff": "Expected: 0\\nReceived: -1",
"codeContext": "test('Player death when health  );\\n  applyDamage(player, 5);\\n  expect(player.health).toBe(0);\\n});",
"suggestions": [
"Re-run the single failing test in isolation to confirm reproducibility.",
"Check recent changes to the code under test."
]
}
],
"suggestions": [
"Re-run the single failing test in isolation to confirm reproducibility.",
"Check recent changes to the code under test."
]
}

行为说明

- 必须提供 file 参数，指向失败测试文件。
- 通过关键词匹配将失败归类为：

- logic_error：断言失败、类型错误、未定义/空值
- environment：网络、超时、文件缺失、权限错误
- data：JSON/语法/解析错误
- concurrency：锁、死锁、并发修改
- unknown：无法识别

- 默认返回 medium 置信度；未读文件时返回 low。

4. coverage

汇总项目覆盖率报告。

调用示例

{
"action": "coverage",
"target": "src"
}

返回示例

{
"action": "coverage",
"framework": "vitest",
"reportPath": "coverage/coverage-summary.json",
"totals": {
"lines": { "pct": 72, "covered": 288, "total": 400 },
"functions": { "pct": 68, "covered": 102, "total": 150 },
"branches": { "pct": 65, "covered": 104, "total": 160 },
"statements": { "pct": 74, "covered": 296, "total": 400 }
},
"files": [
{
"path": "src/combat.ts",
"lines": 120,
"linesCovered": 108,
"functions": 18,
"functionsCovered": 16,
"branches": 24,
"branchesCovered": 20,
"statements": 118,
"statementsCovered": 105
}
],
"uncoveredFiles": [
"src/combat.ts",
"src/network.ts"
],
"highRiskFiles": [
"src/network.ts",
"src/combat.ts",
"src/auth.ts"
],
"suggestions": [
"Overall line coverage is 72%. Target 80%+ by adding tests for uncovered files.",
"2 file(s) have uncovered lines.",
"High-risk files (low coverage + branching): src/network.ts, src/combat.ts, src/auth.ts."
]
}

行为说明

- 优先查找框架默认覆盖率报告文件：

| 框架 | 报告目录 | 报告文件 |
| --- | --- | --- |
| jest | coverage/ | coverage/coverage-summary.json |
| vitest | coverage/ | coverage/coverage-summary.json |
| pytest | htmlcov/ | coverage.xml |
| mocha | coverage/ | coverage/coverage-summary.json |
| playwright | playwright-report/ | index.html |

- 若未找到报告，返回空数据并提示先运行带 coverage 的测试。
- highRiskFiles 按“低行覆盖率 + 低分支覆盖率”加权排序。

5. suggest

扫描源文件并建议缺失的测试用例。

调用示例

{
"action": "suggest",
"target": "src"
}

返回示例

{
"action": "suggest",
"framework": "vitest",
"sourceFile": "/workspace/src/combat.ts",
"suggestions": [
{
"symbol": "applyDamage",
"scenario": "Unit coverage for applyDamage",
"cases": [
"normal input",
"boundary input",
"invalid input"
],
"targetPath": "tests/unit/combat/combat_applydamage_test.js"
},
{
"symbol": "heal",
"scenario": "Unit coverage for heal",
"cases": [
"normal input",
"boundary input",
"invalid input"
],
"targetPath": "tests/unit/combat/combat_heal_test.js"
}
]
}

行为说明

- 扫描常见源码目录，最多分析前 20 个源文件。
- 仅提取 export 的函数、类、常量作为测试符号。
- 对每个符号生成 3 个标准场景：normal input / boundary input / invalid input。

支持框架列表

- jest
- vitest
- pytest
- mocha
- playwright

错误处理说明

| 场景 | 行为 |
| --- | --- |
| 未知 action | 抛出 Unknown test_runner action: ... |
| 沙箱拒绝文件访问 | 返回 FS_SANDBOX_DENIED 并附带提升提示 |
| 未找到配置文件 | discover 返回 framework: "unknown" + warnings |
| 超时 | run 返回 timedOut: true，exitCode 为 -1 |
| 无覆盖率报告 | coverage 返回空数据并建议先运行带 coverage 的测试 |
| analyze-failure 未提供 file | 返回警告，要求提供具体文件路径 |

工具在执行时会受 DSH 沙箱策略约束；若遇到 FS_SANDBOX_DENIED，可通过 sandbox_permissions 与 justification 参数申请一次性提升。

类型定义说明

完整类型定义位于 lib/types/index.d.ts，主要接口包括：

- TestRunnerConfig：插件配置
- TestRunnerDiscoverResult：discover 返回
- TestRunnerRunResult：run 返回
- TestRunnerAnalyzeFailureResult：analyze-failure 返回
- TestRunnerCoverageResult：coverage 返回
- TestRunnerSuggestResult：suggest 返回
- TestRunnerResult：以上结果的联合类型
- TestRunnerParameters：工具入参结构

示例参数常量：

import { TEST_RUNNER_EXAMPLE_PARAMS } from '@deepseek-ai/dsh-tool-test-runner';
// { action: 'discover' }