vitest-evals

vitest-evals

仅使用基于 harness 的 API 作为编写方式。

入门步骤

1. 阅读要修改的 package、app 或 eval 文件。
2. 确定运行时目标，然后仅打开所需的参考文档。
3. 让测试套件保持接近 Vitest 的风格：每个 describeEval(...) 使用一个 harness，在每个测试中显式调用 run(...)，并使用普通的 expect(...) 断言检查返回结果。

参考文档导航

需求	打开
编写或审查普通 eval 测试套件	references/suite-authoring.md
在没有一方适配器的情况下构建自定义 app Harness	references/custom-harness.md
集成 AI SDK generateText、generateObject、工具或 AI SDK 风格的 Agent	references/harness-ai-sdk.md
集成 Pi AI 或 Pi Mono 风格的 Agent	references/harness-pi-ai.md
添加自定义评审器、测试套件评审器、内置评审器或 toSatisfyJudge(...) 断言	references/judges-and-assertions.md
对消息、工具调用或跨度历史进行断言	references/utilities.md
配置工具记录或回放	references/tool-replay.md
诊断失败、缺失的追踪记录、异常输出，或选择验证命令	references/troubleshooting.md

运行时默认设置

• 从 vitest-evals 导入 describeEval(...)、评审器和辅助函数。
• 为一个测试套件绑定且只绑定一个 harness。
• 在测试需要执行系统时调用 run(input)。
• 对 app 面向用户的行为，断言 result.output。
• 使用 toolCalls(result) 和消息辅助函数进行标准化会话断言。
• 使用 spans(result)、spansByKind(result, kind) 和 failedSpans(result) 进行跨度断言。
• 确保 HarnessRun、NormalizedSession、用量、产物和工具记录可序列化为 JSON。
• 在 run.usage 中报告已知的 token 数和 USD 成本。成本未知时省略 costUsd；只有确定运行不产生费用时才使用 0。
• 将评分标准文本和解析逻辑放在评审器中。将提供方调用放入 judgeHarness，然后通过 ctx.runJudge(...) 调用，以便记录用量。
• 将场景自有的标准放在输入值中。将直接检查所需的值放在 Vitest 用例行中。通过显式匹配器选项传递每个用例的评审标准，通过评审器配置传递整个测试套件通用的标准。
• 自定义评审器应使用 createJudge(...)，以保持报告标签稳定。

验证

优先选择能覆盖所编辑文件的最小命令：

任务	命令
检查文件 lint	pnpm exec biome lint path/to/file.ts
格式化文件	pnpm exec biome format --write path/to/file.ts
测试文件	pnpm exec vitest run path/to/file.test.ts -c vitest.config.ts
Eval 文件	pnpm exec vitest run path/to/file.eval.ts -c vitest.config.ts --reporter=./packages/vitest-evals/src/reporter.ts
类型检查	pnpm typecheck
构建 package	pnpm build