# 客户的 staging 宕机了，测试照样能跑

> Vitest 配合 MSW 在网络层拦截请求，不改客户端代码，在笔记本上就能测 200、401、404 和 500。

原文: https://fdetimes.net/zh/guides/test-customer-api-vitest-msw/

周五下午，你正赶着完成与客户 CRM 的集成，对方的 staging 环境突然挂了，而唯一有权限重启它的人在休假。如果你的测试套件必须调用真实系统，那这一周剩下的时间你只能在没有测试的情况下干活。

每位前线部署工程师（FDE）迟早都会遇到这种情况，因为他们的代码依赖自己无法控制的 API。本文给出另一种做法：用 Vitest 测试真实的客户端，让 MSW 扮演客户的 API。

选择 MSW 的理由很简单。Vitest 官方文档推荐用 Mock Service Worker 来模拟网络请求。MSW 可以拦截 HTTP、GraphQL、SSE 和 WebSocket 流量，其 Node 集成并不绑定 Vitest，所以这里学到的东西在其他项目中同样适用。

## 要做什么，需要什么

你要写一个函数 `getCustomer(id, token)`，调用 `crm.example.com` 上一个假想的 CRM API，再写四个测试：成功、缺少 token、客户不存在和服务器错误。所有测试都不访问真实网络。

你需要 Node.js、一个 TypeScript 项目，以及两个开发依赖：`vitest` 和 `msw`。下面是最简命令；如果项目要求特定版本，请查阅各库的文档。

```bash
npm install -D vitest msw
```

## 第 1 步：按真实运行的方式写客户端

要测的是将在客户现场运行的代码，所以先把它写出来，不要为 Mock 预留任何钩子。

```ts
// src/crm.ts
export async function getCustomer(id: string, token: string) {
  const res = await fetch(`https://crm.example.com/api/customers/${id}`, {
    headers: { authorization: `Bearer ${token}` },
  })
  if (res.status === 404) return null
  if (!res.ok) throw new Error(`CRM 错误 ${res.status}`)
  return res.json()
}
```

检查：这个文件没有从 MSW 导入任何东西，客户端并不知道自己正在被测试。MSW 的立场是，API Mock 应该独立成一层；Mock 放在网络层，应用代码就能保持原样。

## 第 2 步：为正常路径写一个 handler

在 MSW 中，请求 handler 负责拦截请求并返回响应。handler 用 `http.*` 辅助函数编写，resolver 会收到 `request`、`params` 和 `cookies` 等属性。

```ts
// src/mocks/handlers.ts
import { http } from 'msw'

export const handlers = [
  http.get('https://crm.example.com/api/customers/:id', ({ request, params }) => {
    if (!request.headers.get('authorization')) {
      return new Response(null, { status: 401 })
    }
    return Response.json({ id: params.id, name: 'Company A', tier: 'gold' })
  }),
]
```

handler 返回的是标准的 Fetch API `Response`，客户端拿到的对象和生产环境中完全一样。对 `authorization` 请求头的检查是一种简化模拟：handler 像真实服务器一样，拒绝没有 token 的请求。

Kent C. Dodds 也推荐这种做法：搭一个像真实服务器那样处理请求的 Mock 服务器，而不是去 Mock fetch 函数。

## 第 3 步：服务器、setup 文件和严格模式

在 Node 中，从 `msw/node` 导入 `setupServer`，把 handler 传进去。

```ts
// src/mocks/server.ts
import { setupServer } from 'msw/node'
import { handlers } from './handlers'

export const server = setupServer(...handlers)
```

接下来是生命周期：测试运行前启动服务器，测试之间重置 handler，全部结束后关闭服务器。`server.listen()` 是同步的，不需要 `await`。

```ts
// vitest.setup.ts
import { beforeAll, afterEach, afterAll } from 'vitest'
import { server } from './src/mocks/server'

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
afterEach(() => server.resetHandlers())
afterAll(() => server.close())
```

```ts
// vitest.config.ts（简化版）
import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { setupFiles: ['./vitest.setup.ts'] } })
```

最关键的一行是 `onUnhandledRequest: 'error'`，这也是 Vitest 文档给出的配置。请求打到没有 handler 的端点时，MSW 会抛出错误，而不是放任请求溜到客户的真实系统。对 FDE 来说，这道护栏能防止有人只是跑了一下 `npm test`，就往客户的生产环境里写入垃圾数据。

## 第 4 步：逐个覆盖错误场景

`server.use()` 会在运行时把 handler 插到列表最前面。用它在特定测试中替换正常路径的响应。覆盖会一直生效，直到被重置，这就是 `resetHandlers()` 放在 `afterEach` 里的原因。

```ts
// src/crm.test.ts
import { describe, it, expect } from 'vitest'
import { http } from 'msw'
import { server } from './mocks/server'
import { getCustomer } from './crm'

const url = 'https://crm.example.com/api/customers/:id'

