Jest测试beforeAll创建用户时出现超时错误的排查与解决

问题场景 #

在Jest测试的beforeAll钩子中执行用户创建操作时触发超时错误，相关代码及错误信息如下：

辅助工具代码（helper.js） #

import { ExampleModel } from '@models/Example/Example.model';
import User from '../../../models/User';
import { mAdmin, mUser } from './mock-data';
import { to } from '../../../../test/util';

async function createUser() {
  const user = new User(mUser);
  const { err, savedUser } = await to(user.save());

  return savedUser;
}

export { createUser };

测试文件代码（example.test.ts） #

import httpClient from '../../../test/controller/httpClient';
import { to } from '../../../test/util';
import { createUser } from './test/helper';

describe('ExampleController', () => {
  beforeAll(async () => {
    const user = await createUser();
  }, 10000);

  describe('GET /example', () => {
    it('should return 200 OK', async () => {
      const { err, res } = await to(httpClient.get('/example'));
      expect(err).toBeNull();
      expect(res.status).toBe(200);
    });
  });
});

错误信息 #

thrown: "Exceeded timeout of 10000 ms for a hook.
Add a timeout value to this test to increase the timeout, if this is a long-running test."

原因分析 #

• 数据库操作阻塞：user.save()执行时，可能存在数据库连接未就绪、测试库配置错误（比如连接到远程慢数据库），或者mock数据不符合User模型校验规则，导致写入操作一直处于挂起状态。
• 错误被静默吞掉：使用的to工具函数捕获了user.save()的错误，但createUser未对err做任何处理——如果保存失败，函数不会抛出异常，只会返回undefined，beforeAll会一直等待异步操作完成，直到超时。
• 超时阈值仍不足：10000ms看似足够，但如果是测试环境首次启动数据库连接、或有大量前置数据初始化，实际所需时间可能超过这个值。

解决方法 #

1. 主动抛出数据库操作错误 #

修改createUser函数，捕获错误后立即抛出，让Jest快速感知失败并输出具体原因：

async function createUser() {
  const user = new User(mUser);
  const { err, savedUser } = await to(user.save());
  
  // 新增错误处理，避免静默失败
  if (err) {
    throw new Error(`创建用户失败: ${err.message}`);
  }
  
  return savedUser;
}

2. 确保数据库连接就绪 #

在测试最外层beforeAll中先完成数据库初始化，确认连接成功后再执行用户创建：

// 假设你有数据库初始化工具函数
import { initDB } from '../../../test/util/db';

describe('ExampleController', () => {
  beforeAll(async () => {
    // 先等待数据库连接初始化完成
    await initDB();
    const user = await createUser();
  }, 15000); // 适当延长超时时间

  // ... 其他测试代码
});

3. 调整超时时间或优化数据库环境 #

• 临时延长beforeAll的超时时间，比如设置为15000或20000ms，适配首次数据库连接的耗时
• 测试环境优先使用本地轻量数据库（如SQLite内存库、本地MongoDB），避免远程数据库的网络延迟

4. 验证mock数据合法性 #

检查mUser是否完全符合User模型的字段规则：

• 确认没有缺少必填字段
• 字段类型、格式与模型定义一致
• 不存在违反唯一约束的字段值

这些问题会导致user.save()因校验失败而挂起或重试，最终触发超时。

内容的提问来源于stack exchange，提问作者Serkan Gün