@yss123/cage-testkit 0.2.0 → 0.3.1

package/README.md

@@ -1,19 +1,87 @@
 # @yss123/cage-testkit
 
-派生测试运行器、fake 仓储、测试数据库
+Cage 测试工具包。提供纯 handler 的内存假依赖、真实 PostgreSQL 集成环境、测试用户/授权、手动驱动 outbox，以及声明派生的权限、状态和不变量测试。属于开发依赖，不用于生产业务写入或日常数据库管理。
 
-Cage 是通过 TypeScript 声明业务、由框架统一执行权限和数据规则的中后台框架。此包是框架的一部分。
+## 安装
 
-## 使用
+需要 Node.js 24+；与 kernel 等框架包保持同版本：
 
 ```powershell
-pnpm add -D @yss123/cage-testkit
+pnpm add -D @yss123/cage-testkit vitest
 ```
 
-首次使用建议通过脚手架创建完整项目，所需依赖由模板统一配置。需要 Node.js 24 或更新版本。
+domain 应已安装 Cage 内核，并从根入口导出组织模型 `@yss123/cage-admin/domain`。
 
-- [完整使用说明](https://github.com/shunshunyue/cage/blob/main/docs/使用说明.md)
-- [框架源码与范例](https://github.com/shunshunyue/cage)
-- [问题反馈](https://github.com/shunshunyue/cage/issues)
+## 配置真实数据库测试
 
-许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。
+在执行测试的包中创建 `vitest.config.ts`：
+
+```ts
+/** 测试集群由 globalSetup 管理；每个 createTestEnv 仍创建独立临时库。 */
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globalSetup: ['@yss123/cage-testkit/global-setup'],
+    testTimeout: 60_000,
+    hookTimeout: 120_000,
+  },
+});
+```
+
+可通过 `CAGE_TEST_DATABASE_URL` 提供专用测试集群的管理员连接，需具备创建数据库与角色权限；否则 globalSetup 尝试启动内嵌 PostgreSQL。测试会创建角色、临时数据库和夹具，必须使用可丢弃的测试集群，不能指向生产环境。不要在输出或源码中保存连接凭据。
+
+下面是已有 `Note.create` 业务的测试，假设测试文件与 domain 根 `index.ts` 位于同一目录；若目录不同，请调整相对导入：
+
+```ts
+/** 用完整内核流水线验证未授予能力时拒绝写入，而非只调用 handler。 */
+import { afterAll, beforeAll, expect, test } from 'vitest';
+import { createTestEnv, type TestEnv } from '@yss123/cage-testkit';
+import * as domain from './index.js';
+
+let env: TestEnv;
+
+beforeAll(async () => {
+  env = await createTestEnv({ domain });
+});
+
+afterAll(async () => {
+  if (env) await env.close();
+});
+
+test('没有创建便笺能力时拒绝创建', async () => {
+  const user = await env.user({ caps: [], scopes: { Note: 'all' } });
+  const result = await env.callAs(await user.ctx(), 'Note.create', {
+    title: '无权限的写入',
+  });
+  expect(result.ok).toBe(false);
+  if (!result.ok) expect(result.code).toBe('FORBIDDEN');
+});
+```
+
+执行 `pnpm exec vitest run`。默认按当前声明建新库，不证明历史数据升级正确；验证迁移时向 `createTestEnv({ domain, migrations })` 传实际迁移文件，并另行准备升级数据。
+
+## 选择测试层次
+
+| 入口 | 用途与边界 |
+| --- | --- |
+| `fakeRepo`、`draftOf`、`handlerCtx` | 纯 handler 计算测试，跳过权限、状态、数据库、审计和事务 |
+| `sampleRecord`、`sampleValue` | 按字段形状构造样例，不保证满足业务不变量 |
+| `arbitraryOf`、`arbitrarySnapshot` | fast-check 候选数据，用于探索输入和不变量边界 |
+| `createTestEnv` | 独立 PostgreSQL 数据库、真实内核、安全读侧和测试身份 |
+| `env.user`、`env.actorWithout`、`env.callAs` | 明确能力/范围后执行完整命令流水线 |
+| `env.insert`、`env.seedFor` | 绕过命令准备夹具，仅测试可用，不能当业务写入示例 |
+| `env.drain`、`env.audit` | 驱动当前可领取 outbox 与检查审计；未来重试/死信不等于已完成 |
+| `derived`、`SKIP`、`DerivedTestError` | 执行声明派生测试并区分跳过与失败 |
+| `@yss123/cage-testkit/global-setup` | 整轮 Vitest 的测试集群启停 |
+| `@yss123/cage-testkit/pg` | 内嵌 PostgreSQL 与测试连接辅助工具 |
+
+`env.close()` 关闭连接并尝试删除本次临时库，必须放在 teardown。外部测试集群不会由 globalSetup 停止。fake 成功、派生测试通过和真实第三方联调是不同证据；跳过项需要单独报告，不能计为通过。
+
+## 文档
+
+- [业务开发与验证流程](https://github.com/shunshunyue/cage/blob/main/docs/ai/workflow.md)
+- [采购业务测试示例](https://github.com/shunshunyue/cage/blob/main/examples/purchase-admin/packages/domain/src/modules/purchase/purchase-order.test.ts)
+- [架构与权限模型](https://github.com/shunshunyue/cage/blob/main/docs/ai/architecture.md)
+
+源码与反馈：[GitHub](https://github.com/shunshunyue/cage)。许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。

package/dist/derived-diagnostics.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 声明派生测试的可复现随机源与失败报告协议。
+ * 固定种子用于命令选择和测试输入，失败区分夹具准备与业务执行，报告递归隐藏敏感和秘密字段。
+ * 最短失败前缀是本轮观察所得，不是对任意程序进行全局缩减后的最小反例。
+ */
+import type { AnyAggregate } from '@yss123/cage-kernel';
+import type { TestEnv } from './env.js';
+/**
+ * 夹具回调参数：env 是真实测试环境，aggregate 是当前聚合，run 为本轮序号。
+ * seed/random/uuid 用于复现候选数据，回调应返回已持久化记录，不能只返回一个未落库对象。
+ */
+export interface DerivedFixtureContext {
+    env: TestEnv;
+    aggregate: AnyAggregate;
+    run: number;
+    seed: number;
+    random(): number;
+    uuid(): string;
+}
+/**
+ * 派生性质测试选项：seed 控制可复现选择，fixtures 按聚合名提供对象字段或构造函数。
+ * 夹具主要用于不变量序列，不能据此假设所有其他派生测试都已获得合法业务输入。
+ */
+export interface DerivedOptions {
+    /** uint32 随机种子；报告会保留实际使用的值，默认固定为 20261103。 */
+    seed?: number;
+    /** 对象作为 env.insert 的字段；函数通过命令/测试工具构造记录并返回已持久化的快照。 */
+    fixtures?: Record<string, Record<string, unknown> | ((context: DerivedFixtureContext) => Record<string, any> | Promise<Record<string, any>>)>;
+}
+/**
+ * 一次命令尝试的证据：step 为序列位置，capability 为目标，input 应已脱敏。
+ * result 记录成功或标准/业务错误码，不把原始异常或响应正文存入轨迹。
+ */
+export interface DerivedCommandTrace {
+    step: number;
+    capability: string;
+    input: unknown;
+    result: {
+        ok: boolean;
+        code?: string;
+        domainCode?: string;
+    };
+}
+/**
+ * 单轮不变量测试轨迹：initial 为初始快照，preparation 为准备命令，commands 为执行序列。
+ * phase 区分非法夹具与执行缺陷；failedInvariants 保存失败规则名，minimalPrefix 保存观察到失败为止的命令。
+ */
+export interface DerivedRunTrace {
+    aggregate: string;
+    seed: number;
+    run: number;
+    phase: 'fixture' | 'execution';
+    initial: unknown;
+    preparation: DerivedCommandTrace[];
+    commands: DerivedCommandTrace[];
+    failedInvariants: string[];
+    /** 在本轮观察到第一个失败时立即停止，保存截至该步的最短已观察失败前缀。 */
+    minimalPrefix: DerivedCommandTrace[];
+}
+/**
+ * 不变量测试汇总，steps 是实际命令尝试数，violations 是发现的问题，seed/traces 供重现排查。
+ * 没有 violation 不意味着穷尽全部命令排列，需结合实际执行步数与业务定向用例。
+ */
+export interface DerivedInvariantResult {
+    steps: number;
+    violations: string[];
+    seed: number;
+    traces: DerivedRunTrace[];
+}
+/**
+ * 携带结构化失败轨迹的测试异常，统一标识为 CAGE-TEST-002。
+ * 构造前由调用方脱敏 detail，消息序列化同一轨迹，phase/aggregate/seed 提供快速定位字段。
+ */
+export declare class DerivedTestError extends Error {
+    readonly detail: DerivedRunTrace;
+    readonly code = "CAGE-TEST-002";
+    readonly phase: 'fixture' | 'execution';
+    readonly aggregate: string;
+    readonly seed: number;
+    constructor(detail: DerivedRunTrace);
+}
+/** 固定算法，避免 Math.random 的隐式全局状态使命令序列无法重放。 */
+/**
+ * 返回独立闭包随机序列，同一 uint32 种子按固定算法产生相同 [0,1) 值。
+ * 仅用于测试可复现性，不具备密码学安全性，不能生成生产凭据。
+ */
+export declare function seededRandom(seed: number): () => number;
+/**
+ * 从给定随机源构造符合版本/变体位形状的 UUID，消耗固定数量的随机值。
+ * 固定种子下可重复，不保证跨独立重放唯一；用于隔离测试数据而非生产标识分配。
+ */
+export declare function seededUuid(random: () => number): string;
+/** 诊断不使用操作者的明文能力；敏感/隐藏字段在任意对象深度及数组内一律遮盖。 */
+/**
+ * 从聚合声明递归收集敏感/隐藏字段名，并结合固定秘密字段名生成报告脱敏函数。
+ * 与操作者的 unmask 权限无关，数组与嵌套对象统一遮盖，避免失败证据泄露明文。
+ */
+export declare function derivedRedactor(aggregates: readonly AnyAggregate[]): (value: unknown) => unknown;

package/dist/derived-diagnostics.js

@@ -0,0 +1,73 @@
+/**
+ * 携带结构化失败轨迹的测试异常，统一标识为 CAGE-TEST-002。
+ * 构造前由调用方脱敏 detail，消息序列化同一轨迹，phase/aggregate/seed 提供快速定位字段。
+ */
+export class DerivedTestError extends Error {
+    detail;
+    code = 'CAGE-TEST-002';
+    phase;
+    aggregate;
+    seed;
+    constructor(detail) {
+        super(`[CAGE-TEST-002] 派生测试${detail.phase === 'fixture' ? '初始夹具非法' : '执行失败'}：${JSON.stringify(detail)}`);
+        this.detail = detail;
+        this.name = 'DerivedTestError';
+        this.phase = detail.phase;
+        this.aggregate = detail.aggregate;
+        this.seed = detail.seed;
+    }
+}
+/** 固定算法，避免 Math.random 的隐式全局状态使命令序列无法重放。 */
+/**
+ * 返回独立闭包随机序列，同一 uint32 种子按固定算法产生相同 [0,1) 值。
+ * 仅用于测试可复现性，不具备密码学安全性，不能生成生产凭据。
+ */
+export function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state += 0x6d2b79f5;
+        let value = Math.imul(state ^ (state >>> 15), 1 | state);
+        value ^= value + Math.imul(value ^ (value >>> 7), 61 | value);
+        return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * 从给定随机源构造符合版本/变体位形状的 UUID，消耗固定数量的随机值。
+ * 固定种子下可重复，不保证跨独立重放唯一；用于隔离测试数据而非生产标识分配。
+ */
+export function seededUuid(random) {
+    const bytes = Array.from({ length: 16 }, () => Math.floor(random() * 256));
+    bytes[6] = (bytes[6] & 15) | 64;
+    bytes[8] = (bytes[8] & 63) | 128;
+    const hex = bytes.map((byte) => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** 诊断不使用操作者的明文能力；敏感/隐藏字段在任意对象深度及数组内一律遮盖。 */
+/**
+ * 从聚合声明递归收集敏感/隐藏字段名，并结合固定秘密字段名生成报告脱敏函数。
+ * 与操作者的 unmask 权限无关，数组与嵌套对象统一遮盖，避免失败证据泄露明文。
+ */
+export function derivedRedactor(aggregates) {
+    const sensitive = new Set(['password', 'passwordhash', 'token', 'secret', 'authorization', 'cookie']);
+    const visitFields = (fields) => {
+        for (const [name, field] of Object.entries(fields)) {
+            if (field.sensitiveKind || field.isHidden)
+                sensitive.add(name.toLowerCase());
+            if (field.shape)
+                visitFields(field.shape);
+        }
+    };
+    for (const aggregate of aggregates)
+        visitFields(aggregate.fields);
+    const redact = (value) => {
+        if (Array.isArray(value))
+            return value.map(redact);
+        if (value === null || typeof value !== 'object')
+            return typeof value === 'bigint' ? value.toString() : value;
+        if (value instanceof Date)
+            return value.toISOString();
+        return Object.fromEntries(Object.entries(value).map(([name, entry]) => [name, sensitive.has(name.toLowerCase()) ? '[REDACTED]' : redact(entry)]));
+    };
+    return redact;
+}
+//# sourceMappingURL=derived-diagnostics.js.map

package/dist/derived-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-diagnostics.js","sourceRoot":"","sources":["../src/derived-diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/derived.d.ts

@@ -1,6 +1,18 @@
 import { type CallResult, type TestEnv } from './env.js';
+import { type DerivedInvariantResult, type DerivedOptions } from './derived-diagnostics.js';
+export { DerivedTestError, type DerivedOptions, type DerivedFixtureContext, type DerivedCommandTrace, type DerivedRunTrace, type DerivedInvariantResult } from './derived-diagnostics.js';
+/**
+ * 派生检查未执行到目标性质时的显式返回标识，用于由测试调用方记录跳过。
+ */
 export type Skip = 'skip';
+/**
+ * 统一跳过值，与成功断言结果区分；调用方须保留跳过计数和原因上下文。
+ */
 export declare const SKIP: Skip;
+/**
+ * 派生检查句柄，先 setup 再调用检查，结束时 teardown。
+ * 各方法返回可断言的观察结果或 SKIP；env 供项目定向检查复用，不能在 setup 前使用。
+ */
 export interface Derived {
     env(): TestEnv;
     setup(): Promise<void>;
@@ -26,9 +38,11 @@ export interface Derived {
         plain: unknown;
         seen: unknown;
     }[] | Skip>;
-    invariantsHold(agg: string, runs?: number): Promise<{
-        steps: number;
-        violations: string[];
-    } | Skip>;
+    invariantsHold(agg: string, runs?: number): Promise<DerivedInvariantResult | Skip>;
 }
-export declare function derived(domain: object): Derived;
+/**
+ * 为一个 domain 建立延迟初始化的性质测试集合，默认固定种子，非法 seed 立即拒绝。
+ * 能力/状态检查构造针对性身份，范围检查验证详情、列表和裸安全视图；成功性质无法执行时报告 SKIP。
+ * invariantsHold 先验证初始夹具再执行有限命令序列，区分准备失败和执行失败，并保留可定位轨迹。
+ */
+export declare function derived(domain: object, options?: DerivedOptions): Derived;