skillhub-048-eval-driven-dev/references/5-run-tests.md

步骤 5：运行 pixie test 并修复机械问题

为什么需要这一步：运行 pixie test 并修复 QA 组件中的机械问题——数据集格式问题、可运行实现中的 bug 以及自定义评估器错误——直到每一条记录都产生真实评分。这一步不涉及评估结果质量或修复应用程序本身。

---

5a. 运行测试

uv run pixie test

如需包含每条用例评分和评估器推理的详细输出：

uv run pixie test -v

pixie test 在运行测试前会自动加载 .env 文件。

评估框架的执行流程如下：

1. 从数据集的 runnable 字段解析出 Runnable 类
2. 调用 Runnable.create() 构造实例，然后调用一次 setup()
3. 以并发方式运行所有数据集条目（最多 4 个并行）： a. 从条目中读取 input_data 和 eval_input b. 用 eval_input 数据填充 wrap 输入注册表 c. 初始化捕获注册表 d. 将 input_data 校验为 Pydantic 模型，然后调用 Runnable.run(args) e. 应用中的 wrap(purpose="input") 调用返回注册表中的值，而不是调用外部服务 f. wrap(purpose="output"/"state") 调用捕获评估所需的数据 g. 从捕获的数据构建 Evaluable h. 运行评估器
4. 调用一次 Runnable.teardown()

由于条目是并发运行的，Runnable 的 run() 方法必须是并发安全的。如果看到 sqlite3.OperationalError、"database is locked" 或类似错误，请为 Runnable 添加一个 Semaphore(1)（参见步骤 2 参考文档中的并发章节）。

5b. 仅修复机械问题

这一步严格限于修复你在前面步骤中构建的内容——数据集、runnable 以及任何自定义评估器。你修复的是阻止流水线运行的机械问题，而非评估或改进应用程序的输出质量。

哪些属于机械问题（需要修复）：

错误	原因	修复方法
WrapRegistryMissError: name='<key>'	数据集条目缺少 eval_input 项，其中 name 与应用中 wrap(purpose="input", name="<key>") 所期望的名称不匹配	在每个受影响的条目的 eval_input 中添加缺失的 {"name": "<key>", "value": ...}
WrapTypeMismatchError	反序列化的类型与应用的期望不匹配	修复数据集中的值
Runnable 解析失败	runnable 路径或类名错误，或该类未实现 Runnable 协议	修复数据集中的 filepath:ClassName；确保该类包含 create() 和 run() 方法
导入错误	模块路径错误或 runnable/evaluator 中存在语法错误	修复引用的文件
ModuleNotFoundError: pixie_qa	pixie_qa/ 目录缺少 __init__.py	运行 pixie init 重新创建
TypeError: ... is not callable	评估器名称指向一个不可调用的属性	评估器必须是函数、类或可调用实例
sqlite3.OperationalError	并发 run() 调用共享同一个 SQLite 连接	为 Runnable 添加 asyncio.Semaphore(1)（参见步骤 2 的并发章节）
自定义评估器崩溃	自定义评估器实现中存在 bug	修复评估器代码

哪些不属于机械问题（此处不要修复）：

• 应用程序输出错误或质量低下 → 属于应用程序行为，在步骤 6 中分析
• 评估器评分低 → 属于质量信号，在步骤 6 中分析
• 应用内部的 LLM 调用失败 → 在步骤 6 中报告，不要模拟或绕过
• 评估器评分在不同运行之间波动 → 正常的 LLM 非确定性，不是 bug

反复迭代——修复错误，重新运行，修复下一个错误——直到 pixie test 成功运行完毕，所有条目都产生真实的评估器评分。

输出

pixie test 成功完成后，结果会存储在按条目组织的目录结构中：

{PIXIE_ROOT}/results/<test_id>/
  meta.json                           # 测试运行元数据
  dataset-{idx}/
    metadata.json                     # 数据集名称、路径、runnable
    entry-{idx}/
      config.json                     # 评估器、描述、预期结果
      eval-input.jsonl                # 提供给评估器的输入数据
      eval-output.jsonl               # 从应用捕获的输出数据
      evaluations.jsonl               # 评估结果（已评分 + 待评分）
      trace.jsonl                     # LLM 调用追踪记录（如果已捕获）

<test_id> 会打印在控制台输出中。你将在步骤 6 中引用该目录。

---

如果在运行测试时遇到意外错误（参数名称错误、导入失败、API 不匹配），请在猜测修复方法之前先阅读 wrap-api.md、evaluators.md 或 testing-api.md 获取权威 API 参考。