@taicode/common-server 3.8.0 → 4.0.0-beta.10

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

@@ -0,0 +1,296 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineServer } from '../entries.js';
+import { routerSchema } from '../modules/schema/builders.js';
+import { defineResource } from '../resource.js';
+import { createTestServer } from './test-server.js';
+const IDENTITY = { service: 'probe', title: 'Probe', version: '0.0.0' };
+const ROUTE_SCHEMA = routerSchema({
+    operationId: 'probeGet',
+    summary: '探测',
+    description: '探测路由',
+    tags: ['探测'],
+});
+const APP_URL = 'postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=probe';
+const TEST_URL = 'postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=probe_test';
+const ORIGINAL_ENV = { ...process.env };
+afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+});
+function buildServer(seen = {}) {
+    return defineServer({
+        app: IDENTITY,
+        resources: (ctx) => {
+            seen.databaseUrl = ctx.env.DATABASE_URL;
+            seen.env = ctx.env.ENV;
+            return {};
+        },
+        config: () => ({ server: { cookieNames: ['token'] } }),
+        clients: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: ({ app }) => {
+            app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+        },
+    });
+}
+/** 把 vitest 自己设的环境变量清干净，让每个用例只看到自己注入的值 */
+function useEnv(overrides) {
+    process.env.ENV = 'development';
+    // 注意：给 process.env 赋 undefined 会变成字符串 "undefined"，所以必须先 delete
+    delete process.env.DATABASE_URL;
+    delete process.env.TEST_DATABASE_URL;
+    process.env.LOG_LEVEL = 'silent';
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined) {
+            delete process.env[key];
+        }
+        else {
+            process.env[key] = value;
+        }
+    }
+}
+describe('createTestServer', () => {
+    it('与 startServer 装配同一套处理链：系统路由 + 业务路由 + zod 序列化 + 成功信封', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const testServer = await createTestServer(buildServer());
+        const response = await testServer.app.inject({ method: 'GET', url: '/probe' });
+        expect(response.statusCode).toBe(200);
+        // 信封形状来自框架 core/response，而不是测试自己拼的一份
+        expect(response.json()).toEqual({ status: 'SUCCESS', message: 'ok', data: { ok: true } });
+        // 框架系统路由同样就位
+        expect((await testServer.app.inject({ method: 'GET', url: '/health' })).statusCode).toBe(200);
+        await testServer.app.close();
+    });
+    it('数据层被结算到 *_test（resources 从 ctx.env 拿到的就是测试目标），且不改写全局 process.env', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const seen = {};
+        const testServer = await createTestServer(buildServer(seen));
+        // resources 从 `ctx.env.DATABASE_URL` 读到的是结算后的测试目标
+        expect(seen.databaseUrl).toContain('schema=probe_test');
+        // 交出来的连接串就是「测试实际连的那个」，不是从 process.env 再推一遍
+        expect(testServer.env.DATABASE_URL).toBe(seen.databaseUrl);
+        // **不改写全局 process.env.DATABASE_URL**：测试目标只属于本次装配，避免同进程并行串扰
+        expect(process.env.DATABASE_URL).toBe(APP_URL);
+        await testServer.app.close();
+    });
+    it('显式 TEST_DATABASE_URL 优先于派生', async () => {
+        useEnv({
+            DATABASE_URL: APP_URL,
+            TEST_DATABASE_URL: TEST_URL.replace('probe_test', 'explicit_test'),
+        });
+        const seen = {};
+        const testServer = await createTestServer(buildServer(seen));
+        expect(seen.databaseUrl).toContain('schema=explicit_test');
+        await testServer.app.close();
+    });
+    it('不监听端口（测试用 inject，占端口会让重跑互相踩）', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const testServer = await createTestServer(buildServer());
+        expect(testServer.app.server.listening).toBe(false);
+        await testServer.app.close();
+    });
+    it('env 强制加载测试层：ENV 没人给时兜底成 test（不用调用方额外声明）', async () => {
+        useEnv({ DATABASE_URL: APP_URL, ENV: undefined });
+        const seen = {};
+        const testServer = await createTestServer(buildServer(seen));
+        expect(seen.env).toBe('test');
+        await testServer.app.close();
+    });
+    it('环境闸门：非可清理环境在装配之前就失败（resources 一次都没跑）', async () => {
+        useEnv({ DATABASE_URL: APP_URL, ENV: 'production' });
+        const onResources = vi.fn(buildServer().resources);
+        const server = defineServer({ ...buildServer(), resources: onResources });
+        await expect(createTestServer(server)).rejects.toThrow(/ENV="production"/);
+        expect(onResources).not.toHaveBeenCalled();
+    });
+    it('schema 闸门：目标不以 *_test 结尾时拒绝装配', async () => {
+        useEnv({ DATABASE_URL: APP_URL, TEST_DATABASE_URL: APP_URL });
+        const onResources = vi.fn(buildServer().resources);
+        const server = defineServer({ ...buildServer(), resources: onResources });
+        await expect(createTestServer(server)).rejects.toThrow(/必须以 _test 结尾/);
+        expect(onResources).not.toHaveBeenCalled();
+    });
+    it('关闭时走同一套八步流程（services 的 dispose 被调用）', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const onDispose = vi.fn();
+        const server = defineServer({
+            ...buildServer(),
+            services: () => ({ unit: { dispose: onDispose } }),
+        });
+        const testServer = await createTestServer(server);
+        await testServer.app.close();
+        expect(onDispose).toHaveBeenCalledTimes(1);
+    });
+    it('业务路由缺少 schema 时注册即失败（守卫在测试入口同样生效）', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const server = defineServer({
+            ...buildServer(),
+            routers: ({ app }) => {
+                app.get('/bad', async () => ({ ok: true }));
+            },
+        });
+        await expect(createTestServer(server)).rejects.toThrow(/GET \/bad 缺少 schema/);
+    });
+    it('返回装配产物本身：resources / config / clients / services 与槽位一一对应', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const resources = { cache: { get: () => undefined } };
+        const config = { server: { cookieNames: ['token'] } };
+        const clients = { account: { verify: async () => true } };
+        const services = { user: { name: () => 'user' } };
+        const testServer = await createTestServer(defineServer({
+            app: IDENTITY,
+            resources: () => resources,
+            config: () => config,
+            clients: () => clients,
+            services: () => services,
+            middlewares: () => [],
+            routers: () => { },
+        }));
+        // 装配产物直接交出来：测试能断言/操作它们本身，而不是再构造一份副本。
+        // `resources` / `clients` 经过 `Live<T>` 视图（剔 `false` 键），所以按值比较；
+        // `config` / `services` 就是槽位原始返回值，引用相同。
+        expect(testServer.resources).toEqual(resources);
+        expect(testServer.clients).toEqual(clients);
+        expect(testServer.config).toBe(config);
+        expect(testServer.services).toBe(services);
+        // env 是**改写后**的快照（resources 看到的就是它）
+        expect(testServer.env.DATABASE_URL).toContain('schema=probe_test');
+        await testServer.app.close();
+    });
+    it('只有定义一个参数：没有「半个生产」的配置入口', () => {
+        // 签名只有一个必填参数。这条断言盯着「别再加 options」——一旦加了，测试就能绕开
+        // 生产接线，本入口随即失去证明力。
+        expect(createTestServer.length).toBe(1);
+    });
+    it('不复位入口只留 reprovision 一个：flushServices / resetTestData 都已移除', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const testServer = await createTestServer(buildServer());
+        expect('flushServices' in testServer).toBe(false);
+        expect('resetTestData' in testServer).toBe(false);
+        expect('cleanServerData' in testServer).toBe(false);
+        expect(typeof testServer.reprovision).toBe('function');
+        await testServer.app.close();
+    });
+    it('不外漏装配层产物：resourceUnits 只活在闭包里', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const server = defineServer({
+            ...buildServer(),
+            resources: () => ({
+                database: defineResource({ marker: 'db' }, { clean: () => { } }),
+            }),
+        });
+        const testServer = await createTestServer(server);
+        // `ResourceSetupUnit[]` 是 boot 层的产物；把它挂在测试对象上等于把下层的实现细节
+        // 变成公开契约，测试就能绕过 `reprovision()` 自己编排清理。
+        expect('resourceUnits' in testServer).toBe(false);
+        // `testData`（已发现的脚本名单）同理：它是装配期的中间产物，唯一用法是「再来一遍基线」，
+        // 而那件事就是 `reprovision()`。外面既没有 `loadTestData` 可以拿它做什么，也没有第二个入口
+        // 需要它——挂出去只会让人以为「我该自己编排装载顺序」。
+        expect('testData' in testServer).toBe(false);
+        expect(Object.keys(testServer).sort()).toEqual(['app', 'clients', 'config', 'env', 'log', 'reprovision', 'resources', 'services']);
+        await testServer.app.close();
+    });
+});
+describe('TestServer.reprovision', () => {
+    it('清完数据再关旧实例：clean() 一定跑在 dispose() 之前（连接还在）', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const order = [];
+        const server = defineServer({
+            ...buildServer(),
+            resources: () => ({
+                database: defineResource({ marker: 'db' }, {
+                    clean: () => { order.push('clean:database'); },
+                    dispose: () => { order.push('dispose:database'); },
+                }),
+            }),
+            services: () => ({
+                cache: {
+                    clean: () => { order.push('clean:cache'); },
+                    dispose: () => { order.push('dispose:cache'); },
+                },
+            }),
+        });
+        const first = await createTestServer(server);
+        const second = await first.reprovision();
+        // 资源声明序 → 服务声明序 → 八步关闭（dispose 逆序）
+        expect(order).toEqual(['clean:database', 'clean:cache', 'dispose:cache', 'dispose:database']);
+        // 旧 app 已关（再 inject 会失败），新 app 可用
+        await expect(first.app.inject({ method: 'GET', url: '/health' })).rejects.toThrow();
+        expect((await second.app.inject({ method: 'GET', url: '/health' })).statusCode).toBe(200);
+        await second.app.close();
+    });
+    it('返回的是新实例：app / resources / services 全部换新，env 快照复用', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        let built = 0;
+        const server = defineServer({
+            ...buildServer(),
+            services: () => {
+                built += 1;
+                return { unit: { id: built } };
+            },
+        });
+        const first = await createTestServer(server);
+        const second = await first.reprovision();
+        expect(second).not.toBe(first);
+        expect(second.app).not.toBe(first.app);
+        expect(second.services).not.toBe(first.services);
+        expect(second.services).toEqual({ unit: { id: 2 } });
+        // env 是同一份快照（不重跑 prepareTestDatabase）
+        expect(second.env).toBe(first.env);
+        await second.app.close();
+    });
+    it('clean() 失败冒泡：不会去装配、也不会留下半开的世界', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        let assembled = 0;
+        const server = defineServer({
+            ...buildServer(),
+            resources: () => ({
+                database: defineResource({ marker: 'db' }, {
+                    clean: () => { throw new Error('truncate failed'); },
+                }),
+            }),
+            services: () => {
+                assembled += 1;
+                return {};
+            },
+        });
+        const testServer = await createTestServer(server);
+        await expect(testServer.reprovision()).rejects.toThrow(/truncate failed/);
+        // 失败发生在装配之前：services 只被构造过一次
+        expect(assembled).toBe(1);
+        await testServer.app.close();
+    });
+    it('app.close() 失败不阻断：clean 已跑完，仍然会重新装配', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const order = [];
+        const server = defineServer({
+            ...buildServer(),
+            resources: () => ({
+                database: defineResource({ marker: 'db' }, {
+                    clean: () => { order.push('clean'); },
+                    dispose: () => { throw new Error('dispose failed'); },
+                }),
+            }),
+        });
+        const first = await createTestServer(server);
+        const second = await first.reprovision();
+        expect(order).toEqual(['clean']);
+        expect((await second.app.inject({ method: 'GET', url: '/health' })).statusCode).toBe(200);
+        await second.app.close();
+    });
+    it('环境闸门：非可清理环境下连 clean() 都不跑', async () => {
+        useEnv({ DATABASE_URL: APP_URL });
+        const onClean = vi.fn();
+        const server = defineServer({
+            ...buildServer(),
+            resources: () => ({
+                database: defineResource({ marker: 'db' }, { clean: onClean }),
+            }),
+        });
+        const testServer = await createTestServer(server);
+        testServer.env.ENV = 'production';
+        await expect(testServer.reprovision()).rejects.toThrow(/ENV="production"/);
+        expect(onClean).not.toHaveBeenCalled();
+        await testServer.app.close();
+    });
+});

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

