@taicode/common-server 4.0.0-beta.4 → 4.0.0-beta.6

package/output/core/test-support/testdata.d.ts

@@ -0,0 +1,148 @@
+import type { LoggerLike } from '../types.js';
+/**
+ * **测试数据（testdata）机制**：`packages/server/testdata/*.ts|js` 下的脚本，在 `development` /
+ * `test` 启动时自动加载、在测试用例之间自动清理。
+ *
+ * ## 为什么是「目录 + 两个约定方法」，而不是资源上的生命周期
+ *
+ * 「这条用例需要哪些样本数据」与「这份数据怎么删掉」是**同一件事的正反面**，写在同一个文件里
+ * 才不容易漏。把 `cleanup` 挂到资源单元上做不到这一点：资源只知道「有哪些表 / 哪些 key」，
+ * 不知道「谁往里写了什么」——新增一个 model 就要回去改一次清库清单，漏改只会安静地变脏。
+ *
+ * 所以机制倒过来：**数据脚本自己负责自己**。
+ *
+ * ```ts
+ * // packages/server/testdata/01-base.ts
+ * import { PrismaClient } from '@prisma/generated/client'
+ *
+ * export async function load() { …插入样本数据… }
+ * export async function cleanup() { …删掉自己插入的数据… }
+ * ```
+ *
+ * ## 契约（只有三条）
+ *
+ * 1. **目录固定**：`<cwd>/testdata`（`tsx watch ./source/index.ts` 与 `vitest` 的 cwd 都是
+ *    `packages/server`）。目录不存在 = 没有脚本。
+ * 2. **两个方法都必需**：`load()` 与 `cleanup()` 缺一个就**报错**（不是跳过）。只写 `load`
+ *    的脚本意味着「这份数据删不掉」，那正是本机制要消灭的东西。
+ * 3. **顺序**：文件名（字典序升序）是默认序；需要「我必须排在某脚本之后」时用
+ *    `dependsOn` 显式声明，见下节。
+ *
+ * ## 顺序：`dependsOn` 是权威，文件名只做同层破平
+ *
+ * ```ts
+ * // packages/server/testdata/02-organization.ts
+ * export const dependsOn = ['01-database']
+ * ```
+ *
+ * - **引用名 = 去扩展名的文件名**（`01-base.ts` → `'01-base'`），与 `TestDataUnit.name` 一致。
+ * - **只影响顺序，不注入任何东西**：声明依赖**不会**把前一个脚本的客户端/数据递给你。脚本仍然
+ *   自己建自己的连接（只依赖 env），否则 `testdata/` 就不再是可独立运行的样本数据。
+ * - **`cleanup` 不用声明**：它是装配序的逆序，依赖自动反向成立（后建的先拆）。
+ * - **同层按文件名升序**：没有依赖关系的脚本之间的相对顺序由文件名决定，结果确定可复现。
+ * - **缺依赖 / 自依赖 / 环一律报错**（不是跳过、不是猜测顺序）：顺序是安全属性，猜错只会
+ *   变成偶发的外键冲突。
+ *
+ * 为什么要有这个字段：数字前缀是「顺序的替身」，中间插一个脚本就得重命名后面全部文件——
+ * 纯噪音改动，还会切断 git 历史。依赖声明让「谁必须在谁之后」贴着原因写。
+ *
+ * > 字段名与已删除的**模块装配期** `dependsOn`（连同 `validateLifecycleDependencies`，§11-2）
+ * > 无关：那个是资源/模块之间的构造依赖，这个是数据脚本之间的**执行顺序**。
+ *
+ * ## 两条与「安全」有关的约定
+ *
+ * - **`_` 开头的文件不是脚本**：它们是脚本之间共享的 helper（`_client.ts`），不会被 `load` /
+ *   `cleanup`。否则扫描目录就会把工具文件也当成脚本执行。
+ * - **只在可清理环境执行**：`load` / `cleanup` / `reset` 三个执行入口的**第 0 步**都是
+ *   `assertCleanableEnvironment(env)`。`env` 是**必填参数**而不是从 `process.env` 现读——
+ *    漏传即编译错误，且判据是装配期的快照（事后改写 `process.env` 不影响结论）。
+ *
+ * ## 执行顺序与失败语义
+ *
+ * | 入口 | 顺序 | 失败 |
+ * | --- | --- | --- |
+ * | `loadTestData` | **执行序**（`dependsOn` 拓扑序，同层按文件名升序） | 立即冒泡 |
+ * | `cleanupTestData` | **执行序逆序** | 立即冒泡 |
+ * | `resetTestData` | 先整体 `cleanup`（逆序），再整体 `load`（正序） | 立即冒泡 |
+ *
+ * `cleanup` 逆序是「后建的先拆」，依赖因此不必反向声明；`reset` 合成一个入口是给
+ * `beforeEach` 用的——一条语句就能拿到干净基线，不需要调用方自己记「先清后载」。
+ *
+ * 失败**一律冒泡**，不降级成「跳过这条脚本」：数据没准备好时静默继续只会让后续用例读到脏状态，
+ * 制造伪绿。
+ */
+export interface TestDataScript {
+    /** 加载本脚本负责的测试数据（可重复执行：`reset` 会反复调它） */
+    load(): void | Promise<void>;
+    /** 清理本脚本负责的测试数据（必须能把 `load()` 的效果完全撤销） */
+    cleanup(): void | Promise<void>;
+    /**
+     * 必须在哪些脚本**之后**执行（去扩展名的文件名；缺省 = 无要求）。
+     *
+     * 只影响排序：`load` 按依赖拓扑序（同层按文件名升序），`cleanup` 取其逆序。
+     * 校验严格：引用不存在的脚本、引用自己、循环依赖都会让装载阶段**抛错**。
+     */
+    readonly dependsOn?: readonly string[];
+}
+/** 一个已从磁盘装载好的脚本单元（含名字，用于日志与报错定位） */
+export interface TestDataUnit extends TestDataScript {
+    /** 脚本文件名去掉扩展名（`01-base.ts` → `01-base`） */
+    readonly name: string;
+}
+/** 三个执行入口的共同入参 */
+export interface TestDataRunParams {
+    /**
+     * 本次装配的 `env.ENV`（`ctx.env.ENV`）。**必填**：破坏性动作没有环境就没法判断该不该跑。
+     *
+     * 非 `CLEANABLE_ENVS`（`development` / `test`）一律抛错，一个脚本都不跑。
+     */
+    env: string;
+    /** 已装载的脚本（`discoverTestDataModules()` 的产物）；缺省 = 没有脚本 */
+    units?: readonly TestDataUnit[];
+    /** 日志标签（`defineServer({ app: { service } })`） */
+    service?: string;
+    /** 记录型 logger（`ctx.log`）；缺省 = 不打日志 */
+    log?: LoggerLike;
+}
+/** 默认脚本目录（相对 `process.cwd()`） */
+export declare function resolveTestDataDirectory(): string;
+/**
+ * 扫描目录并**装载**全部脚本（`import()` 一次，模块本身由 ESM 缓存复用）。
+ *
+ * 目录不存在 → 空数组（不是错误：没写测试数据的服务是合法的）。
+ * 文件存在但 `load` / `cleanup` 缺一个 → **抛错**，并指出是哪个文件缺哪个方法。
+ *
+ * 返回的顺序就是**执行序**：`dependsOn` 拓扑序 + 同层文件名升序（`load` 直接正序跑，
+ * `cleanup` 直接逆序跑）。
+ */
+export declare function discoverTestDataModules(directory?: string): Promise<TestDataUnit[]>;
+/**
+ * 加载测试数据：按**执行序**逐项 `await load()`（依赖在前，同层按文件名升序）。
+ *
+ * 在 `createTestServer()` 装配完成（`ready()` 之后）自动执行一次；也可以由测试自己再调。
+ */
+export declare function loadTestData(params: TestDataRunParams): Promise<void>;
+/**
+ * 清理测试数据：按执行序**逆序**逐项 `await cleanup()`（后建的先拆）。
+ *
+ * 依赖不必反向声明：`load` 的拓扑序取逆就是安全的拆除序。
+ *
+ * 单独调用它的场景很少（多半是要 `resetTestData`）：它与 `loadTestData` 成对，
+ * 语义是「把脚本插入的数据撤掉」，而不是「把整个库清空」。
+ */
+export declare function cleanupTestData(params: TestDataRunParams): Promise<void>;
+/**
+ * 重置测试数据：先**整体** `cleanup`（逆序），再**整体** `load`（正序）。
+ *
+ * 这是 `beforeEach` 的标准动作（`TestServer.resetTestData()` 的底层实现）：
+ * 先全部撤掉再全部重建，而不是「逐脚本 cleanup + load」——后者会让前一个脚本重新插入的数据
+ * 被后一个脚本的 `cleanup` 顺手删掉（顺序依赖）。分两趟就没有这个问题。
+ *
+ * ## 两点与「安全」有关的说明
+ *
+ * - **先在清理阶段**：万一 `load` 失败，库里留下的是「干净」而不是「半套数据 + 半套旧数据」。
+ * - **闸门只判一次**（三个入口各自开头），不做逐脚本判定：同一批脚本在同一环境里跑，
+ *   逐个判只是把一次判定复制 N 次。
+ */
+export declare function resetTestData(params: TestDataRunParams): Promise<void>;
+//# sourceMappingURL=testdata.d.ts.map

