# @geekmidas/testkit 中文文档

规范地址：https://npmcn.com/package/%40geekmidas/testkit/

版本：9\.6\.1
npm 元数据更新时间：2026-11-16T09:33:02.393Z
中文译文更新时间：2026-11-16T09:34:44.859Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40geekmidas/testkit
原文对照：https://npmcn.com/package/%40geekmidas/testkit/?lang=original
项目主页：https://github.com/geekmidas/toolbox#readme
源码仓库：https://github.com/geekmidas/toolbox

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：872 kB，261 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：pg ~8\.16\.3，knex ~3\.1\.0，kysely ~0\.29\.4，vitest ^3\.2\.4 \|\| ^4\.1\.11，db-errors ~0\.2\.3，objection ~3\.1\.5，better-auth \>=1\.3\.34，@geekmidas/envkit ^9\.6\.1，@geekmidas/logger ^9\.6\.1，@types/aws-lambda \>=8\.10\.92，@geekmidas/services ^9\.6\.1
- 首次发布：2025-07-04T10:47:14.961Z
- 最新版本发布：2026-11-16T09:33:02.034Z
- 近 30 天下载量：14163（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：232（近 12 个月 216 个）

## 中文简介

> 现代TypeScript应用软件的型式安全测试设施和数据库工厂

## 安装

```sh
npm install @geekmidas/testkit
```

也可以使用：`pnpm add @geekmidas/testkit`、`yarn add @geekmidas/testkit`、`bun add @geekmidas/testkit`

## README

# @geekmidas/ testkit (英语)

> 现代TypeScript应用软件的型式安全测试设施和数据库工厂

