客户的 staging 宕机了,测试照样能跑
Vitest 配合 MSW 在网络层拦截请求,不改客户端代码,在笔记本上就能测 200、401、404 和 500。
要点速览
- MSW 在网络层拦截请求,使用标准的 Fetch API Request 和 Response 对象,客户端代码无需改动。
- 开启 onUnhandledRequest: 'error',没有 handler 的请求会直接让测试失败,而不会误打到客户的真实系统。
- 默认 handler 只放正常路径,在单个测试里用 server.use() 制造错误,每个测试结束后调用 resetHandlers()。
周五下午,你正赶着完成与客户 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。下面是最简命令;如果项目要求特定版本,请查阅各库的文档。
npm install -D vitest msw
第 1 步:按真实运行的方式写客户端
要测的是将在客户现场运行的代码,所以先把它写出来,不要为 Mock 预留任何钩子。
// 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 等属性。
// 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 传进去。
// src/mocks/server.ts
import { setupServer } from 'msw/node'
import { handlers } from './handlers'
export const server = setupServer(...handlers)
接下来是生命周期:测试运行前启动服务器,测试之间重置 handler,全部结束后关闭服务器。server.listen() 是同步的,不需要 await。
// 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())
// 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 里的原因。
// 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 时才发送这个请求头:
// 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 都返回预设数据,这种拼写错误就会被放过。
常见错误
第一个是忘了调用 resetHandlers()。某个测试里的 500 handler 残留下来,会让下一个测试随运行顺序出现不可预测的失败。如果一个测试单独跑能通过,整套跑却失败,首先怀疑这一点。
第二个是为了“少点麻烦”,把 onUnhandledRequest 调成更宽松的选项。代价是请求会在无人察觉的情况下直接打到客户的真实 API。第三个是在默认 handler 里塞进太多逻辑:默认 handler 应保持为干净的正常路径,特殊情况放到单个测试的 server.use() 里。
这项技能在客户现场怎么用
以项目第一周为例:客户交来了 API 文档和几个示例响应,但还没开通 staging 权限。第一天你就可以把这些示例做成 handler,写出带 401、404 和 500 测试的客户端,一次真实调用都不用发。
权限开通后,对齐工作就变成拿真实响应和 handler 做比较。两者不一致的地方,就是需要回头找客户确认的地方,而且你拿出的是一个具体的测试,而不是一种感觉。
如果你的目标是 FDE 岗位,让作品集仓库证明你能和自己无法控制的系统做集成:一个调用公开 API 的客户端,配一套开启了 onUnhandledRequest: 'error'、每个错误码各有一个测试的 MSW 测试套件。简历上要写明你在沙箱环境还不存在时就测试了集成,而不只是在技能栏里列一个“Vitest”。
下次客户的 staging 又在周五下午宕机,你的测试照样能跑。
这篇文章对你有帮助吗?
感谢你的反馈!