## 🎯 测试编写最佳实践

### Mock 数据策略：追求"低成本的真实性" 📋

**核心原则**: 测试数据应默认追求真实性，只有在引入"高昂的测试成本"时才进行简化。

#### 什么是"高昂的测试成本"？

"高成本"指的是测试中引入了外部依赖，使测试变慢、不稳定或复杂：

- **文件 I/O 操作**：读写硬盘文件

- **网络请求**：HTTP 调用、数据库连接

- **系统调用**：获取系统时间、环境变量等

#### ✅ 推荐做法：Mock 依赖，保留真实数据

```typescript

// ✅ 好的做法：Mock I/O 操作，但使用真实的文件内容格式

describe('parseContentType', () => {

beforeEach(() => {

// Mock 文件读取操作（避免真实 I/O）

vi.spyOn(fs, 'readFileSync').mockImplementation((path) => {

// 但返回真实的文件内容格式

if (path.includes('.pdf')) return '%PDF-1.4\n%âãÏÓ'; // 真实 PDF 文件头

if (path.includes('.png')) return '\x89PNG\r\n\x1a\n'; // 真实 PNG 文件头

return '';

});

});

it('should detect PDF content type correctly', () => {

const result = parseContentType('/path/to/file.pdf');

expect(result).toBe('application/pdf');

});

});

// ❌ 过度简化：使用不真实的数据

describe('parseContentType', () => {

it('should detect PDF content type correctly', () => {

// 这种简化数据没有测试价值

const result = parseContentType('fake-pdf-content');

expect(result).toBe('application/pdf');

});

});

```

#### 🎯 真实标识符的价值

```typescript

// ✅ 使用真实的提供商标识符

it('should parse OpenAI model list correctly', () => {

const result = parseModelString('openai', '+gpt-4,+gpt-3.5-turbo');

expect(result.add).toHaveLength(2);

expect(result.add[0].id).toBe('gpt-4');

});

// ❌ 使用占位符标识符（价值较低）

it('should parse model list correctly', () => {

const result = parseModelString('test-provider', '+model1,+model2');

expect(result.add).toHaveLength(2);

// 这种测试对理解真实场景帮助不大

});

```

### 错误处理测试：测试"行为"而非"文本" ⚠️

**核心原则**: 测试应该验证程序在错误发生时的行为是可预测的，而不是验证易变的错误信息文本。

#### ✅ 推荐的错误测试方式

```typescript

// ✅ 测试是否抛出错误

it('should throw error when invalid input provided', () => {

expect(() => processInput(null)).toThrow();

});

// ✅ 测试错误类型（最推荐）

it('should throw ValidationError for invalid data', () => {

expect(() => validateUser({})).toThrow(ValidationError);

});

// ✅ 测试错误属性而非消息文本

it('should throw error with correct error code', () => {

expect(() => processPayment({})).toThrow(

expect.objectContaining({

code: 'INVALID_PAYMENT_DATA',

statusCode: 400,

}),

);

});

```

#### ❌ 应避免的做法

```typescript

// ❌ 过度依赖具体错误信息文本

it('should throw specific error message', () => {

expect(() => processUser({})).toThrow('用户数据不能为空，请检查输入参数');

// 这种测试很脆弱，错误文案稍有修改就会失败

});

```

#### 🎯 例外情况：何时可以测试错误信息

```typescript

// ✅ 测试标准 API 错误（这是契约的一部分）

it('should return proper HTTP error for API', () => {

expect(response.statusCode).toBe(400);

expect(response.error).toBe('Bad Request');

});

// ✅ 测试错误信息的关键部分（使用正则）

it('should include field name in validation error', () => {

expect(() => validateField('email', '')).toThrow(/email/i);

});

```

### 疑难解答：警惕模块污染 🚨

**识别信号**: 当你的测试出现以下"灵异"现象时，优先怀疑模块污染：

- 单独运行某个测试通过，但和其他测试一起运行就失败

- 测试的执行顺序影响结果

- Mock 设置看起来正确，但实际使用的是旧的 Mock 版本

#### 典型场景：动态 Mock 同一模块

```typescript

// ❌ 容易出现模块污染的写法

describe('ConfigService', () => {

it('should work in development mode', async () => {

vi.doMock('./config', () => ({ isDev: true }));

const { getSettings } = await import('./configService'); // 第一次加载

expect(getSettings().debugMode).toBe(true);

});

it('should work in production mode', async () => {

vi.doMock('./config', () => ({ isDev: false }));

const { getSettings } = await import('./configService'); // 可能使用缓存的旧版本！

expect(getSettings().debugMode).toBe(false); // ❌ 可能失败

});

});

// ✅ 使用 resetModules 解决模块污染

describe('ConfigService', () => {

beforeEach(() => {

vi.resetModules(); // 清除模块缓存，确保每个测试都是干净的环境

});

it('should work in development mode', async () => {

vi.doMock('./config', () => ({ isDev: true }));

const { getSettings } = await import('./configService');

expect(getSettings().debugMode).toBe(true);

});

it('should work in production mode', async () => {

vi.doMock('./config', () => ({ isDev: false }));

const { getSettings } = await import('./configService');

expect(getSettings().debugMode).toBe(false); // ✅ 测试通过

});

});

```

#### 🔧 排查和解决步骤

1. **识别问题**: 测试失败时，首先问自己："是否有多个测试在 Mock 同一个模块？"

2. **添加隔离**: 在 `beforeEach` 中添加 `vi.resetModules()`

