Jest如何对异步函数抛出且被捕获的错误编写expect断言

原有写法的错误原因 #

• 捕获到的错误对象是Error类（此处为TypeError）的实例，并非字符串，直接用toBe()做严格全等对比字符串，永远不可能匹配成功。
• 直接把Error实例传给toMatch()匹配器会报错，该匹配器要求入参是字符串或正则表达式，错误的具体文本存储在实例的message属性上。
• 使用rejects断言时如果没有添加await，测试进程会在Promise状态变更前提前结束，无法拿到抛出的错误对象，导致断言失败。

推荐写法 #

写法1：简洁的rejects断言（官方推荐） #

不需要自己写try/catch逻辑，Jest内置的rejects匹配器会自动等待Promise状态变更、捕获抛出的错误：

it('should throw an error', async () => {
  // 断言前必须加await，否则会提前结束测试
  await expect(processor({}, MODULE_CONFIG)).rejects.toThrow(TypeError);
  // 匹配错误信息，支持字符串子串或正则，不需要写全错误文本
  await expect(processor({}, MODULE_CONFIG)).rejects.toThrow(/Cannot read properties of undefined.*'match'/);
});

如果要合并断言也可以直接写：

it('should throw an error', async () => {
  await expect(processor({}, MODULE_CONFIG)).rejects.toThrow(
    new TypeError("Cannot read properties of undefined (reading 'match')")
  );
});

写法2：try/catch 模式（适配原有代码结构） #

如果习惯手动捕获错误，记得判断错误实例的属性，同时加兜底逻辑防止函数未抛错时测试误通过：

it('should throw an error', async ()=> {
    expect.assertions(2);
    try {
        await processor({}, MODULE_CONFIG)
        // 兜底：如果函数没抛错，主动抛错让测试失败
        throw new Error('目标函数未按预期抛出错误');
    }
    catch (e) {
        // 先校验错误类型
        expect(e).toBeInstanceOf(TypeError);
        // 再校验错误信息，注意取e.message
        expect(e.message).toContain("Cannot read properties of undefined (reading 'match')");
    }
});

避坑提示 #

• 所有涉及异步Promise的断言，前面必须加await，否则断言不会等待异步逻辑执行完成。
• 不要用toBe()严格匹配完整错误字符串，不同Node/Jest版本下错误信息的格式可能有细微差异，用toThrow/toContain/正则做子串匹配即可，避免测试不稳定。
• 手动写try/catch时不要漏了兜底抛错逻辑，否则如果目标函数没抛错，catch块里的断言不会执行，测试会误判为通过。

内容的提问来源于stack exchange，提问作者stackers