@@ -0,0 +1,255 @@
+import type { AppEnv, ClientsView, LoggerLike, ResourcesView, Server } from '../types.js';
+/**
+ * **测试数据（testdata）机制**：`packages/server/testdata/*.ts|js` 下的脚本，在 `development` /
+ * `test` 启动时自动加载，并在用例之间被重新加载。
+ *
+ * ## 为什么是「目录 + 约定方法」，而不是资源上的生命周期
+ *
+ * 「这条用例需要哪些样本数据」与「这份数据怎么删掉」是**同一件事的正反面**，写在同一个文件里
+ * 才不容易漏。把 `cleanup` 挂到资源单元上做不到这一点：资源只知道「有哪些表 / 哪些 key」，
+ * 不知道「谁往里写了什么」——新增一个 model 就要回去改一次清库清单，漏改只会安静地变脏。
+ *
+ * 所以机制倒过来：**数据脚本自己负责自己**。
+ *
+ * ```ts
+ * // packages/server/testdata/01-base.ts（推荐写法）
+ * import { defineTestData } from '@taicode/common-server/app'
+ * import type { AppResources } from '../source/resources'
+ *
+ * export default defineTestData<AppResources>({
+ *   async load(ctx) { …插入样本数据… },
+ * })
+ * ```
+ *
+ * 命名导出 `load(ctx)` / `cleanup(ctx)`（+ 可选 `dependsOn`）继续支持；两者都有时默认导出优先。
+ *
+ * ## 契约（只有三条）
+ *
+ * 1. **目录固定**：`<cwd>/testdata`（`tsx watch ./source/index.ts` 与 `vitest` 的 cwd 都是
+ *    `packages/server`）。目录不存在 = 没有脚本。
+ * 2. **`load` 必需，`cleanup` 可选**：只写 `load` 的脚本是**合法**的——它的数据由资源单元的
+ *    `clean()`（典型实现 `TRUNCATE ... CASCADE`）在重装前清掉。需要「资源清不掉的东西」
+ *    （下游 mock 预置、临时文件）时才写 `cleanup`。
+ * 3. **顺序**：文件名（字典序升序）是默认序；需要「我必须排在某脚本之后」时用
+ *    `dependsOn` 显式声明，见下节。
+ *
+ * ## 顺序：`dependsOn` 是权威，文件名只做同层破平
+ *
+ * ```ts
+ * // packages/server/testdata/02-organization.ts
+ * import { defineTestData } from '@taicode/common-server/app'
+ *
+ * export default defineTestData({
+ *   dependsOn: ['01-database'],
+ *   async load(ctx) { … },
+ * })
+ * ```
+ *
+ * - **引用名 = 去扩展名的文件名**（`01-base.ts` → `'01-base'`），与 `TestDataUnit.name` 一致。
+ * - **只影响顺序，不注入任何东西**：声明依赖**不会**把前一个脚本的客户端/数据递给你——需要共享
+ *   资源时用 `ctx.resources`（框架注入的装配产物），而不是依赖另一个脚本。
+ * - **`cleanup` 不用声明**：它是装配序的逆序，依赖自动反向成立（后建的先拆）。
+ * - **同层按文件名升序**：没有依赖关系的脚本之间的相对顺序由文件名决定，结果确定可复现。
+ * - **缺依赖 / 自依赖 / 环一律报错**（不是跳过、不是猜测顺序）：顺序是安全属性，猜错只会
+ *   变成偶发的外键冲突。
+ *
+ * 为什么要有这个字段：数字前缀是「顺序的替身」，中间插一个脚本就得重命名后面全部文件——
+ * 纯噪音改动，还会切断 git 历史。依赖声明让「谁必须在谁之后」贴着原因写。
+ *
+ * > 字段名与已删除的**模块装配期** `dependsOn`（连同 `validateLifecycleDependencies`，§11-2）
+ * > 无关：那个是资源/模块之间的构造依赖，这个是数据脚本之间的**执行顺序**。
+ *
+ * ## 两条与「安全」有关的约定
+ *
+ * - **`_` 开头的文件不是脚本**：它们是脚本之间共享的 helper（`_client.ts`），不会被 `load` /
+ *   `cleanup`。否则扫描目录就会把工具文件也当成脚本执行。
+ * - **只在可清理环境执行**：`load` / `cleanup` 两个执行入口的**第 0 步**都是
+ *   `assertCleanableEnvironment(ctx.env.ENV)`。判据是装配期的 `ctx.env` 快照（事后改写
+ *   `process.env` 不影响结论）。
+ *
+ * ## 执行顺序与失败语义
+ *
+ * | 入口 | 顺序 | 失败 |
+ * | --- | --- | --- |
+ * | `loadTestData` | **执行序**（`dependsOn` 拓扑序，同层按文件名升序） | 立即冒泡 |
+ * | `cleanupTestData` | **执行序逆序**（无 `cleanup` 的脚本跳过） | 立即冒泡 |
+ *
+ * `cleanup` 逆序是「后建的先拆」，依赖因此不必反向声明。
+ *
+ * 失败**一律冒泡**，不降级成「跳过这条脚本」：数据没准备好时静默继续只会让后续用例读到脏状态，
+ * 制造伪绿。
+ *
+ * ## 脚本拿到什么：`ctx`
+ *
+ * 脚本不再自己读 env、不再自己建连接——框架把装配好的东西注入进来。`load` 跑在
+ * `app.ready()` 之后、`listen` 之前，所以装配产物**全部已经存在**：
+ *
+ * | 字段 | 是什么 | 为什么给 |
+ * | --- | --- | --- |
+ * | `env` | 装配快照 `AppEnv<Env>` | 脚本不碰 `process.env`；看到的就是应用看到的那份 |
+ * | `resources` | `ResourcesView<Resources>`（单元已解包） | 脚本写数据的地方就是被测服务读数据的地方 |
+ * | `config` | 启动期配置快照 `Awaited<Config>`（只读） | 有些基线必须以配置为输入（按配置里的管理员名单造账号） |
+ * | `clients` | `ClientsView<Clients>` | 预置 / 清理下游 mock 状态的唯一正当通道 |
+ * | `services` | `Awaited<Services>`（已 `init()`） | 走服务造数据才会自动满足业务不变量（哈希、缓存失效、审计） |
+ * | `log` | `ctx.log` | 日志与装配期同一路输出 |
+ *
+ * 「脚本自己建一份客户端」是**错的**：同一份数据经两条连接写/读，缓存与连接级状态对不上
+ * （account 曾经的 `globalThis` 重置注册表就是这个坑的产物）。所以注入 `resources` 是结构性的，
+ * 不是便利。
+ *
+ * **为什么不给 `app`**：拿到 `app` 就能 `inject()`，等于「跑一条业务链路来造数据」。那会一次性
+ * 引入中间件链（鉴权 / 限流 / requestId）、响应信封与错误映射，让基线脚本的失败语义、执行顺序、
+ * 耗时全部失控——而这三样正是 `dependsOn` 与「失败直接冒泡」想守住的东西。要跑链路请写在用例里。
+ *
+ * ## 三条使用边界
+ *
+ * 1. **首选 `resources`，`services` 只在「必须满足业务不变量」时用**，并在文件头写明原因。
+ *    同一个目录里一半 raw write、一半走 service，数据形状迟早会不一致。
+ * 2. **`config` 是快照**：脚本写配置表**不会**刷新当前实例的 `ctx.config`，要生效只能重新装配。
+ * 3. **`clients` 只用于预置 / 清理下游 mock**：`development` 会跑同一批脚本，误发就是真的发出去了。
+ */
+export interface TestDataContext<Resources = object, Env = object, Config = object, Clients = object, Services = object> {
+    /** 本次装配的 env 快照（框架固定约定 + 应用扩展字段）；脚本**不必也不该**再读 `process.env` */
+    readonly env: AppEnv<Env>;
+    /** 装配好的资源（单元已解包）：写数据 / 清缓存都用它，而不是另建一份客户端 */
+    readonly resources: ResourcesView<Resources>;
+    /** 启动期配置快照（只读）：写配置表不会刷新它，要生效需重新装配 */
+    readonly config: Awaited<Config>;
+    /** 外部客户端：只用于预置 / 清理下游 mock，不得产生真实外部副作用 */
+    readonly clients: ClientsView<Clients>;
+    /** 已 `init()` 完成的服务实例：走它造数据才会满足业务不变量 */
+    readonly services: Awaited<Services>;
+    /** 记录型 logger（与装配期同一个） */
+    readonly log: LoggerLike;
+}
+/** 一个测试数据脚本（`testdata/*.ts` 的约定导出） */
+export interface TestDataScript<Resources = object, Env = object, Config = object, Clients = object, Services = object> {
+    /** 加载本脚本负责的测试数据（可重复执行） */
+    load(ctx: TestDataContext<Resources, Env, Config, Clients, Services>): void | Promise<void>;
+    /**
+     * 清理本脚本负责的测试数据（可选）。
+     *
+     * **大多数脚本不需要它**：内存数据库的行由资源单元的 `clean()`（典型实现
+     * `TRUNCATE ... CASCADE`）在重新装配前清掉。只有「资源清不掉的东西」才需要自己写
+     * `cleanup`——下游 mock 的预置状态、临时文件、外部队列的 key。
+     *
+     * 提供时必须能把 `load()` 的效果完全撤销；不提供时重装前由资源兜底。
+     */
+    cleanup?(ctx: TestDataContext<Resources, Env, Config, Clients, Services>): void | Promise<void>;
+    /**
+     * 必须在哪些脚本**之后**执行（去扩展名的文件名；缺省 = 无要求）。
+     *
+     * 只影响排序：`load` 按依赖拓扑序（同层按文件名升序），`cleanup` 取其逆序。
+     * 校验严格：引用不存在的脚本、引用自己、循环依赖都会让装载阶段**抛错**。
+     */
+    readonly dependsOn?: readonly string[];
+}
+/** `defineTestData()` 的入参：与 `TestDataScript` 同形（只有 `load` 必需） */
+export type TestDataDefinition<Resources = object, Env = object, Config = object, Clients = object, Services = object> = TestDataScript<Resources, Env, Config, Clients, Services>;
+/**
+ * 由**一个** `Server` 类型推出脚本类型（`defineTestData<typeof server>({ … })` 用的就是这个）。
+ *
+ * 五个槽位泛型本来要一个个手写、顺序还得对上（`Resources, Env, Config, Clients, Services` 与
+ * `Server` 的 `Resources, Config, Clients, Services, Env` 不同序）；直接给 `server` 就没这个问题：
+ * 写错泛型名会当场报错，而不是静默拿到 `object`。
+ *
+ * 非 `Server` 类型（如直接传 `AccountResources`）退化为「只声明 `resources`」的老写法。
+ */
+export type TestDataScriptOf<S, Env = object> = S extends Server<infer Resources, infer Config, infer Clients, infer Services, infer AppEnvShape> ? TestDataScript<Resources, AppEnvShape, Config, Clients, Services> : TestDataScript<S, Env>;
+/** `defineTestData<S>()` 的入参（`TestDataScriptOf` 的别名，语义更贴近调用处） */
+export type TestDataDefinitionOf<S, Env = object> = TestDataScriptOf<S, Env>;
+/**
+ * 声明一个测试数据脚本（**唯一正当的写法**）。
+ *
+ * ```ts
+ * // packages/server/testdata/03-system-config.ts
+ * import { defineTestData } from '@taicode/common-server/app'
+ * import type { server } from '../source/server' // 纯类型导入，无副作用
+ *
+ * export default defineTestData<typeof server>({
+ *   dependsOn: ['01-database'],
+ *   async load(ctx) { …插入样本数据… },
+ *   async cleanup(ctx) { …删掉自己插入的数据… },
+ * })
+ * ```
+ *
+ * 泛型写 `typeof server` 而不是逐个槽位：`ctx` 上的 `resources` / `config` / `clients` /
+ * `services` / `env` 类型一次到位。只想声明 `resources` 时也可以写
+ * `defineTestData<AccountResources>({ … })`（其余槽位退化为 `object`）。
+ *
+ * ## 它解决什么
+ *
+ * 命名导出 `load` 是**约定**，写错只在装载期才会暴露（少写 `load` = 启动直接失败）。
+ * `defineTestData` 把这份约定变成**定义期**就检查的东西：
+ *
+ * 1. **缺 `load` 当场报错**（不是等到 `discoverTestDataModules()` 扫描到它）；
+ * 2. **`dependsOn` 当场校验**（必须是字符串数组、不能有重复项；引用不存在的脚本 / 自依赖 /
+ *    环属于跨文件问题，仍在装载期由 `sortByDependencies()` 统一判定）；
+ * 3. **结果冻结**：脚本之间不会互相改写 `load` / `cleanup`（执行器拿到的就是定义时那份）。
+ *
+ * `ctx` 的类型由 `S` 一次性带进来：`defineTestData<typeof server>({ load(ctx) {…} })` 里
+ * `ctx.services` / `ctx.resources` / `ctx.config` 全部有类型，不需要每个脚本再手写
+ * `type Ctx = TestDataContext<…>`。
+ *
+ * ## 与「命名导出」的关系
+ *
+ * 两种写法都合法，`defineTestData` 只是把结构显式化：
+ *
+ * ```ts
+ * // 推荐：默认导出一个定义对象
+ * export default defineTestData<typeof server>({ load })
+ *
+ * // 等价：命名导出（旧写法，继续支持）
+ * export async function load(ctx: TestDataContext<AccountResources>) { … }
+ * export const dependsOn = ['01-database']
+ * ```
+ *
+ * 同一个文件里两者都有时，**默认导出优先**——避免「改了默认导出、命名导出还在生效」的歧义。
+ */
+export declare function defineTestData<S = object, Env = object>(definition: TestDataDefinitionOf<S, Env>): TestDataScriptOf<S, Env>;
+/** 一个已从磁盘装载好的脚本单元（含名字，用于日志与报错定位） */
+export interface TestDataUnit<Resources = object, Env = object, Config = object, Clients = object, Services = object> extends TestDataScript<Resources, Env, Config, Clients, Services> {
+    /** 脚本文件名去掉扩展名（`01-base.ts` → `01-base`） */
+    readonly name: string;
+}
+/** 两个执行入口的共同入参 */
+export interface TestDataRunParams<Resources = object, Env = object, Config = object, Clients = object, Services = object> {
+    /**
+     * 本次装配的 ctx（`env` + `resources` + `config` + `clients` + `services` + `log`）。**必填**：
+     *
+     * - 闸门读 `ctx.env.ENV`：非 `CLEANABLE_ENVS`（`development` / `test`）一律抛错，一个脚本都不跑；
+     * - 脚本拿到的就是这份 ctx，所以它看到的环境 / 资源与本次装配完全一致。
+     */
+    ctx: TestDataContext<Resources, Env, Config, Clients, Services>;
+    /** 已装载的脚本（`discoverTestDataModules()` 的产物）；缺省 = 没有脚本 */
+    units?: readonly TestDataUnit<Resources, Env, Config, Clients, Services>[];
+    /** 日志标签（`defineServer({ app: { service } })`） */
+    service?: string;
+}
+/** 默认脚本目录（相对 `process.cwd()`） */
+export declare function resolveTestDataDirectory(): string;
+/**
+ * 扫描目录并**装载**全部脚本（`import()` 一次，模块本身由 ESM 缓存复用）。
+ *
+ * 目录不存在 → 空数组（不是错误：没写测试数据的服务是合法的）。
+ * 文件存在但缺 `load` → **抛错**，并指出是哪个文件。
+ *
+ * 返回的顺序就是**执行序**：`dependsOn` 拓扑序 + 同层文件名升序（`load` 直接正序跑，
+ * `cleanup` 直接逆序跑）。
+ */
+export declare function discoverTestDataModules<Resources = object, Env = object, Config = object, Clients = object, Services = object>(directory?: string): Promise<TestDataUnit<Resources, Env, Config, Clients, Services>[]>;
+/**
+ * 加载测试数据：按**执行序**逐项 `await load(ctx)`（依赖在前，同层按文件名升序）。
+ *
+ * 在 `createTestServer()` / `startServer()` 装配完成后自动执行一次；也可以由测试自己再调。
+ */
+export declare function loadTestData<Resources, Env, Config, Clients, Services>(params: TestDataRunParams<Resources, Env, Config, Clients, Services>): Promise<void>;
+/**
+ * 清理测试数据：按执行序**逆序**逐项 `await cleanup()`（后建的先拆）。
+ *
+ * 依赖不必反向声明：`load` 的拓扑序取逆就是安全的拆除序。没有 `cleanup` 的脚本直接跳过。
+ *
+ * 注意：它只负责「把脚本插入的东西撤掉」，不是「把整个库清空」——库由资源单元的 `clean()` 清。
+ */
+export declare function cleanupTestData<Resources, Env, Config, Clients, Services>(params: TestDataRunParams<Resources, Env, Config, Clients, Services>): 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":"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"}