3. **验证修复**: 重新运行测试，确认问题解决

**记住**: `vi.resetModules()` 是解决测试"灵异"失败的终极武器，当常规调试方法都无效时，它往往能一针见血地解决问题。

- **数据策略**: 默认追求真实性，只有高成本（I/O、网络等）时才简化

- **错误测试**: 测试错误类型和行为，避免依赖具体的错误信息文本

- **模块污染**: 测试"灵异"失败时，优先怀疑模块污染，使用 `vi.resetModules()` 解决

- Type: Optional

- Description: Enables FAL as a model provider by default. Set to `0` to disable the FAL service.

- Default: `1`

- Example: `0`

- Type: Required

- Description: This is the API key you applied for in the FAL service.

- Default: -

- Example: `fal-xxxxxx...xxxxxx`

- Type: Optional

- Description: Used to control the FAL model list. Use `+` to add a model, `-` to hide a model, and `model_name=display_name` to customize the display name of a model. Separate multiple entries with commas. The definition syntax follows the same rules as other providers' model lists.

- Default: `-`

- Example: `-all,+fal-model-1,+fal-model-2=fal-special`

The above example disables all models first, then enables `fal-model-1` and `fal-model-2` (displayed as `fal-special`).

- 类型：可选

- 描述：默认启用 FAL 作为模型供应商，当设为 0 时关闭 FAL 服务

- 默认值：`1`

- 示例：`0`

- 类型：必选

- 描述：这是你在 FAL 服务中申请的 API 密钥

- 默认值：-

- 示例：`fal-xxxxxx...xxxxxx`

- 类型：可选

- 描述：用来控制 FAL 模型列表，使用 `+` 增加一个模型，使用 `-` 来隐藏一个模型，使用 `模型名=展示名` 来自定义模型的展示名，用英文逗号隔开。模型定义语法规则与其他 provider 保持一致。

- 默认值：`-`

- 示例：`-all,+fal-model-1,+fal-model-2=fal-special`

上述示例表示先禁用所有模型，再启用 `fal-model-1` 和 `fal-model-2`（显示名为 `fal-special`）。

title: Resolving AI Image Generation Timeout on Vercel

description: >-

tags:

- Vercel

- AI Image Generation

- Timeout

- Fluid Compute

- gpt-image-1

When using AI image generation models (such as `gpt-image-1`) on Vercel, you may encounter timeout errors. This occurs because AI image generation typically requires more than 1 minute to complete, which exceeds Vercel's default function execution time limit.

Common error symptoms include:

- Function timeout errors during image generation

- Failed image generation requests after approximately 60 seconds

- "Function execution timed out" messages

In your Vercel function logs, you may see entries like this:

The key indicators are:

- **Status Code**: `504` (Gateway Timeout)

- **Endpoint**: `/trpc/async/image.createImage` or similar image generation endpoints

- **Timing**: Usually occurs around 60 seconds after the request starts

For projects created before Vercel's dashboard update, you can resolve this issue by enabling Fluid Compute, which extends the maximum execution duration to 300 seconds.

1. Go to your project dashboard on Vercel

2. Navigate to the **Settings** tab

3. Find the **Functions** section

4. Enable **Fluid Compute** as shown in the screenshot below:


5. After enabling, the maximum execution duration will be extended to 300 seconds by default

- **For new projects**: Newer Vercel projects have Fluid Compute enabled by default, so this issue primarily affects legacy projects

For more information about Vercel's function limitations and Fluid Compute:

- [Vercel Fluid Compute Documentation](https://vercel.com/docs/fluid-compute)

- [Vercel Functions Limitations](https://vercel.com/docs/functions/limitations#max-duration)

title: 解决 Vercel 上 AI 绘画生图超时问题

description: 了解如何通过开启 Fluid Compute 来解决在 Vercel 上使用 gpt-image-1 等 AI 绘画模型时遇到的超时问题。

tags:

- Vercel

- AI 绘画

- 超时问题

- Fluid Compute

- gpt-image-1

在 Vercel 上使用 AI 绘画模型（如 `gpt-image-1`）时，您可能会遇到超时错误。这是因为 AI 绘画生成通常需要超过 1 分钟的时间，超出了 Vercel 默认的函数执行时间限制。

常见的错误症状包括：

- 图像生成过程中出现函数超时错误

- 图像生成请求在大约 60 秒后失败

- 出现 "函数执行超时" 的错误消息

在您的 Vercel 函数日志中，您可能会看到类似这样的条目：

关键指标包括：

- **状态码**: `504`（网关超时）

- **端点**: `/trpc/async/image.createImage` 或类似的图像生成端点

- **时间**: 通常在请求开始后约 60 秒出现

对于在 Vercel 控制台更新前创建的项目，您可以通过开启 Fluid Compute 来解决此问题，这将最大执行时长延长至 300 秒。

1. 前往您在 Vercel 上的项目控制台

2. 进入 **Settings**（设置）选项卡

3. 找到 **Functions**（函数）部分

4. 按照下方截图所示开启 **Fluid Compute**：


5. 开启后，最大执行时长将默认延长至 300 秒

- **新项目**：较新的 Vercel 项目默认已启用 Fluid Compute，因此此问题主要影响旧版项目

有关 Vercel 函数限制和 Fluid Compute 的更多信息：

- [Vercel Fluid Compute 文档](https://vercel.com/docs/fluid-compute)

- [Vercel 函数限制说明](https://vercel.com/docs/functions/limitations#max-duration)