Jest测试超时时是否有方法执行指定自定义代码？

核心结论 #

Jest 原生没有提供onTimeout类的可配置回调。测试触发超时阈值时，Jest 会在 runner 层直接中断当前测试的异步执行上下文，不会预留钩子执行用户自定义的瞬时清理逻辑，这也是锁被持有后无法自动释放的根本原因——锁的释放逻辑本身就在被中断的异步链路里，没有执行机会。

你目前在用的afterEach统一释放锁是官方推荐的兜底思路，但可以通过针对性优化实现更高的执行效率，避免全局无差别清理的额外开销。

高效率锁清理实现方案 #

方案1：测试用例包装器（推荐单测内使用） #

封装专用的测试包装函数，自动追踪当前测试实际获取的锁实例，仅在测试结束（正常完成/报错/超时）时清理当前测试持有的锁，不需要全局遍历所有锁实例，开销极低：

import { Mutex } from 'async-mutex';

/**
 * 带自动锁清理的测试包装器
 * @param {string} testName 用例名称
 * @param {Function} testFn 用例逻辑，入参为自动埋点的mutex追踪方法
 * @param {number} timeout 用例超时时间
 */
const withMutexTest = (testName, testFn, timeout = 5000) => {
  const heldReleases = [];

  // 代理mutex的acquire方法，自动追踪当前测试拿到的锁释放函数
  const trackMutex = (mutexInstance) => {
    const originalAcquire = mutexInstance.acquire.bind(mutexInstance);
    mutexInstance.acquire = async (...acquireArgs) => {
      const release = await originalAcquire(...acquireArgs);
      const wrappedRelease = () => {
        const idx = heldReleases.indexOf(wrappedRelease);
        if (idx > -1) heldReleases.splice(idx, 1);
        return release();
      };
      heldReleases.push(wrappedRelease);
      return wrappedRelease;
    };
    return mutexInstance;
  };

  test(testName, async () => {
    try {
      await testFn(trackMutex);
    } finally {
      // 外层finally不受测试内部异步中断影响，一定会执行
      await Promise.all(heldReleases.map(release => release()));
    }
  }, timeout);
};

// 用法示例
withMutexTest('依赖互斥锁的业务逻辑测试', async (trackMutex) => {
  const bizMutex = trackMutex(new Mutex());
  const release = await bizMutex.acquire();
  // 写入测试逻辑
}, 3000);

方案2：自定义测试环境事件监听（适合全局统一配置） #

如果不想修改单个测试的写法，可以自定义Jest测试环境，监听测试失败事件，仅在失败原因为超时时触发预注册的锁清理逻辑，正常执行的测试完全不会触发额外开销：

// custom-jest-environment.js
const NodeEnvironment = require('jest-environment-node').default;

class MutexAwareNodeEnv extends NodeEnvironment {
  async handleTestEvent(event) {
    // 仅在测试超时失败时触发清理
    if (
      event.name === 'test_fn_failure' &&
      event.error?.message?.includes('timed out') &&
      typeof this.global.__mutexCleanup === 'function'
    ) {
      await this.global.__mutexCleanup();
    }
  }
}

module.exports = MutexAwareNodeEnv;

在Jest配置中指定testEnvironment: './custom-jest-environment.js'，之后只需要在锁初始化的位置把对应实例的清理方法挂载到global.__mutexCleanup上即可。

避坑提示 #

• 不要依赖测试函数内部的try/finally做锁释放：Jest触发超时时会直接斩断当前测试的异步调用栈，测试内部的finally块没有执行机会，清理逻辑必须放在Jest可管控的外层上下文（包装器外层、环境事件钩子、afterEach）中。
• 跨测试共享的锁实例建议在setupFilesAfterEach中做重置，避免单文件的锁泄漏扩散到整个测试套件。

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