[![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.8.2-blue)](https://www.typescriptlang.org/) [![License](https://img.shields.io/badge/license-MIT-green)](https://npmcn.com/package/%40geekmidas/testkit/LICENSE)

## 概览

**@geekmidas/ testkit (英语)** 提供一套全面的测试工具,旨在简化TypeScript应用程序中的数据库测试. 它为创建测试数据提供了工厂模式,支持多个数据库库,并确保了整个测试过程中的类型安全.

### 关键特性

-   **工厂模式**: 用最小的锅炉板创建测试数据
-   **类型安全**: 完全类型Script支持,并带有自动计划推论
-   **多数据库支持**:与Kysely和Object.js合作
-   **交易隔离**: 测试隔离的内置支持
-   **强化的Faker**: 带有时间戳、序列和坐标的扩展假人
-   **AWS 模拟器**: Mok Lambda 上下文和 API 网关事件
-   **更好的认证**: 用于认证测试的模拟适配器

## 安装

```bash
npm install --save-dev @geekmidas/testkit
# or
pnpm add -D @geekmidas/testkit
# or
yarn add -D @geekmidas/testkit
```

## 子路径导出

```typescript
// Kysely utilities
import {
  KyselyFactory,
  wrapVitestKyselyTransaction,
  extendWithFixtures,
} from '@geekmidas/testkit/kysely';

// Objection.js utilities
import {
  ObjectionFactory,
  wrapVitestObjectionTransaction,
  extendWithFixtures,
} from '@geekmidas/testkit/objection';

// Other utilities
import { faker } from '@geekmidas/testkit/faker';
import { waitFor } from '@geekmidas/testkit/timer';
import { itWithDir } from '@geekmidas/testkit/os';
import { createMockContext, createMockV1Event, createMockV2Event } from '@geekmidas/testkit/aws';
import { createMockLogger } from '@geekmidas/testkit/logger';
import { memoryAdapter } from '@geekmidas/testkit/better-auth';
```

## 快速启动

### 带有 Kysely 的数据库工厂

```typescript
import { KyselyFactory } from '@geekmidas/testkit/kysely';
import { Kysely } from 'kysely';

// Define your database schema
interface Database {
  users: {
    id: string;
    name: string;
    email: string;
    createdAt: Date;
  };
  posts: {
    id: string;
    title: string;
    content: string;
    userId: string;
  };
}

// Create builders for your tables
const builders = {
  user: KyselyFactory.createBuilder<Database, 'users'>(
    'users',
    ({ attrs, faker }) => ({
      id: faker.string.uuid(),
      name: faker.person.fullName(),
      email: faker.internet.email(),
      createdAt: new Date(),
      ...attrs,
    })
  ),
  post: KyselyFactory.createBuilder<Database, 'posts'>(
    'posts',
    ({ attrs, faker }) => ({
      id: faker.string.uuid(),
      title: 'Test Post',
      content: faker.lorem.paragraph(),
      ...attrs,
    })
  ),
};

// Initialize factory
const factory = new KyselyFactory(builders, {}, db);

// Use in tests
describe('User Service', () => {
  it('should create a user with posts', async () => {
    const user = await factory.insert('user', {
      name: 'Jane Smith',
      email: 'jane@example.com',
    });

    const posts = await factory.insertMany(3, 'post', {
      userId: user.id,
    });

    expect(posts).toHaveLength(3);
    expect(posts[0].userId).toBe(user.id);
  });
});
```

### 反对 js

```typescript
import { ObjectionFactory } from '@geekmidas/testkit/objection';
import { Model } from 'objection';

class User extends Model {
  static tableName = 'users';
  id!: string;
  name!: string;
  email!: string;
}

const builders = {
  user: ObjectionFactory.createBuilder(
    User,
    ({ attrs, faker }) => ({
      id: faker.string.uuid(),
      name: faker.person.fullName(),
      email: faker.internet.email(),
      ...attrs,
    })
  ),
};

const factory = new ObjectionFactory(builders, {}, knex);
const user = await factory.insert('user', { name: 'Jane Doe' });
```

## 强化的Faker

测试设备提供了强化的假冒实例,并增加了通用测试数据模式的公用事业.

```typescript
import { faker } from '@geekmidas/testkit/faker';

// Standard faker methods
const name = faker.person.fullName();
const email = faker.internet.email();

// Generate timestamps for database records
const { createdAt, updatedAt } = faker.timestamps();
// createdAt: Date in the past
// updatedAt: Date between createdAt and now

// Sequential numbers (useful for unique IDs)
faker.sequence();           // 1
faker.sequence();           // 2
faker.sequence('user');     // 1 (separate sequence)
faker.sequence('user');     // 2

// Reset sequences between tests
faker.resetSequence('user');
faker.resetAllSequences();

// Generate prices as numbers
const price = faker.price(); // 29.99

// Generate reverse domain identifiers
faker.identifier();         // "com.example.widget1"
faker.identifier('user');   // "org.acme.user"

// Generate coordinates within/outside a radius
const center = { lat: 40.7128, lng: -74.0060 };
faker.coordinates.within(center, 1000);   // Within 1km
faker.coordinates.outside(center, 1000, 5000); // Between 1km and 5km
```

## 计时器

简单的async 等待测试工具 .

```typescript
import { waitFor } from '@geekmidas/testkit/timer';

it('should process after delay', async () => {
  startBackgroundProcess();
  await waitFor(100); // Wait 100ms
  expect(processComplete).toBe(true);
});
```

## OS 公用事业

Vest fixture 用于自动清理的临时目录创建.

```typescript
import { itWithDir } from '@geekmidas/testkit/os';

// Creates a temp directory before test, removes it after
itWithDir('should write files to temp dir', async ({ dir }) => {
  const filePath = path.join(dir, 'test.txt');
  await fs.writeFile(filePath, 'hello');

  const content = await fs.readFile(filePath, 'utf-8');
  expect(content).toBe('hello');
  // Directory is automatically cleaned up after test
});
```

## AWS 测试工具

Mock AWS Lambda背景和API Gateway事件,用于测试Lambda处理器.

```typescript
import {
  createMockContext,
  createMockV1Event,
  createMockV2Event
} from '@geekmidas/testkit/aws';

describe('Lambda Handler', () => {
  it('should handle API Gateway v1 event', async () => {
    const event = createMockV1Event({
      httpMethod: 'POST',
      path: '/users',
      body: JSON.stringify({ name: 'John' }),
    });
    const context = createMockContext();

    const result = await handler(event, context);
    expect(result.statusCode).toBe(201);
  });

  it('should handle API Gateway v2 event', async () => {
    const event = createMockV2Event({
      routeKey: 'POST /users',
      rawPath: '/users',
      body: JSON.stringify({ name: 'John' }),
    });
    const context = createMockContext();

    const result = await handler(event, context);
    expect(result.statusCode).toBe(201);
  });
});
```

## Logger 测试工具

创建用于测试代码的模拟日志 `@geekmidas/logger`。 。 。 .

```typescript
import { createMockLogger } from '@geekmidas/testkit/logger';

describe('Service', () => {
  it('should log errors', async () => {
    const logger = createMockLogger();
    const service = new MyService(logger);

    await service.doSomethingRisky();

    expect(logger.error).toHaveBeenCalledWith(
      expect.objectContaining({ error: expect.any(Error) }),
      'Operation failed'
    );
  });
});
```

## 更好的认证测试

用于测试Better Auth的模拟适配器,没有真正的数据库.

```typescript
import { memoryAdapter } from '@geekmidas/testkit/better-auth';
import { betterAuth } from 'better-auth';

describe('Authentication', () => {
  const adapter = memoryAdapter({
    debugLogs: false,
    initialData: {
      user: [{ id: '1', email: 'test@example.com', name: 'Test User' }],
    },
  });

  const auth = betterAuth({
    database: adapter,
    // ... other config
  });

  afterEach(() => {
    adapter.clear(); // Reset data between tests
  });

  it('should create user', async () => {
    await auth.api.signUp({
      email: 'new@example.com',
      password: 'password123',
    });

    const data = adapter.getAllData();
    expect(data.user).toHaveLength(2);
  });
});
```

## 数据库迁移

TestKit包括管理测试数据库迁移的公用事业.

```typescript
import { PostgresKyselyMigrator } from '@geekmidas/testkit/kysely';

const migrator = new PostgresKyselyMigrator({
  database: 'test_db',
  connection: {
    host: 'localhost',
    port: 5432,
    user: 'postgres',
    password: 'password',
  },
  migrationFolder: './migrations',
});

// In test setup
beforeAll(async () => {
  const cleanup = await migrator.start();
  globalThis.cleanupDb = cleanup;
});

afterAll(async () => {
  await globalThis.cleanupDb?.();
});
```

## 无效交易隔离

TestKit为自动交易隔离提供Vitest特定帮助. 每个测试在测试完成后自动回滚的交易中运行.

### 基本用途

```typescript
import { test } from 'vitest';
import { wrapVitestKyselyTransaction } from '@geekmidas/testkit/kysely';
import { db } from './database';

// Wrap Vitest's test function with transaction support
const it = wrapVitestKyselyTransaction<Database>(
  test,
  () => db,
  async (trx) => {
    // Optional: Set up test tables or seed data
    await trx.schema.createTable('users').execute();
  }
);

// Each test gets its own transaction
it('should create user', async ({ trx }) => {
  const user = await trx
    .insertInto('users')
    .values({ name: 'John' })
    .returningAll()
    .executeTakeFirst();

  expect(user.name).toBe('John');
  // Transaction is automatically rolled back after test
});
```

### 以固定器延伸

使用 `extendWithFixtures` 在测试中添加工厂和其他固定装置:

```typescript
import { test } from 'vitest';
import {
  wrapVitestKyselyTransaction,
  extendWithFixtures,
  KyselyFactory,
} from '@geekmidas/testkit/kysely';

// Define builders
const builders = {
  user: KyselyFactory.createBuilder<Database, 'users'>('users', ({ faker }) => ({
    name: faker.person.fullName(),
    email: faker.internet.email(),
  })),
  post: KyselyFactory.createBuilder<Database, 'posts'>('posts', ({ faker }) => ({
    title: faker.lorem.sentence(),
    content: faker.lorem.paragraphs(),
  })),
};

// Create base test with transaction
const baseTest = wrapVitestKyselyTransaction<Database>(test, () => db);

// Extend with factory fixture
const it = extendWithFixtures<
  Database,
  { factory: KyselyFactory<Database, typeof builders, {}> }
>(baseTest, {
  factory: (trx) => new KyselyFactory(builders, {}, trx),
});

// Both trx and factory are available in tests
it('should create user with factory', async ({ trx, factory }) => {
  const user = await factory.insert('user', { name: 'Jane' });

  expect(user.id).toBeDefined();
  expect(user.name).toBe('Jane');

  // Verify in database
  const found = await trx
    .selectFrom('users')
    .where('id', '=', user.id)
    .selectAll()
    .executeTakeFirst();

  expect(found?.name).toBe('Jane');
});

it('should create related records', async ({ factory }) => {
  const user = await factory.insert('user');
  const posts = await factory.insertMany(3, 'post', { userId: user.id });

  expect(posts).toHaveLength(3);
  expect(posts[0].userId).toBe(user.id);
});
```

### 多个固定

您可以添加全部接收交易的多个定着:

```typescript
const it = extendWithFixtures<
  Database,
  {
    factory: KyselyFactory<Database, typeof builders, {}>;
    userRepo: UserRepository;
    config: { maxUsers: number };
  }
>(baseTest, {
  factory: (trx) => new KyselyFactory(builders, {}, trx),
  userRepo: (trx) => new UserRepository(trx),
  config: () => ({ maxUsers: 100 }), // Fixtures can ignore trx if not needed
});

it('should use multiple fixtures', async ({ factory, userRepo, config }) => {
  const user = await factory.insert('user');
  const found = await userRepo.findById(user.id);
  expect(found).toBeDefined();
  expect(config.maxUsers).toBe(100);
});
```

### 反对 js

```typescript
import { wrapVitestObjectionTransaction, extendWithFixtures } from '@geekmidas/testkit/objection';

const baseTest = wrapVitestObjectionTransaction(test, () => knex);

const it = extendWithFixtures<{ factory: ObjectionFactory<typeof builders, {}> }>(
  baseTest,
  {
    factory: (trx) => new ObjectionFactory(builders, {}, trx),
  }
);
```

## 手动交易隔离

为了进行更多的控制,您可以手动管理交易 :

```typescript
describe('User Service', () => {
  let trx: Transaction<Database>;
  let factory: KyselyFactory;

  beforeEach(async () => {
    trx = await db.transaction();
    factory = new KyselyFactory(builders, seeds, trx);
  });

  afterEach(async () => {
    await trx.rollback();
  });

  it('should perform operations in isolation', async () => {
    const user = await factory.insert('user');
    // All changes will be rolled back after the test
  });
});
```

## 种子

种子是产生复杂测试情景的函数. 使用 `createSeed` 以定义获得的类型安全种子功能 `{ attrs, factory, db }` 作为单个上下文对象:

### 用 Kysely 定义种子

```typescript
import { KyselyFactory } from '@geekmidas/testkit/kysely';

// Define seeds using createSeed for type safety
const seeds = {
  // Simple seed with typed attrs
  adminUser: KyselyFactory.createSeed(
    async ({ attrs, factory }: {
      attrs: { name?: string };
      factory: KyselyFactory<Database, typeof builders, {}>;
      db: Kysely<Database>
    }) => {
      return factory.insert('user', {
        name: attrs.name || 'Admin User',
        role: 'admin',
      });
    }
  ),

  // Complex seed creating related records
  blogWithPosts: KyselyFactory.createSeed(
    async ({ attrs, factory }) => {
      const author = await factory.insert('user', {
        name: attrs.authorName || 'Blog Author',
        role: 'author',
      });

      const categories = await factory.insertMany(3, 'category');

      const posts = await factory.insertMany(attrs.postCount || 5, 'post', (index) => ({
        title: `Post ${index + 1}`,
        authorId: author.id,
        categoryId: categories[index % categories.length].id,
      }));

      return { author, categories, posts };
    }
  ),
};

// Create factory with seeds
const factory = new KyselyFactory(builders, seeds, db);

// Use in tests - attrs are type-safe
const admin = await factory.seed('adminUser', { name: 'Super Admin' });
const blog = await factory.seed('blogWithPosts', {
  authorName: 'Jane Doe',
  postCount: 10
});
```

### 以反对方式定义种子。js

```typescript
import { ObjectionFactory } from '@geekmidas/testkit/objection';
import type { Knex } from 'knex';

const seeds = {
  userWithProfile: ObjectionFactory.createSeed(
    async ({ attrs, factory, db }: {
      attrs: { email?: string };
      factory: ObjectionFactory<typeof builders, {}>;
      db: Knex
    }) => {
      const user = await factory.insert('user', {
        email: attrs.email || 'user@example.com',
      });

      await factory.insert('profile', { userId: user.id });

      return user;
    }
  ),
};

const factory = new ObjectionFactory(builders, seeds, knex);
const user = await factory.seed('userWithProfile', { email: 'custom@example.com' });
```

### 种子上下文对象

所有种子函数都收到一个具有三个属性的单个上下文对象:

| 财产 | 说明 |
| --- | --- |
| `attrs` | 配置属性传递到 `factory.seed()` |
| `factory` | 创建记录的工厂实例 |
| `db` | 数据库连接( Kysely 或 Knex 交易) |

这个图案只允许您解构您需要的 :

```typescript
// Use all three
KyselyFactory.createSeed(async ({ attrs, factory, db }) => {
  // Direct db access for complex queries
  const existing = await db.selectFrom('users').where('role', '=', 'admin').execute();
  // ...
});

// Or just what you need
KyselyFactory.createSeed(async ({ factory }) => {
  return factory.insert('user');
});
```

## API 参考

### 基斯利事实

```typescript
class KyselyFactory<DB, Builders, Seeds> {
  constructor(
    builders: Builders,
    seeds: Seeds,
    db: Kysely<DB> | ControlledTransaction<DB>
  );

  // Create a type-safe builder for a specific table
  static createBuilder<DB, TableName extends keyof DB & string>(
    table: TableName,
    defaults?: (context: {
      attrs: Partial<Insertable<DB[TableName]>>;
      factory: KyselyFactory;
      db: Kysely<DB>;
      faker: FakerFactory;
    }) => Partial<Insertable<DB[TableName]>> | Promise<...>,
    autoInsert?: boolean
  ): BuilderFunction;

  // Create a type-safe seed function
  static createSeed<Seed extends FactorySeed>(
    seedFn: (context: { attrs: Attrs; factory: Factory; db: DB }) => Promise<Result>
  ): Seed;

  // Insert a single record
  insert<K extends keyof Builders>(
    builderName: K,
    attrs?: Partial<BuilderAttrs>
  ): Promise<BuilderResult>;

  // Insert multiple records
  insertMany<K extends keyof Builders>(
    count: number,
    builderName: K,
    attrs?: Partial<BuilderAttrs> | ((idx: number, faker: FakerFactory) => Partial<BuilderAttrs>)
  ): Promise<BuilderResult[]>;

  // Execute a seed function
  seed<K extends keyof Seeds>(
    seedName: K,
    attrs?: ExtractSeedAttrs<Seeds[K]>  // Attrs type is extracted from seed function
  ): Promise<SeedResult>;
}
```

### 强化的Faker

```typescript
interface EnhancedFaker extends Faker {
  timestamps(): { createdAt: Date; updatedAt: Date };
  sequence(name?: string): number;
  resetSequence(name?: string, value?: number): void;
  resetAllSequences(): void;
  identifier(suffix?: string): string;
  price(): number;
  coordinates: {
    within(center: Coordinate, radiusMeters: number): Coordinate;
    outside(center: Coordinate, minRadius: number, maxRadius: number): Coordinate;
  };
}
```

### AWS 模拟器

```typescript
function createMockContext(): Context;
function createMockV1Event(overrides?: Partial<APIGatewayProxyEvent>): APIGatewayProxyEvent;
function createMockV2Event(overrides?: Partial<APIGatewayProxyEventV2>): APIGatewayProxyEventV2;
```

### 内存适配器( Better Auth)

```typescript
function memoryAdapter(config?: {
  debugLogs?: boolean;
  usePlural?: boolean;
  initialData?: Record<string, any[]>;
}): DatabaseAdapter & {
  clear(): void;
  getAllData(): Record<string, any[]>;
  getStore(): Map<string, any>;
};
```

## 测试最佳做法

1.  **使用交易**: 总是在交易中包装测试以隔离
2.  **创建最小数据**: 只创建每个测试所需的数据
3.  **复杂情景使用种子**: 封装种子中的复杂设置
4.  **利用类型安全**: 让 TypeScript 捕获计划错配
5.  **清理资源**: 总是清理数据库连接和交易
6.  **重置顺序**: 调用 `faker.resetAllSequences()` 内 `beforeEach` 用于可预见身份证

## 捐款

我们欢迎捐款! 请看我们的 [贡献指南](https://npmcn.com/package/CONTRIBUTING.md) 详细情况.

## 许可证

这个项目根据麻省理工学院许可证颁发——见 [自由主义](https://npmcn.com/package/LICENSE) 详细文件.

## 常见问题

### @geekmidas/testkit 是什么？

现代TypeScript应用软件的型式安全测试设施和数据库工厂

### 如何安装 @geekmidas/testkit？

在项目目录运行 npm install @geekmidas/testkit，或使用 pnpm add / yarn add / bun add。

### @geekmidas/testkit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @geekmidas/testkit 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @geekmidas/testkit 可以商用吗？

@geekmidas/testkit 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @geekmidas/testkit 的下载量有多少？

根据 npm 官方下载统计，@geekmidas/testkit 在 2026/10/16 – 2026/11/14 这 30 天内被下载 14,163 次，日均约 472 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @geekmidas/testkit 还在维护吗？

最新版本 9\.6\.1 发布于 2026/11/16（今天）；至今共发布 232 个版本，其中过去 12 个月发布了 216 个；首次发布于 2025/07/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

