> ## Documentation Index
> Fetch the complete documentation index at: https://niceeval.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据驱动测试（dataset fan-out）：用多份数据运行同一套评估用例

> 从 .eval.ts 文件导出数组或 keyed record，将一套评估逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部数据集，并获得稳定 ID。

数据驱动测试（dataset fan-out）适合大量结构相同、输入不同的测试。例如 SQL 生成、意图分类、检索问答和工具选择。

## 工作原理

没有外部业务 ID 时，一个 `.eval.ts` 文件默认导出数组：

```ts theme={null}
import { defineEval } from "niceeval";
import { equals } from "niceeval/expect";

const rows = [
  { task: "Count users", prompt: "Count all users", sql: "SELECT COUNT(*) FROM users;" },
  { task: "Recent orders", prompt: "Find recent orders", sql: "SELECT * FROM orders ORDER BY created_at DESC LIMIT 10;" },
];

export default rows.map((row) =>
  defineEval({
    description: row.task,
    async test(t) {
      await t.send(row.prompt);
      t.check(t.reply, equals(row.sql));
    },
  }),
);
```

## 生成 ID

如果文件是 `evals/sql.eval.ts`，生成的 ID 是：

```text theme={null}
sql/0000
sql/0001
```

序号零填充，便于稳定引用和过滤。

数据源已经带稳定 case、issue 或 benchmark ID 时，默认导出 keyed record：

```ts theme={null}
export default Object.fromEntries(
  rows.map((row) => [
    row.issueId,
    defineEval({
      description: row.title,
      async test(t) {
        await t.send(row.prompt);
        t.succeeded();
      },
    }),
  ]),
);
```

文件是 `evals/swelancer.eval.ts`、key 是 `15193` 时，ID 就是 `swelancer/15193`。key 必须是一个非空路径片段：不能是 `.` / `..`，不能含 `/`、`\\` 或控制字符。NiceEval 按 key 字典序发现，数据源返回顺序变化不会改变运行顺序。

## 从 YAML / JSON 加载

```ts theme={null}
import { loadYaml } from "niceeval/loaders";

const doc = await loadYaml("evals/data/sql-cases.yaml");
const rows = doc.cases as { task: string; prompt: string; sql: string }[];
```

```yaml theme={null}
cases:
  - task: Count users
    prompt: Count all rows in the users table
    sql: SELECT COUNT(*) FROM users;
```

## 过滤数据集评估用例

```bash theme={null}
# 运行整个数据集
npx niceeval exp local sql

# 只运行第一个数组 case
npx niceeval exp local sql/0000

# 运行一个 keyed case
npx niceeval exp local swelancer/15193
```

## 数据集 vs 独立文件

<Tabs>
  <Tab title="使用数据集">
    case 结构完全一致，主要差异是输入和预期输出。
  </Tab>

  <Tab title="使用独立文件">
    每个 case 有不同流程、不同断言或需要不同 agent 配置。
  </Tab>
</Tabs>

<Tip>
  数据集适合”横向覆盖”，独立评估用例文件适合”行为复杂”的场景。
</Tip>