Jest で「Exceeded timeout of 5000 ms for a test」が出てテストが完了できない
Exceeded timeout of 5000 ms は、終わらない非同期処理を直すか、タイムアウト値を延ばせば直る。
resolve されない Promise や done の呼び忘れを先に疑う。
公開: 更新:
npx jest … FAIL ./slow.test.js (5.145 s) ✕ 重い統合テスト (5001 ms) ● 重い統合テスト
npx jest … Tests: 1 passed, 1 total Snapshots: 0 total Time: 8.147 s Ran all test suites.
2026-09-06 に node:20(Node.js 20.20.2 / npm 10.8.2) で実際に打って取った出力。検証環境の詳細
要約
thrown: "Exceeded timeout of 5000 ms for a test." は、1 つのテストが Jest の既定タイムアウトである 5 秒以内に終わらなかったときに出る。
本当に時間のかかるテストならタイムアウト値を延ばせばよい。
ただし体感では、原因の多くは「終わらない非同期処理」で、タイムアウトを延ばしても解決しない。
まずテストが何を待ち続けているのかを確認する。
実行例
8 秒かけて resolve する Promise を待つテストを既定設定のまま走らせると、5001 ms の時点で Exceeded timeout of 5000 ms for a test. が投げられ、終了コード 1 で失敗する。
解決策 1 のとおり it の第 3 引数に 10000 を渡すと、同じテストが 8001 ms かけて完走し PASS になる。
$ npx jest
FAIL ./slow.test.js (5.145 s)
✕ 重い統合テスト (5001 ms)
● 重い統合テスト
thrown: "Exceeded timeout of 5000 ms for a test.
Add a timeout value to this test to increase the timeout, if this is a long-running test. See https://jestjs.io/docs/api#testname-fn-timeout."
1 | const { runHeavyJob } = require('./slow');
2 |
> 3 | it('重い統合テスト', async () => {
| ^
4 | const result = await runHeavyJob();
5 | expect(result.ok).toBe(true);
6 | });
at Object.it (slow.test.js:3:1)
Test Suites: 1 failed, 1 total
Tests: 1 failed, 1 total
Snapshots: 0 total
Time: 5.159 s
Ran all test suites.
Jest did not exit one second after the test run has completed.
'This usually means that there are asynchronous operations that weren't stopped in your tests. Consider running Jest with `--detectOpenHandles` to troubleshoot this issue.
$ echo $?
1$ npx jest
PASS ./slow.test.js (8.133 s)
✓ 重い統合テスト (8001 ms)
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 8.147 s
Ran all test suites.
$ echo $?
0— 2026-09-06 時点の出力
検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-09-06 検証(ほか 1 件)
- 検証日
- 実行環境
node:20Debian GNU/Linux 12 (bookworm)- バージョン
- Node.js 20.20.2
- npm 10.8.2
- Python 3.11.2
- Git 2.39.5
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. テスト単位でタイムアウトを延ばす
it("重い統合テスト", async () => {
const result = await runHeavyJob();
expect(result.ok).toBe(true);
}, 10000);第 3 引数にミリ秒を渡すと、そのテストだけタイムアウトが変わる。
2. 全体のタイムアウトを変更する
// jest.config.js
module.exports = {
testTimeout: 10000,
};ファイル単位なら jest.setTimeout(10000) をそのファイルの先頭やセットアップで呼ぶ。jest.setTimeout() は呼び出したテストファイルにだけ効く(jest オブジェクトの公式ドキュメント(新しいタブで開く))。
3. 終わらない非同期処理を直す
タイムアウトを延ばしても落ち続けるなら、待ち先が終わっていない。done 形式なら全分岐で done() が呼ばれるか、Promise 形式なら await の対象が本当に resolve されるかを確認する。
モックの戻り値を設定し忘れて、応答が永遠に返らないケースも多い。
4. フェイクタイマーを進める
jest.useFakeTimers();
// ...
jest.advanceTimersByTime(3000);フェイクタイマー有効時は setTimeout が実時間では発火しない。
タイマーを進めるか、そのテストでは jest.useRealTimers() に戻す。
よくある原因
- 本当に遅い: 外部 API・実 DB アクセス・重い計算など、5 秒を超える処理をそのまま実行している。
- done の呼び忘れ: コールバック形式のテストで
doneを受け取ったのに、分岐によっては一度も呼ばれない。 - await 漏れ・未解決の Promise: resolve されない Promise を待っている、またはモックの設定漏れで応答が返らない。
- フェイクタイマー:
jest.useFakeTimers()を有効にしたままsetTimeout依存の処理を実時間で待っている。