Reactのタイマー処理をVitestで待たずにテストする方法
「保存しました」の通知(トースト)を3秒で消す、2段階認証の確認コードの再送信ボタンを30秒押せなくする、といった React のコンポーネントは、本物のタイマーのままテストすると、その時間だけテストが待たされます。Vitest の vi.useFakeTimers() でタイマーを偽物に替えると、時間を一瞬で進めて、3秒後や30秒後の画面を確かめられます。
ただし、React Testing Library と組み合わせると、userEvent のクリックや waitForElementToBeRemoved が終わらなくなることがあります。どこで止まるのかも、テストを動かして確かめました。
検証環境は Ubuntu 24.04、Node.js 22.23.4 です。使ったのは vitest 5.1.0、jsdom 31.0.0、@testing-library/react 16.3.3、@testing-library/dom 10.4.2、@testing-library/user-event 14.6.9、@testing-library/jest-dom 7.0.1、react / react-dom 19.3.1、typescript 7.0.2 です。テストのタイムアウトは3秒に設定しました。Jest の偽のタイマー、Vitest のブラウザーモード、requestAnimationFrame を使うコンポーネントは試していません。
3秒で消える通知を、待たずにテストする
テストするのは、ボタンを押すと「保存しました」を出し、3秒たったら消すコンポーネントです。
// src/SaveButton.tsx
import { useEffect, useState } from 'react';
// 押すと「保存しました」を出し、3秒たったら消す
export function SaveButton({ onSave }: { onSave: () => void }) {
const [saved, setSaved] = useState(false);
useEffect(() => {
if (!saved) return;
const id = setTimeout(() => setSaved(false), 3000);
return () => clearTimeout(id);
}, [saved]);
return (
<div>
<button
type="button"
onClick={() => {
onSave();
setSaved(true);
}}
>
保存
</button>
{saved && <p role="status">保存しました</p>}
</div>
);
}
Vitest の設定では、環境を jsdom にし、setup ファイルで @testing-library/jest-dom/vitest を読み込んでいます(toBeInTheDocument() などを使うため)。
テストでは、beforeEach で vi.useFakeTimers を呼んでタイマーを偽物にし、afterEach の vi.useRealTimers() で本物に戻します。時間は vi.advanceTimersByTime で進めます。
// src/SaveButton.test.tsx
import { act, fireEvent, render, screen } from '@testing-library/react';
import { afterEach, beforeEach, expect, test, vi } from 'vitest';
import { SaveButton } from './SaveButton';
beforeEach(() => {
vi.useFakeTimers();
});
afterEach(() => {
vi.useRealTimers();
});
test('3秒たつと「保存しました」が消える', () => {
render(<SaveButton onSave={() => {}} />);
fireEvent.click(screen.getByRole('button', { name: '保存' }));
expect(screen.getByRole('status')).toHaveTextContent('保存しました');
act(() => {
vi.advanceTimersByTime(2999);
});
expect(screen.getByRole('status')).toBeInTheDocument();
act(() => {
vi.advanceTimersByTime(1);
});
expect(screen.queryByRole('status')).not.toBeInTheDocument();
});
2999ms の時点では通知が残り、あと 1ms 進めると消えました。テストにかかった時間は 72ms です。本物のタイマーのまま waitForElementToBeRemoved で消えるのを待つテストも書いて比べると、こちらは 3063ms かかりました。
時間を進める vi.advanceTimersByTime() は、act で包んでいます。包まずに呼ぶと、通知が残ったままになり、テストは失敗しました。
FAIL src/pitfall-act.test.tsx > act で包まずにタイマーを進める
Error: expect(element).not.toBeInTheDocument()
expected document not to contain element, found <p
role="status"
>
保存しました
</p> instead
React の act の説明のとおり、act は、中で起きた更新を処理して DOM に反映してから戻ります。タイマーで state を変えるコンポーネントでは、時間を進める呼び出しを act の中に入れます。なお、この説明では await act(async () => ...) の形が勧められ、同期の形は将来なくすと書かれています。この記事では、タイマーを同期で進めるだけなので、同期の形で試しました。
偽のタイマーのままだと、userEvent や waitForElementToBeRemoved が終わらない
上のテストでは、クリックに fireEvent を使いました。同じテストを userEvent で書くと、テストは3秒のタイムアウトで落ちました。user-event の公式ドキュメントにある advanceTimers オプションの説明どおりに、時間を進める関数を渡しても同じでした。
test('advanceTimers を渡して userEvent でクリックする', async () => {
const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
render(<SaveButton onSave={() => {}} />);
await user.click(screen.getByRole('button', { name: '保存' }));
expect(screen.getByRole('status')).toBeInTheDocument();
});
FAIL src/pitfall-userevent.test.tsx > advanceTimers を渡して userEvent でクリックする
Error: Test timed out in 3000ms.
クリックそのものは済んでいました。user.click() の Promise を待たずに調べると、onSave は1回呼ばれていたのに、Promise は終わっていませんでした。そこで偽の時計を 0ms 進めると、Promise が終わりました。
onSave の呼び出し回数: 1 / click の完了: false
偽の時計を 0ms 進めたあと click の完了: true
止まっていたのは、React Testing Library が操作のあとに入れている待ち時間です。React Testing Library のソースコードの asyncWrapper は、操作が終わったあとに setTimeout(..., 0) で待ちます。Jest の偽のタイマーが使われているときだけ、自分で jest.advanceTimersByTime(0) を呼んで時計を進めます。偽のタイマーかどうかを判定する関数は、まず jest というグローバル変数があるかを確かめ、なければ false を返します。検証環境で調べると、Vitest の偽のタイマーを使っている間も globalThis.jest は undefined で、この関数は false を返しました。userEvent も、操作をこの asyncWrapper に包んで動かしていました。
shouldAdvanceTime で、偽の時計を少しずつ進める
vi.useFakeTimers() に、shouldAdvanceTime を true にして渡すと、userEvent のクリックが終わりました。偽の時計が、実際に過ぎた時間に合わせて(既定では 20ms ごとに)進むようになるオプションです。import は省きます。
beforeEach(() => {
vi.useFakeTimers({ shouldAdvanceTime: true });
});
afterEach(() => {
vi.useRealTimers();
});
test('shouldAdvanceTime: true なら userEvent のクリックが終わる', async () => {
const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
const onSave = vi.fn();
render(<SaveButton onSave={onSave} />);
await user.click(screen.getByRole('button', { name: '保存' }));
expect(onSave).toHaveBeenCalledTimes(1);
expect(screen.getByRole('status')).toBeInTheDocument();
act(() => {
vi.advanceTimersByTime(3000);
});
expect(screen.queryByRole('status')).not.toBeInTheDocument();
});
このテストは 78ms で通りました。3秒後の確かめ方は、前の節と同じく act の中で時間を進めます。
waitForElementToBeRemoved で、消えるのを待たない
偽のタイマー(shouldAdvanceTime なし)のまま、waitForElementToBeRemoved で通知が消えるのを待つテストも、3秒のタイムアウトで落ちました。
fireEvent.click(screen.getByRole('button', { name: '保存' }));
await waitForElementToBeRemoved(() => screen.queryByRole('status'));
Testing Library の waitFor のソースコードでは、待つ時間の上限を setTimeout で決め、Jest の偽のタイマーでないときは、setInterval と DOM の変化の監視で調べます。通知を消す setTimeout も偽物なので、時計を進めない限り DOM は変わらず、上限の setTimeout も動きません。タイマーで変わる表示は、act の中で時間を進めてから、getBy… や queryBy… で確かめます。
30秒の再送信ボタンを setInterval でテストする
確認コードを送ったあと、30秒は押せなくし、残りの秒数を出すボタンです。setInterval で1秒ごとに数を減らし、0になったら後片づけで止めます。
// src/ResendButton.tsx
import { useEffect, useState } from 'react';
// 確認コードを送ったあと、30秒は再送信できないボタン
export function ResendButton({ onResend }: { onResend: () => void }) {
const [left, setLeft] = useState(0);
const waiting = left > 0;
useEffect(() => {
if (!waiting) return;
const id = setInterval(() => {
setLeft((s) => s - 1);
}, 1000);
return () => clearInterval(id);
}, [waiting]);
return (
<button
type="button"
disabled={waiting}
onClick={() => {
onResend();
setLeft(30);
}}
>
{waiting ? `再送信(あと${left}秒)` : 'コードを再送信'}
</button>
);
}
1秒進めると「あと29秒」になり、さらに29秒進めると、ボタンが押せる状態に戻りました。vi.getTimerCount で、待っているタイマーが 0 になったこと(clearInterval が呼ばれたこと)も確かめています。import(読み込むのは ResendButton)と beforeEach・afterEach は省きます。
test('30秒たつと、もう一度押せる', () => {
const onResend = vi.fn();
render(<ResendButton onResend={onResend} />);
fireEvent.click(screen.getByRole('button'));
expect(screen.getByRole('button')).toBeDisabled();
expect(screen.getByRole('button')).toHaveTextContent('再送信(あと30秒)');
act(() => {
vi.advanceTimersByTime(1000);
});
expect(screen.getByRole('button')).toHaveTextContent('再送信(あと29秒)');
act(() => {
vi.advanceTimersByTime(29000);
});
expect(screen.getByRole('button')).toBeEnabled();
expect(screen.getByRole('button')).toHaveTextContent('コードを再送信');
expect(vi.getTimerCount()).toBe(0);
});
act の中の runAllTimers は、インターバルを止められない
時間を指定せずに、タイマーがなくなるまで全部動かす vi.runAllTimers もあります。このボタンは30秒で clearInterval を呼ぶので、終わりそうに見えます。ところが act の中で呼ぶと、1万回で打ち切られて失敗しました。
act(() => {
vi.runAllTimers();
});
FAIL src/pitfall-runall.test.tsx > runAllTimers で、終わるまで全部動かす
Error: Aborting after running 10000 timers, assuming an infinite loop!
1万回という上限は、Vitest の設定の fakeTimers.loopLimit の既定値です。
act の中の様子を調べると、1秒進めても、さらに30秒進めても、ボタンは「あと30秒」のままで、待っているタイマーも1つ残っていました。act を抜けたところで、はじめて「コードを再送信」に変わり、タイマーは0になりました。
act の中で1秒進めた: 再送信(あと30秒) / 待っているタイマー: 1
act の中でさらに30秒進めた: 再送信(あと30秒) / 待っているタイマー: 1
act を抜けたあと: コードを再送信 / 待っているタイマー: 0
act の中では、setLeft で変えた state が、act を抜けるまで画面に反映されません。再描画がないのでエフェクトの後片づけも動かず、clearInterval が呼ばれません。そのため、runAllTimers から見ると、インターバルがいつまでも残ります。

setInterval を使うコンポーネントでは、進める時間を決めて vi.advanceTimersByTime() を呼びます。Vitest の説明にあるとおり、vi.runOnlyPendingTimers は呼んだ時点で待っているタイマーだけを動かすので、このボタンでは1回分(「あと29秒」)進んで止まりました。
偽のタイマーでテストするときの早見表
| やりたいこと | 書き方 |
|---|---|
| 決めた時間だけ進める | act(() => { vi.advanceTimersByTime(ms) }) |
| いま待っているタイマーだけを動かす | act(() => { vi.runOnlyPendingTimers() }) |
| クリックする | fireEvent.click()。userEvent を使うなら shouldAdvanceTime: true と advanceTimers を渡す |
| 表示が消えたか確かめる | 時間を進めてから queryBy… で確かめる(偽のタイマーのままでは waitForElementToBeRemoved が終わらない) |
| 後片づけを確かめる | vi.getTimerCount() が 0 か |





