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

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

@@ -0,0 +1,154 @@
+import type { AppEnv, ClientsView, LoggerLike, ResourcesView, Server } from '../types.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * `createTestServer()` ——**测试对象的唯一构造方式**。
+ *
+ * ## 它是唯一的一个，不是「又一个」入口
+ *
+ * 这里有一个硬性约束：**测试必须跑在生产的同一套装配上**。请求链、响应信封、错误码映射、
+ * `request.ctx`、关闭流程，只要测试里另有一套实现，它就会在生产之外漂移，而漂移只在线暴露。
+ *
+ * 因此测试对象的构造只有一个入口，它**不接受任何槽位覆盖**：没有 `resources` 参数、没有
+ * `services` 参数、没有 `overrideXxx`。覆盖面一开，测试就能绕开生产接线，这个入口随即失去
+ * 全部证明力——那还不如直接写个假 app。
+ *
+ * 需要「只测一个模块」时，**组合定义**，而不是覆盖槽位：
+ *
+ * ```ts
+ * const moduleServer = defineServer({
+ *   ...server,
+ *   routers: ({ app }) => app.register(createUserRouter(stub)),
+ * })
+ * const testServer = await createTestServer(moduleServer)
+ * ```
+ *
+ * 组合用的是同一个 `defineServer` 产物、同一套装配，只是把另一个模块的接线换掉。
+ *
+ * ## 与 `startServer` 的唯一差别
+ *
+ * `startServer` 会 listen 并装信号处理器；测试用 `app.inject()`，且 vitest worker 收不到
+ * SIGTERM。除此之外（env 分层 → resources → config → clients → services → `init()` →
+ * middlewares → 系统路由 → routers、八步关闭）**逐行相同**。
+ *
+ * ## 参数就是那个 `Server`，没有第二个参数
+ *
+ * 连接串结算、闸门、改写 `DATABASE_URL` 全部固定（见 `prepareTestDatabase()`）。
+ * 没有「用哪个连接串」这类开关：测试对象的身份就是测试，让它可以被配置成「有点像测试」
+ * 是把安全前提变成调用方的责任。
+ *
+ * ## 返回值：`TestServer` 就是测试要的一切
+ *
+ * 测试要断言的对象往往不是 HTTP 响应，而是**装配出来的东西本身**：`resources.database` 连的
+ * 是不是 `*_test`、某个 service 有没有被 `dispose`、`config` 里那个开关有没有生效。
+ * 因此返回装配期**已经构造完成**的各槽位产物，而不是让调用方重新跑一遍工厂——重新构造就等于
+ * 测试里又拼了一份，与生产接线脱钩。
+ *
+ * **不包同义方法**：没有 `close()`、没有 `getDatabase()`。`app` 就是原生 `FastifyInstance`，
+ * 关闭就是 `await app.close()`，走同一套八步流程；连接串就是 `env.DATABASE_URL`。多包一层
+ * `close()` 只是在已有接口上再加一个同义名，反而让「用哪个」变成需要记的事。
+ *
+ * **唯一的例外是 `reprovision()`**：它不是现有接口的同义名，生产入口没有对应物——
+ * 「用例之间要一份干净基线」只有测试知道。
+ */
+export interface TestServer<Resources, Config, Clients, Services, Env> {
+    /** 原生 Fastify 实例（已 `ready()`，用 `inject` 发请求；关闭用 `app.close()`） */
+    readonly app: FastifyInstance;
+    /**
+     * 装配后的 env 快照（框架固定约定 + 应用声明的扩展字段 `Env`，`AppEnv<Env>`）。
+     *
+     * **测试断言「连的是哪个库」就看这里**：`env.DATABASE_URL` 在装配前已结算成 `*_test`
+     * 目标，它就是本次实际连的连接串。不额外给一个 `databaseUrl` 字段——同一份事实出现两次，
+     * 迟早会有人读到另一个。应用扩展的 env（如 `REDIS_KEY_PREFIX`）也在这里、且有类型。
+     */
+    readonly env: AppEnv<Env>;
+    /** `resources` 槽位产物（`false` 键已按 `Live<Value>` 剔除） */
+    readonly resources: ResourcesView<Resources>;
+    /** `config` 槽位产物（`Awaited<>` 归一） */
+    readonly config: Awaited<Config>;
+    /** `clients` 槽位产物 */
+    readonly clients: ClientsView<Clients>;
+    /** `services` 槽位产物（已 `init()` 过；测试直接拿它调方法，不 mock） */
+    readonly services: Awaited<Services>;
+    /** 日志器（与 `app.log` 同一个；关闭阶段仍可用） */
+    readonly log: LoggerLike;
+    /**
+     * **重新装配一个新的实例**：清掉旧实例的数据 → 关掉旧实例 → 按同一份 `env` 快照重跑一遍装配。
+     *
+     * 返回的是一份**新对象**，不是原地重启：
+     *
+     * ```ts
+     * let server = await createTestServer(server)
+     * beforeEach(async () => {
+     *   server = await server.reprovision()
+     * })
+     * ```
+     *
+     * 旧对象上的一切（`app` / `resources` / `services`）**已经失效**：连接已断、`app` 已 `close()`。
+     * 还在引用旧实例的 `describe` 报错时不要奇怪——它的名字就叫“旧装配”。
+     *
+     * ## 为什么是「重新装配」而不是「复位」
+     *
+     * 状态有两类，而只有一类能被「复位」：
+     *
+     * | 状态 | 在哪 | 能不能拨回去 |
+     * | --- | --- | --- |
+     * | 库里的行 / 队列 key / 临时文件 | 外部 | 能（`clean()`） |
+     * | 限流桶、进程内缓存、连接级状态 | 内存 | **不能可靠地拨回** |
+     *
+     * 第二类覆盖地方、无法可靠拨回（漏清一处就是偶发红），而重新装配不需要「谁记得清」：
+     * `init()` 重跑一次，内存态天然就是初始值。
+     *
+     * 另一层原因在 Fastify：`ready()` 是一次性的，同一实例上无法重跑注册流程。想「不换实例而重跑
+     * 装配」在结构上就不成立。
+     *
+     * ## 四个步骤（顺序不可换）
+     *
+     * 1. **闸门**：`ENV` 必须可清理（`development` / `test`），否则直接抛错；
+     * 2. **`clean()`**：由 boot 层的 `cleanServerUnits()` 编排——资源声明序逐项清（数据库那个
+     *    必须在最前，它持有 `TRUNCATE`），再服务声明序逐项清；**必须在 `app.close()` 之前**——
+     *    关完之后连接就没了；
+     * 3. **`app.close()`**：走完整八步关闭（逐单元 `dispose()` 会在这里顺带把缓冲落盘）；
+     * 4. **重新装配**：复用同一份 `env` 快照（**不重跑** `prepareTestDatabase()`），重建
+     *    `resources` → `config` → `clients` → `services` → `init()` → 路由 → `ready()` → `loadTestData()`。
+     *
+     * ## 失败语义
+     *
+     * - `clean()` 失败**冒泡**：没清干净就去装配，后面全是伪绿；
+     * - `app.close()` 失败**不阻断**（八步关闭本来就是逐步骤聚合、失败只 `log.error`）：
+     *   旧实例释放不完美不应该阻止下一条用例。
+     *
+     * ## 耗时
+     *
+     * 一次完整装配 = 一次 `setup()` + 一次 `init()`。这是**故意的约束**：`setup()` 必须保持在
+     * 几十毫秒量级（只做连接 / 预执 / 极小的结构检查），跑 `prisma migrate` 这类事归 npm script——
+     * `reprovision()` 是**逐用例**跑的，装配慢就等于整个测试套件慢。
+     */
+    reprovision(): Promise<TestServer<Resources, Config, Clients, Services, Env>>;
+}
+/**
+ * 构造测试对象。
+ *
+ * 固定顺序（安全闸门全部在装配之前，`resources` 一行代码都还没跑）：
+ * ```
+ * prepareTestDatabase()：
+ *   加载 env（强制叠加 .env.test / .env.test.local，ENV 未给时兜底 test）
+ *     → 环境闸门（ENV 必须可清理）
+ *     → 结算测试连接串（显式 TEST_DATABASE_URL 优先，否则派生 +_test，幂等）
+ *     → schema 闸门（必须以 _test 结尾）
+ *     → 回写 process.env.DATABASE_URL
+ * → resources → core → config → clients → services → init() → middlewares
+ *   → 系统路由 → routers → 关闭钩子 → ready()
+ *   → 装载 testdata/ 脚本并整体 load(ctx)
+ * ```
+ *
+ * `testdata/` 的 `load()` 排在 `ready()` 之后：脚本拿到的是装配好的 `ctx`（`env` + `resources` +
+ * `log`），所以它写数据用的就是被测服务读数据的那份连接——两套连接写/读同一张表而看不到对方
+ * 写入（缓存 / 连接级状态）这类问题从结构上不会发生。排在最后也让失败语义最干净：装载失败时
+ * 装配已完成、可正常 `app.close()` 释放。
+ *
+ * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于
+ * 「自比自」。真正拦住「测试清空应用库」的是派生 + schema 闸门——派生只会给 schema 追加
+ * `_test`，schema 闸门只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export declare function createTestServer<Resources, Config, Clients, Services, Env>(server: Server<Resources, Config, Clients, Services, Env>): Promise<TestServer<Resources, Config, Clients, Services, Env>>;
+//# sourceMappingURL=test-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"test-server.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/test-server.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,WAAW,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG;IACnE,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IACzB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IAC5C,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IAChC,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IACtC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpC,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACH,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAA;CAC9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,CAO3M"}

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

@@ -0,0 +1,114 @@
+import { cleanServerUnits, initServiceUnits } from '../boot/lifecycle.js';
+import { buildClients, buildConfig, buildResources, buildServices, createBootContext, installShutdownHook, registerCoreStep, registerMiddlewares, registerRouters, registerSystemRoutesStep, resolveAppEnv, setupResources, } from '../boot/steps.js';
+import { assertCleanableEnvironment } from '../env.js';
+import { maskDatabaseUrl } from './database.js';
+import { prepareTestDatabase } from './environment.js';
+import { discoverTestDataModules, loadTestData } from './testdata.js';
+/**
+ * 构造测试对象。
+ *
+ * 固定顺序（安全闸门全部在装配之前，`resources` 一行代码都还没跑）：
+ * ```
+ * prepareTestDatabase()：
+ *   加载 env（强制叠加 .env.test / .env.test.local，ENV 未给时兜底 test）
+ *     → 环境闸门（ENV 必须可清理）
+ *     → 结算测试连接串（显式 TEST_DATABASE_URL 优先，否则派生 +_test，幂等）
+ *     → schema 闸门（必须以 _test 结尾）
+ *     → 回写 process.env.DATABASE_URL
+ * → resources → core → config → clients → services → init() → middlewares
+ *   → 系统路由 → routers → 关闭钩子 → ready()
+ *   → 装载 testdata/ 脚本并整体 load(ctx)
+ * ```
+ *
+ * `testdata/` 的 `load()` 排在 `ready()` 之后：脚本拿到的是装配好的 `ctx`（`env` + `resources` +
+ * `log`），所以它写数据用的就是被测服务读数据的那份连接——两套连接写/读同一张表而看不到对方
+ * 写入（缓存 / 连接级状态）这类问题从结构上不会发生。排在最后也让失败语义最干净：装载失败时
+ * 装配已完成、可正常 `app.close()` 释放。
+ *
+ * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于
+ * 「自比自」。真正拦住「测试清空应用库」的是派生 + schema 闸门——派生只会给 schema 追加
+ * `_test`，schema 闸门只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export async function createTestServer(server) {
+    // 闸门 + 结算测试连接串全在框架内部，顺序不由调用方决定；**不改写全局 process.env**（见
+    // `prepareTestDatabase`）——测试目标只注入到本次装配的 `env` 快照里，`resources` 从
+    // `ctx.env.DATABASE_URL` 读取，同进程并行多个实例互不污染。
+    const env = resolveAppEnv(prepareTestDatabase());
+    return assemble(server, env);
+}
+/**
+ * 一次完整装配（`createTestServer` 与 `reprovision()` 共用）。
+ *
+ * 共用是刻意的：`reprovision()` 走的是**同一条**装配路径，不是「简化版重启」。两条路径一旦
+ * 分叉，测试里跑的就和第一次装配不再是同一件事，`reprovision()` 之后的用例就失去了证明力。
+ *
+ * 入参 `env` 是**已结算好**的快照：`reprovision()` 复用它、不重跑 `prepareTestDatabase()`——
+ * 连接串 / ENV 在一次测试生命周期里不该变，重算只会引入「第二次结算结果不同」的怪异失败。
+ *
+ * 返回的**只有** `TestServer`：装配期单元（`ResourceSetupUnit[]` 之类）是 boot 层的产物，
+ * 只在本函数的闭包里给 `reprovision()` 用，不往测试入口的外面漏。
+ */
+async function assemble(server, env) {
+    // 以下步序与 `startServer` 逐行对应，只去掉 listen 与信号处理器
+    const ctx = createBootContext(server, env);
+    const { resources, units: resourceUnits, classifyResourceError } = await buildResources(ctx);
+    await setupResources(ctx, resourceUnits);
+    await registerCoreStep(ctx, classifyResourceError);
+    await buildConfig(ctx, resources);
+    const clients = await buildClients(ctx, resources);
+    const services = await buildServices(ctx, resources, clients);
+    await initServiceUnits({
+        service: ctx.service,
+        log: ctx.log,
+        services: services,
+    });
+    await registerMiddlewares(ctx, services, clients);
+    registerSystemRoutesStep(ctx, services);
+    await registerRouters(ctx, services, clients);
+    installShutdownHook(ctx, services, resourceUnits);
+    await ctx.app.ready();
+    ctx.log.info({ service: ctx.service, database: maskDatabaseUrl(env.DATABASE_URL), env: env.ENV }, '[test-server] ready（测试实例不会监听端口）');
+    // `buildConfig` 一定跑过（本路径不跳过 config），缺了就按「没有 config」的语义
+    // 如实报错（`read()` 抛 `CONFIG_UNAVAILABLE`），而不是拿 `undefined` 冒充产物。
+    if (!ctx.configAccess.available) {
+        throw new Error('[test-server] config 槽位没有产出：装配顺序被改坏了（应当紧跟 resources 之后）');
+    }
+    // 装载`testdata/` 脚本并整体 `load(ctx)`：闸门（ENV 必须可清理）在 `loadTestData` 内部，
+    // 这里不重复判断，也不降级成「非测试就不算」——失败直接冒泡。
+    //
+    // `ctx` 与 `resources` 槽位同一个口径：脚本写数据 / 清缓存用的就是被测服务的那份实例。
+    const testDataCtx = {
+        env,
+        resources,
+        config: ctx.configAccess.read(),
+        clients,
+        services,
+        log: ctx.log,
+    };
+    // 脚本名单只在本函数的闭包里用：装配时 `load()` 一次就够了。用例之间的复位是
+    // `reprovision()` 的职责（重跑装配 = 重新发现 + 重新 `load`），返回值不需要把它挂在外面。
+    const testData = await discoverTestDataModules();
+    await loadTestData({ ctx: testDataCtx, units: testData, service: ctx.service });
+    return {
+        app: ctx.app,
+        env,
+        resources,
+        config: ctx.configAccess.read(),
+        clients,
+        services,
+        log: ctx.log,
+        reprovision: async () => {
+            // 1. 闸门先于一切：非可清理环境下连 `clean()` 都不该跑
+            assertCleanableEnvironment(env.ENV);
+            // 2. 清数据**必须在 `close()` 之前**：连接一断就清不了了。顺序由 boot 层编排
+            //    （资源在前、服务在后），本入口只说「给我一份干净基线」。失败冒泡——
+            //    没清干净就重装，后面全是伪绿。
+            await cleanServerUnits({ service: ctx.service, log: ctx.log, resources: resourceUnits, services: services });
+            // 3. 关掉旧实例：八步关闭自带逐单元 `dispose()`（缓冲落盘的归属就是它），
+            //    失败只 `log.error`、不阻断——旧实例释放不完美不该拦住下一条用例。
+            await ctx.app.close();
+            // 4. 用同一份 `env` 快照重新装配（内部照常 `loadTestData`）
+            return assemble(server, env);
+        },
+    };
+}

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

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

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

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

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();
+    });
+});