package/output/core/test-support/testdata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testdata.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/testdata.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,0CAA0C;IAC1C,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,kBAAkB;AAClB,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAA;IACX,wDAAwD;IACxD,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sCAAsC;IACtC,GAAG,CAAC,EAAE,UAAU,CAAA;CACjB;AAED,iCAAiC;AACjC,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AA8FD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,SAAS,GAAE,MAAmC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAgDrH;AAeD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO3E;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW5E"}

package/output/core/test-support/testdata.js

@@ -0,0 +1,202 @@
+import { readdir } from 'node:fs/promises';
+import { basename, extname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { assertCleanableEnvironment } from '../env.js';
+/** 默认脚本目录（相对 `process.cwd()`） */
+export function resolveTestDataDirectory() {
+    return resolve(process.cwd(), DEFAULT_TESTDATA_DIRECTORY);
+}
+const DEFAULT_TESTDATA_DIRECTORY = 'testdata';
+/** 会被当作脚本的扩展名 */
+const TESTDATA_EXTENSIONS = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'];
+/** `_` 前缀 = 共享 helper，不参与 load / cleanup */
+const HELPER_PREFIX = '_';
+function isTestDataFile(name) {
+    if (name.startsWith(HELPER_PREFIX)) {
+        return false;
+    }
+    // `.d.ts` 是纯声明，没有运行期实现
+    if (name.endsWith('.d.ts')) {
+        return false;
+    }
+    return TESTDATA_EXTENSIONS.includes(extname(name));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** 读一个脚本模块的 `dependsOn` 导出（缺省 = 空数组；类型不对直接报错） */
+function readDependsOn(file, loaded) {
+    const value = loaded.dependsOn;
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new Error(`[testdata] "${file}" 的 dependsOn 必须是字符串数组（引用其它脚本的去扩展名文件名）`);
+    }
+    return value;
+}
+/**
+ * 按 `dependsOn` 做**稳定**拓扑排序（Kahn）：同层取文件名升序。
+ *
+ * 三个不变式：
+ * - **依赖是权威**：只要 A 声明依赖 B，A 一定排在 B 之后，文件名管不了它。
+ * - **同层可复现**：没有依赖关系的脚本按文件名升序，跑多少次都是同一个序。
+ * - **坏图直接报错**：未知依赖 / 自依赖 / 循环依赖都在装载期抛错，不猜顺序——
+ *   猜错只会变成偶发的外键冲突，比当场失败难查得多。
+ */
+function sortByDependencies(units) {
+    const known = new Set(units.map((unit) => unit.name));
+    const pending = new Map();
+    const dependents = new Map();
+    for (const unit of units) {
+        const deps = [...new Set(unit.dependsOn ?? [])];
+        for (const dep of deps) {
+            if (dep === unit.name) {
+                throw new Error(`[testdata] "${unit.name}" 依赖了自己：dependsOn 只能引用其它脚本`);
+            }
+            if (!known.has(dep)) {
+                throw new Error(`[testdata] "${unit.name}" 依赖的 "${dep}" 不存在：dependsOn 用去扩展名的文件名`);
+            }
+        }
+        pending.set(unit.name, deps.length);
+        for (const dep of deps) {
+            dependents.set(dep, [...(dependents.get(dep) ?? []), unit.name]);
+        }
+    }
+    // 候选池保持升序：同层先跑文件名小的
+    const ready = units.filter((unit) => pending.get(unit.name) === 0).map((unit) => unit.name).sort();
+    const order = [];
+    while (ready.length > 0) {
+        const name = ready.shift();
+        order.push(name);
+        for (const next of dependents.get(name) ?? []) {
+            const rest = (pending.get(next) ?? 0) - 1;
+            pending.set(next, rest);
+            if (rest === 0) {
+                ready.push(next);
+            }
+        }
+        ready.sort();
+    }
+    if (order.length !== units.length) {
+        const stuck = units.filter((unit) => !order.includes(unit.name)).map((unit) => unit.name);
+        throw new Error(`[testdata] 存在循环依赖：${stuck.join(' → ')}`);
+    }
+    return order.map((name) => units.find((unit) => unit.name === name));
+}
+/**
+ * 扫描目录并**装载**全部脚本（`import()` 一次，模块本身由 ESM 缓存复用）。
+ *
+ * 目录不存在 → 空数组（不是错误：没写测试数据的服务是合法的）。
+ * 文件存在但 `load` / `cleanup` 缺一个 → **抛错**，并指出是哪个文件缺哪个方法。
+ *
+ * 返回的顺序就是**执行序**：`dependsOn` 拓扑序 + 同层文件名升序（`load` 直接正序跑，
+ * `cleanup` 直接逆序跑）。
+ */
+export async function discoverTestDataModules(directory = resolveTestDataDirectory()) {
+    let entries;
+    try {
+        entries = (await readdir(directory, { withFileTypes: true }))
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    const files = entries.filter(isTestDataFile).sort();
+    const units = [];
+    for (const file of files) {
+        const name = basename(file, extname(file));
+        const moduleUrl = pathToFileURL(join(directory, file)).href;
+        let loaded;
+        try {
+            loaded = await import(moduleUrl);
+        }
+        catch (error) {
+            throw new Error(`[testdata] 装载 "${file}" 失败：${error instanceof Error ? error.message : String(error)}`, {
+                cause: error,
+            });
+        }
+        if (!isRecord(loaded)) {
+            throw new Error(`[testdata] "${file}" 没有导出任何东西：必须同时导出 load 与 cleanup`);
+        }
+        if (typeof loaded.load !== 'function') {
+            throw new Error(`[testdata] "${file}" 缺少 load 导出：load 与 cleanup 两个都必须有`);
+        }
+        if (typeof loaded.cleanup !== 'function') {
+            throw new Error(`[testdata] "${file}" 缺少 cleanup 导出：load 与 cleanup 两个都必须有`);
+        }
+        units.push({
+            name,
+            dependsOn: readDependsOn(file, loaded),
+            load: loaded.load,
+            cleanup: loaded.cleanup,
+        });
+    }
+    return sortByDependencies(units);
+}
+/** 跑一个脚本步骤（统一日志，失败冒泡给调用方决定） */
+async function runTestDataUnit(params, unit, phase) {
+    const fields = { service: params.service ?? '', unit: unit.name, stage: 'testdata', phase };
+    params.log?.debug(fields, `[testdata] ${phase} "${unit.name}" start`);
+    try {
+        await unit[phase]();
+        params.log?.debug(fields, `[testdata] ${phase} "${unit.name}" done`);
+    }
+    catch (error) {
+        params.log?.error({ ...fields, error }, `[testdata] ${phase} "${unit.name}" failed`);
+        throw error;
+    }
+}
+/**
+ * 加载测试数据：按**执行序**逐项 `await load()`（依赖在前，同层按文件名升序）。
+ *
+ * 在 `createTestServer()` 装配完成（`ready()` 之后）自动执行一次；也可以由测试自己再调。
+ */
+export async function loadTestData(params) {
+    // 闸门先于一切：非可清理环境下一个脚本都不许跑
+    assertCleanableEnvironment(params.env);
+    for (const unit of sortByDependencies(params.units ?? [])) {
+        await runTestDataUnit(params, unit, 'load');
+    }
+}
+/**
+ * 清理测试数据：按执行序**逆序**逐项 `await cleanup()`（后建的先拆）。
+ *
+ * 依赖不必反向声明：`load` 的拓扑序取逆就是安全的拆除序。
+ *
+ * 单独调用它的场景很少（多半是要 `resetTestData`）：它与 `loadTestData` 成对，
+ * 语义是「把脚本插入的数据撤掉」，而不是「把整个库清空」。
+ */
+export async function cleanupTestData(params) {
+    assertCleanableEnvironment(params.env);
+    for (const unit of sortByDependencies(params.units ?? []).reverse()) {
+        await runTestDataUnit(params, unit, 'cleanup');
+    }
+}
+/**
+ * 重置测试数据：先**整体** `cleanup`（逆序），再**整体** `load`（正序）。
+ *
+ * 这是 `beforeEach` 的标准动作（`TestServer.resetTestData()` 的底层实现）：
+ * 先全部撤掉再全部重建，而不是「逐脚本 cleanup + load」——后者会让前一个脚本重新插入的数据
+ * 被后一个脚本的 `cleanup` 顺手删掉（顺序依赖）。分两趟就没有这个问题。
+ *
+ * ## 两点与「安全」有关的说明
+ *
+ * - **先在清理阶段**：万一 `load` 失败，库里留下的是「干净」而不是「半套数据 + 半套旧数据」。
+ * - **闸门只判一次**（三个入口各自开头），不做逐脚本判定：同一批脚本在同一环境里跑，
+ *   逐个判只是把一次判定复制 N 次。
+ */
+export async function resetTestData(params) {
+    assertCleanableEnvironment(params.env);
+    const units = sortByDependencies(params.units ?? []);
+    for (const unit of [...units].reverse()) {
+        await runTestDataUnit(params, unit, 'cleanup');
+    }
+    for (const unit of units) {
+        await runTestDataUnit(params, unit, 'load');
+    }
+}

package/output/core/test-support/testdata.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=testdata.test.d.ts.map

package/output/core/test-support/testdata.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testdata.test.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/testdata.test.ts"],"names":[],"mappings":""}

package/output/core/test-support/testdata.test.js

@@ -0,0 +1,220 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanupTestData, discoverTestDataModules, loadTestData, resetTestData, resolveTestDataDirectory } from './testdata.js';
+const ORIGINAL_ENV = { ...process.env };
+const tempDirs = [];
+afterEach(async () => {
+    process.env = { ...ORIGINAL_ENV };
+    await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+/** 造一个临时脚本目录（内容按 `文件名 → 模块源码` 写入） */
+async function makeDirectory(files) {
+    const dir = await mkdtemp(join(tmpdir(), 'common-testdata-'));
+    tempDirs.push(dir);
+    await Promise.all(Object.entries(files).map(([name, source]) => writeFile(join(dir, name), source)));
+    return dir;
+}
+/** 造一个记录调用顺序的脚本源码（模块级数组挂在 globalThis 上，跨 import 共享） */
+function scriptSource(name, recorder) {
+    return `
+const record = (phase) => globalThis.${recorder}.push(\`\${phase}:${name}\`)
+export function load() { record('load') }
+export function cleanup() { record('cleanup') }
+`;
+}
+describe('discoverTestDataModules', () => {
+    it('目录不存在时返回空数组（没写测试数据的服务是合法的）', async () => {
+        const dir = join(tmpdir(), `common-testdata-missing-${Date.now()}`);
+        await expect(discoverTestDataModules(dir)).resolves.toEqual([]);
+    });
+    it('按文件名升序装载，name 为去扩展名的文件名', async () => {
+        const dir = await makeDirectory({
+            '02-second.mjs': scriptSource('second', '__order02'),
+            '01-first.mjs': scriptSource('first', '__order01'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['01-first', '02-second']);
+        expect(units.every((unit) => typeof unit.load === 'function' && typeof unit.cleanup === 'function')).toBe(true);
+    });
+    it('`_` 开头的文件是共享 helper，不参与 load / cleanup', async () => {
+        const dir = await makeDirectory({
+            '_shared.mjs': 'export const helper = 1',
+            '01-real.mjs': scriptSource('real', '__orderShared'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['01-real']);
+    });
+    it('非脚本文件（.md / .json / .d.ts）被忽略', async () => {
+        const dir = await makeDirectory({
+            'README.md': '# 说明',
+            'data.json': '{}',
+            'types.d.ts': 'export declare function load(): void',
+            '01-real.mjs': scriptSource('real', '__orderIgnore'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['01-real']);
+    });
+    it('缺 cleanup 导出直接抛错（只写 load 的脚本等于「数据删不掉」）', async () => {
+        const dir = await makeDirectory({
+            '01-bad.mjs': 'export function load() {}',
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/缺少 cleanup 导出/);
+    });
+    it('缺 load 导出直接抛错', async () => {
+        const dir = await makeDirectory({
+            '01-bad.mjs': 'export function cleanup() {}',
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/缺少 load 导出/);
+    });
+    it('装载期抛错时带上文件名（定位不要靠猜）', async () => {
+        const dir = await makeDirectory({
+            '01-broken.mjs': 'throw new Error("boom")',
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/装载 "01-broken.mjs" 失败/);
+    });
+    it('dependsOn 缺省时按文件名升序', async () => {
+        const dir = await makeDirectory({
+            '02-b.mjs': scriptSource('b', '__orderNoDep'),
+            '01-a.mjs': scriptSource('a', '__orderNoDep'),
+        });
+        await expect(discoverTestDataModules(dir)).resolves.toMatchObject([{ name: '01-a' }, { name: '02-b' }]);
+    });
+    it('dependsOn 决定顺序：依赖在前，文件名管不了它', async () => {
+        const dir = await makeDirectory({
+            '01-late.mjs': `export const dependsOn = ['99-early']\n${scriptSource('late', '__orderDep')}`,
+            '99-early.mjs': scriptSource('early', '__orderDep'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['99-early', '01-late']);
+    });
+    it('同层按文件名升序（无依赖关系的脚本可复现）', async () => {
+        const dir = await makeDirectory({
+            '03-c.mjs': `export const dependsOn = ['01-base']\n${scriptSource('c', '__orderTie')}`,
+            '02-b.mjs': `export const dependsOn = ['01-base']\n${scriptSource('b', '__orderTie')}`,
+            '01-base.mjs': scriptSource('base', '__orderTie'),
+        });
+        const units = await discoverTestDataModules(dir);
+        expect(units.map((unit) => unit.name)).toEqual(['01-base', '02-b', '03-c']);
+    });
+    it('依赖不存在的脚本直接抛错', async () => {
+        const dir = await makeDirectory({
+            '01-a.mjs': `export const dependsOn = ['99-missing']\n${scriptSource('a', '__orderMissing')}`,
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/依赖的 "99-missing" 不存在/);
+    });
+    it('依赖自己直接抛错', async () => {
+        const dir = await makeDirectory({
+            '01-a.mjs': `export const dependsOn = ['01-a']\n${scriptSource('a', '__orderSelf')}`,
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/依赖了自己/);
+    });
+    it('循环依赖直接抛错（不猜顺序）', async () => {
+        const dir = await makeDirectory({
+            '01-a.mjs': `export const dependsOn = ['02-b']\n${scriptSource('a', '__orderCycle')}`,
+            '02-b.mjs': `export const dependsOn = ['01-a']\n${scriptSource('b', '__orderCycle')}`,
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/循环依赖/);
+    });
+    it('dependsOn 不是字符串数组直接抛错', async () => {
+        const dir = await makeDirectory({
+            '01-a.mjs': `export const dependsOn = [1]\n${scriptSource('a', '__orderType')}`,
+        });
+        await expect(discoverTestDataModules(dir)).rejects.toThrow(/dependsOn 必须是字符串数组/);
+    });
+});
+/** 造一批内存脚本单元（不经磁盘，专测执行语义） */
+function unitsOf(order, names) {
+    return names.map((name) => ({
+        name,
+        load: () => {
+            order.push(`load:${name}`);
+        },
+        cleanup: () => {
+            order.push(`cleanup:${name}`);
+        },
+    }));
+}
+describe('testdata 执行语义', () => {
+    it('load 正序、cleanup 逆序', async () => {
+        const order = [];
+        const units = unitsOf(order, ['a', 'b', 'c']);
+        await loadTestData({ env: 'test', units });
+        expect(order).toEqual(['load:a', 'load:b', 'load:c']);
+        order.length = 0;
+        await cleanupTestData({ env: 'test', units });
+        expect(order).toEqual(['cleanup:c', 'cleanup:b', 'cleanup:a']);
+    });
+    it('reset 先整体 cleanup（逆序）再整体 load（正序）', async () => {
+        const order = [];
+        const units = unitsOf(order, ['a', 'b']);
+        await resetTestData({ env: 'test', units });
+        // 分两趟而不是「逐脚本 cleanup + load」：后者会让前一个脚本刚插入的数据
+        // 被后一个脚本的 cleanup 顺手删掉（顺序依赖）。
+        expect(order).toEqual(['cleanup:b', 'cleanup:a', 'load:a', 'load:b']);
+    });
+    it('执行器自己按 dependsOn 定序，不信任调用方传入的顺序', async () => {
+        const order = [];
+        const units = [
+            { name: '01-late', dependsOn: ['99-early'], load: () => { order.push('load:late'); }, cleanup: () => { order.push('cleanup:late'); } },
+            { name: '99-early', load: () => { order.push('load:early'); }, cleanup: () => { order.push('cleanup:early'); } },
+        ];
+        await loadTestData({ env: 'test', units });
+        expect(order).toEqual(['load:early', 'load:late']);
+        order.length = 0;
+        await cleanupTestData({ env: 'test', units });
+        expect(order).toEqual(['cleanup:late', 'cleanup:early']);
+    });
+    it('没有脚本时三个入口都是空操作（但闸门照样生效）', async () => {
+        await expect(loadTestData({ env: 'test' })).resolves.toBeUndefined();
+        await expect(cleanupTestData({ env: 'development' })).resolves.toBeUndefined();
+        await expect(resetTestData({ env: 'test' })).resolves.toBeUndefined();
+    });
+    it.each([
+        ['loadTestData', loadTestData],
+        ['cleanupTestData', cleanupTestData],
+        ['resetTestData', resetTestData],
+    ])('%s：脚本失败直接冒泡（不降级成「跳过这条」）', async (_name, run) => {
+        const order = [];
+        const units = [
+            { name: 'ok', load: () => { order.push('load:ok'); }, cleanup: () => { order.push('cleanup:ok'); } },
+            { name: 'broken', load: () => { throw new Error('insert failed'); }, cleanup: () => { throw new Error('delete failed'); } },
+        ];
+        await expect(run({ env: 'test', units })).rejects.toThrow(/failed/);
+    });
+});
+describe('testdata 的环境闸门', () => {
+    const units = (order) => unitsOf(order, ['a']);
+    it.each([
+        ['loadTestData', loadTestData],
+        ['cleanupTestData', cleanupTestData],
+        ['resetTestData', resetTestData],
+    ])('%s：非可清理环境一个脚本都不跑', async (_name, run) => {
+        const order = [];
+        await expect(run({ env: 'production', units: units(order) })).rejects.toThrow(/拒绝在 ENV=/);
+        expect(order).toEqual([]);
+    });
+    it.each(['production', 'staging', ''])('ENV=%s 时拒绝，报错带上当前值', async (env) => {
+        await expect(loadTestData({ env })).rejects.toThrow(/ENV="/);
+    });
+    it.each(['development', 'test'])('ENV=%s 时放行', async (env) => {
+        const order = [];
+        await loadTestData({ env, units: units(order) });
+        expect(order).toEqual(['load:a']);
+    });
+    it('闸门先于一切：没有脚本也要在非可清理环境下失败', async () => {
+        await expect(resetTestData({ env: 'production' })).rejects.toThrow(/ENV="production"/);
+    });
+    it('判据是传入的 env 参数，不是 process.env（事后改写不影响结论）', async () => {
+        const order = [];
+        process.env.ENV = 'production';
+        await loadTestData({ env: 'test', units: units(order) });
+        expect(order).toEqual(['load:a']);
+    });
+});
+describe('resolveTestDataDirectory', () => {
+    it('默认是 <cwd>/testdata', () => {
+        expect(resolveTestDataDirectory()).toBe(join(process.cwd(), 'testdata'));
+    });
+});