# @sadikkhan02/test-utils 中文文档

规范地址：https://npmcn.com/package/%40sadikkhan02/test-utils/

版本：1\.0\.0
npm 元数据更新时间：2026-11-02T08:30:14.214Z
中文译文更新时间：2026-11-02T09:35:49.811Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40sadikkhan02/test-utils
原文对照：https://npmcn.com/package/%40sadikkhan02/test-utils/?lang=original

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

- 包体积（解压后）：24.6 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- peer 依赖：vitest \>=1\.0\.0 \|\| \>=2\.0\.0 \|\| \>=3\.0\.0 \|\| \>=4\.0\.0 \|\| \>=5\.0\.0，@sadikkhan02/notifykit ^1\.0\.0
- 首次发布：2026-11-02T08:18:00.453Z
- 最新版本发布：2026-11-02T08:30:14.041Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

用于NotifyKit的确定性测试实用程序和适配器契约遵从套件

## 安装

```sh
npm install @sadikkhan02/test-utils
```

也可以使用：`pnpm add @sadikkhan02/test-utils`、`yarn add @sadikkhan02/test-utils`、`bun add @sadikkhan02/test-utils`

## README

# `@sadikkhan02/test-utils`

官方测试工具和适配器契约测试框架 **NotifyKit**.

提供共享fixture、内存模拟提供程序、安全的本地Redis帮助程序和标准化的 **适配器合同套件** （`runAdapterContractTests`)，所有官方和社区提供程序适配器都需要。

* * *

## 安装

```bash
npm install --save-dev @sadikkhan02/test-utils vitest
```

* * *

## 1\. 适配器契约测试套件

每个NotifyKit适配器（电子邮件、短信、推送）都必须符合标准的提供者接口和错误分类契约。使用 `runAdapterContractTests`，您可以在几分钟内验证自定义适配器。

### 示例：运行契约套件

```typescript
import { describe, it, expect, vi } from 'vitest';
import { runAdapterContractTests } from '@sadikkhan02/test-utils';
import { MyEmailProvider, metadata } from '../src/index.js';

runAdapterContractTests({
  providerName: 'my-email',
  channel: 'email',
  metadata,
  createSuccessProvider: () => new MyEmailProvider({ mockTransport: true }),
  createAuthFailingProvider: () => new MyEmailProvider({ authError: true }),
  createNetworkFailingProvider: () => new MyEmailProvider({ networkError: true }),
  validOptions: {
    to: 'user@example.com',
    from: 'noreply@notifykit.dev',
    subject: 'Welcome',
    html: '<h1>Welcome!</h1>',
  },
  invalidOptions: {
    to: '',
    from: '',
    subject: '',
    html: '',
  },
  sampleSecret: 'my-secret-key-12345',
});
```

### 什么 `runAdapterContractTests` 断言

1.  **元数据的一致性**:验证 `metadata.name`， `metadata.channel`，非空 `requiredEnv`.
2.  **提供者的身份**:检查 `provider.name === metadata.name` 并确保规范的交付方法(`sendEmail`， `sendSms`，或者 `sendPush`)被实现。
3.  **交付成功**:断言 `{ success: true, messageId: string }` 成功交付。
4.  **永久故障分类**:断言 `{ success: false, retryable: false }` 与可操作的 `error` 关于身份验证/凭证失败。
5.  **暂态故障分类**:断言 `{ success: false, retryable: true }` 与可操作的 `error` 在网络/超时失败时。
6.  **畸形输入安全**：断言提供程序返回 `{ success: false, retryable: false }` 优雅地处理格式错误的输入，而不会抛出未处理的异常。
7.  **零凭证暴露**验证原始秘密、承载令牌和私钥头在返回的错误消息中永远不会泄露。

* * *

## 2\. 内存中模拟提供程序

在应用程序单元和集成测试中轻松模拟通知传递，无需网络I/O或凭据：

```typescript
import {
  createMockEmailProvider,
  createMockSmsProvider,
  createMockPushProvider,
} from '@sadikkhan02/test-utils';

const mockEmail = createMockEmailProvider({ name: 'test-smtp' });
const mockSms = createMockSmsProvider({ name: 'test-sms' });

// Send a test email
await mockEmail.sendEmail({
  to: 'user@example.com',
  from: 'app@example.com',
  subject: 'Test',
  html: '<p>Test</p>',
});

// Inspect recorded calls
console.log(mockEmail.calls.length); // 1
console.log(mockEmail.calls[0].to); // 'user@example.com'

// Simulate failure
mockEmail.setResult({ success: false, error: 'Rate limit exceeded', retryable: true });
```

* * *

## 3\. 确定性测试装置

生成一致的、模式有效的接收者、作业和结果：

```typescript
import {
  createTestRecipient,
  createTestNotificationJob,
  createMockProviderResult,
} from '@sadikkhan02/test-utils';

const emailRecipient = createTestRecipient('email', { email: 'custom@example.com' });
const smsRecipient = createTestRecipient('sms');
const pushRecipient = createTestRecipient('push');

const job = createTestNotificationJob('email', {
  templateId: 'order-confirmed',
  variables: { orderId: '123' },
});
```

* * *

## 4\. 安全的本地Redis帮手

当使用真正的Redis运行集成测试时，防止对远程或生产实例的意外执行：

```typescript
import { isSafeLocalRedisUrl, cleanupTestRedis } from '@sadikkhan02/test-utils';

// Fails closed if REDIS_URL is not 127.0.0.1 or localhost
await cleanupTestRedis();
```

* * *

## 许可证

麻省理工学院

## 常见问题

### @sadikkhan02/test-utils 是什么？

用于NotifyKit的确定性测试实用程序和适配器契约遵从套件

### 如何安装 @sadikkhan02/test-utils？

在项目目录运行 npm install @sadikkhan02/test-utils，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vitest（\>=1\.0\.0 \|\| \>=2\.0\.0 \|\| \>=3\.0\.0 \|\| \>=4\.0\.0 \|\| \>=5\.0\.0）、@sadikkhan02/notifykit（^1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @sadikkhan02/test-utils 支持 TypeScript 吗？

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

### @sadikkhan02/test-utils 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @sadikkhan02/test-utils 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @sadikkhan02/test-utils 可以商用吗？

@sadikkhan02/test-utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @sadikkhan02/test-utils 还在维护吗？

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