@yss123/cage-testkit 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +16 -70
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -1,87 +1,33 @@
1
1
  # @yss123/cage-testkit
2
2
 
3
- Cage 测试工具包。提供纯 handler 的内存假依赖、真实 PostgreSQL 集成环境、测试用户/授权、手动驱动 outbox，以及声明派生的权限、状态和不变量测试。属于开发依赖，不用于生产业务写入或日常数据库管理。
3
+ 开发测试工具：纯 handler 假依赖、独立真实 PostgreSQL、测试主体与授权、outbox 驱动及声明派生测试。它不作为生产业务写入口或日常数据库管理工具。
4
4
 
5
- ## 安装
5
+ ## 配置
6
6
 
7
- 需要 Node.js 24+；与 kernel 等框架包保持同版本：
7
+ 安装 pnpm add -D @yss123/cage-testkit vitest，使用 Node.js 24+ 与同版本内核。在 Vitest 配置 globalSetup: ['@yss123/cage-testkit/global-setup']，并给数据库启动留出 hookTimeout。
8
8
 
9
- ```powershell
10
- pnpm add -D @yss123/cage-testkit vitest
11
- ```
12
-
13
- domain 应已安装 Cage 内核，并从根入口导出组织模型 `@yss123/cage-admin/domain`。
14
-
15
- ## 配置真实数据库测试
16
-
17
- 在执行测试的包中创建 `vitest.config.ts`：
18
-
19
- ```ts
20
- /** 测试集群由 globalSetup 管理；每个 createTestEnv 仍创建独立临时库。 */
21
- import { defineConfig } from 'vitest/config';
22
-
23
- export default defineConfig({
24
- test: {
25
- globalSetup: ['@yss123/cage-testkit/global-setup'],
26
- testTimeout: 60_000,
27
- hookTimeout: 120_000,
28
- },
29
- });
30
- ```
9
+ CAGE_TEST_DATABASE_URL 可提供可丢弃独立测试集群；缺省时 setup 尝试内嵌真实 PostgreSQL。环境会创建角色和临时库，不能指向生产或普通业务集群。
31
10
 
32
- 可通过 `CAGE_TEST_DATABASE_URL` 提供专用测试集群的管理员连接，需具备创建数据库与角色权限；否则 globalSetup 尝试启动内嵌 PostgreSQL。测试会创建角色、临时数据库和夹具，必须使用可丢弃的测试集群，不能指向生产环境。不要在输出或源码中保存连接凭据。
11
+ ## 验证真实流水线
33
12
 
34
- 下面是已有 `Note.create` 业务的测试，假设测试文件与 domain 根 `index.ts` 位于同一目录；若目录不同，请调整相对导入：
13
+ 以下是测试函数中的片段，domain 已包含 Note.create 与组织声明：
35
14
 
36
15
  ```ts
37
- /** 用完整内核流水线验证未授予能力时拒绝写入，而非只调用 handler。 */
38
- import { afterAll, beforeAll, expect, test } from 'vitest';
39
- import { createTestEnv, type TestEnv } from '@yss123/cage-testkit';
40
- import * as domain from './index.js';
41
-
42
- let env: TestEnv;
43
-
44
- beforeAll(async () => {
45
- env = await createTestEnv({ domain });
46
- });
47
-
48
- afterAll(async () => {
49
- if (env) await env.close();
50
- });
51
-
52
- test('没有创建便笺能力时拒绝创建', async () => {
16
+ const env = await createTestEnv({ domain });
17
+ try {
53
18
  const user = await env.user({ caps: [], scopes: { Note: 'all' } });
54
- const result = await env.callAs(await user.ctx(), 'Note.create', {
55
- title: '无权限的写入',
56
- });
19
+ const result = await env.callAs(await user.ctx(), 'Note.create', { title: '无权创建' });
57
20
  expect(result.ok).toBe(false);
58
21
  if (!result.ok) expect(result.code).toBe('FORBIDDEN');
59
- });
22
+ } finally {
23
+ await env.close();
24
+ }
60
25
  ```
61
26
 