describe('getCustomer', () => {
  it('有 token 时返回客户', async () => {
    const c = await getCustomer('42', 'tok')
    expect(c.name).toBe('Company A')
  })

  it('缺少 token 时抛出错误', async () => {
    await expect(getCustomer('42', '')).rejects.toThrow('401')
  })

  it('客户不存在时返回 null', async () => {
    server.use(http.get(url, () => new Response(null, { status: 404 })))
    expect(await getCustomer('999', 'tok')).toBeNull()
  })

  it('CRM 返回 500 时抛出错误', async () => {
    server.use(http.get(url, () => new Response(null, { status: 500 })))
    await expect(getCustomer('42', 'tok')).rejects.toThrow('500')
  })
})
```

检查：运行 `npx vitest run`，会看到三个测试通过，一个失败，即“缺少 token 时抛出错误”。原因是 token 为空时，客户端仍然会发送值为 `Bearer` 的 `authorization` 请求头，handler 把它当作已认证，返回 200，函数也就不会抛错。

这里测试失败是好事。这个 bug 是真实存在的，就藏在第 1 步的客户端里；没有这个测试，它就会被带进客户的环境。修复方法是只在有 token 时才发送这个请求头：

```ts
// src/crm.ts（修复后）
export async function getCustomer(id: string, token: string) {
  const headers: Record<string, string> = {}
  if (token) headers.authorization = `Bearer ${token}`

  const res = await fetch(`https://crm.example.com/api/customers/${id}`, { headers })
  if (res.status === 404) return null
  if (!res.ok) throw new Error(`CRM 错误 ${res.status}`)
  return res.json()
}
```

再次运行 `npx vitest run`，这次四个测试应当全部通过。没有 token 的请求不带请求头，handler 返回 401，客户端抛出 `CRM 错误 401`，和测试的预期一致。

## 第 5 步：故意弄坏，证明测试能发现错误

把客户端 URL 中的 `customers` 改成 `customer`，再跑一遍测试。所有测试都应该失败，因为请求匹配不到任何 handler，`onUnhandledRequest: 'error'` 会抛出错误。

Kent C. Dodds 解释了这一步为什么重要：在网络层做 Mock 时，如果 fetch 调用方式不对，handler 根本不会被调用，测试就会失败，这正是应有的结果。手写的 `fetch` Mock 不管你调用什么 URL 都返回预设数据，这种拼写错误就会被放过。

**要点:** 在网络层做 Mock，测试才能同时发现你发出的请求本身的错误。

## 常见错误

第一个是忘了调用 `resetHandlers()`。某个测试里的 500 handler 残留下来，会让下一个测试随运行顺序出现不可预测的失败。如果一个测试单独跑能通过，整套跑却失败，首先怀疑这一点。

第二个是为了“少点麻烦”，把 `onUnhandledRequest` 调成更宽松的选项。代价是请求会在无人察觉的情况下直接打到客户的真实 API。第三个是在默认 handler 里塞进太多逻辑：默认 handler 应保持为干净的正常路径，特殊情况放到单个测试的 `server.use()` 里。

## 这项技能在客户现场怎么用

以项目第一周为例：客户交来了 API 文档和几个示例响应，但还没开通 staging 权限。第一天你就可以把这些示例做成 handler，写出带 401、404 和 500 测试的客户端，一次真实调用都不用发。

权限开通后，对齐工作就变成拿真实响应和 handler 做比较。两者不一致的地方，就是需要回头找客户确认的地方，而且你拿出的是一个具体的测试，而不是一种感觉。

如果你的目标是 FDE 岗位，让作品集仓库证明你能和自己无法控制的系统做集成：一个调用公开 API 的客户端，配一套开启了 `onUnhandledRequest: 'error'`、每个错误码各有一个测试的 MSW 测试套件。简历上要写明你在沙箱环境还不存在时就测试了集成，而不只是在技能栏里列一个“Vitest”。

下次客户的 staging 又在周五下午宕机，你的测试照样能跑。

**本周动手试试:**

- 挑一个代码会调用的客户端点，为正常路径写一个 MSW handler，再用 server.use() 写一个 500 错误测试。
- 在 Vitest 的 setup 文件中开启 onUnhandledRequest: 'error'，重新运行整套测试，看看还有哪些请求在往外发。
- 故意把客户端 URL 改错一个字符，确认测试会失败。如果仍然通过，说明你的 Mock 放错了层。

## 信源

- [Quick start – Mock Service Worker](https://mswjs.io/docs/quick-start)

- [Node.js integration – Mock Service Worker](https://mswjs.io/docs/integrations/node)

- [Mocking Requests | Guide | Vitest](https://vitest.dev/guide/mocking/requests)

- [server.use() – Mock Service Worker](https://mswjs.io/docs/api/setup-server/use)

- [Intercepting requests – Mock Service Worker](https://mswjs.io/docs/http/intercepting-requests)

- [Philosophy – Mock Service Worker](https://mswjs.io/docs/philosophy)

- [Stop mocking fetch – Kent C. Dodds](https://kentcdodds.com/blog/stop-mocking-fetch)