62
- 执行 `pnpm exec vitest run`。默认按当前声明建新库，不证明历史数据升级正确；验证迁移时向 `createTestEnv({ domain, migrations })` 传实际迁移文件，并另行准备升级数据。
63
-
64
- ## 选择测试层次
65
-
66
- | 入口 | 用途与边界 |
67
- | --- | --- |
68
- | `fakeRepo`、`draftOf`、`handlerCtx` | 纯 handler 计算测试，跳过权限、状态、数据库、审计和事务 |
69
- | `sampleRecord`、`sampleValue` | 按字段形状构造样例，不保证满足业务不变量 |
70
- | `arbitraryOf`、`arbitrarySnapshot` | fast-check 候选数据，用于探索输入和不变量边界 |
71
- | `createTestEnv` | 独立 PostgreSQL 数据库、真实内核、安全读侧和测试身份 |
72
- | `env.user`、`env.actorWithout`、`env.callAs` | 明确能力/范围后执行完整命令流水线 |
73
- | `env.insert`、`env.seedFor` | 绕过命令准备夹具，仅测试可用，不能当业务写入示例 |
74
- | `env.drain`、`env.audit` | 驱动当前可领取 outbox 与检查审计；未来重试/死信不等于已完成 |
75
- | `derived`、`SKIP`、`DerivedTestError` | 执行声明派生测试并区分跳过与失败 |
76
- | `@yss123/cage-testkit/global-setup` | 整轮 Vitest 的测试集群启停 |
77
- | `@yss123/cage-testkit/pg` | 内嵌 PostgreSQL 与测试连接辅助工具 |
78
-
79
- `env.close()` 关闭连接并尝试删除本次临时库，必须放在 teardown。外部测试集群不会由 globalSetup 停止。fake 成功、派生测试通过和真实第三方联调是不同证据；跳过项需要单独报告，不能计为通过。
27
+ createTestEnv 从本包导入，expect 来自测试库，domain 来自被测入口。默认按当前声明建库；历史升级要传实际 migrations 并准备旧数据，默认测试不证明迁移历史正确。
80
28
 
81
- ## 文档
29
+ fakeRepo/draftOf/handlerCtx 只测计算，跳过权限、事务与数据库。env.insert/seedFor 是测试夹具通道；env.drain 驱动可领取消息，不代表未来重试或死信已完成。
82
30
 
83
- - [业务开发与验证流程](https://github.com/shunshunyue/cage/blob/main/docs/development/getting-started/workflow.md)
84
- - [采购业务测试示例](https://github.com/shunshunyue/cage/blob/main/examples/purchase-admin/packages/domain/src/modules/purchase/purchase-order.test.ts)
85
- - [架构与权限模型](https://github.com/shunshunyue/cage/blob/main/docs/development/getting-started/architecture.md)
31
+ derived 证明通用性质，不能凭空推断所有业务合法输入。跳过、失败与通过分别报告，fake 和真实第三方联调也分别取得证据。
86
32
 
87
- 源码与反馈：[GitHub](https://github.com/shunshunyue/cage)。许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。
33
+ [验证参考](https://github.com/shunshunyue/cage/blob/main/docs/development/reference/verification.md) · [采购业务测试](https://github.com/shunshunyue/cage/blob/main/examples/purchase-admin/packages/domain/src/modules/purchase/purchase-order.test.ts)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yss123/cage-testkit",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "派生测试运行器、fake 仓储、测试数据库",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -30,17 +30,17 @@
30
30
  "zod": "^4.1.5"
31
31
  },
32
32
  "peerDependencies": {
33
- "@yss123/cage-kernel": "0.4.0"
33
+ "@yss123/cage-kernel": "0.4.1"
34
34
  },
35
35
  "devDependencies": {
36
36
  "@types/pg": "^8.15.5",
37
37
  "vitest": "^4.1.12",
38
- "@yss123/cage-ai": "0.4.0",
39
- "@yss123/cage-kernel": "0.4.0",
40
- "@yss123/cage-admin": "0.4.0",
41
- "@yss123/cage-approval": "0.4.0",
42
- "@yss123/cage-connectors": "0.4.0",
43
- "@yss123/cage-http": "0.4.0"
38
+ "@yss123/cage-http": "0.4.1",
39
+ "@yss123/cage-kernel": "0.4.1",
40
+ "@yss123/cage-admin": "0.4.1",
41
+ "@yss123/cage-ai": "0.4.1",
42
+ "@yss123/cage-approval": "0.4.1",
43
+ "@yss123/cage-connectors": "0.4.1"
44
44
  },
45
45
  "license": "MIT",
46
46
  "repository": {