Reactのタイマー処理をVitestで待たずにテストする方法

​​React​React Testing Library,TypeScript,user-event,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秒たったら消すコンポーネントです。

tsx
// 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 で進めます。

tsx
// 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 で包んでいます。包まずに呼ぶと、通知が残ったままになり、テストは失敗しました。

text
 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 オプションの説明どおりに、時間を進める関数を渡しても同じでした。

tsx
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();
});
text
 FAIL  src/pitfall-userevent.test.tsx > advanceTimers を渡して userEvent でクリックする
Error: Test timed out in 3000ms.

クリックそのものは済んでいました。user.click() の Promise を待たずに調べると、onSave は1回呼ばれていたのに、Promise は終わっていませんでした。そこで偽の時計を 0ms 進めると、Promise が終わりました。

text
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 は省きます。

tsx
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秒のタイムアウトで落ちました。

tsx
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になったら後片づけで止めます。

tsx
// 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 は省きます。

tsx
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万回で打ち切られて失敗しました。

tsx
act(() => {
  vi.runAllTimers();
});
text
 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になりました。

text
act の中で1秒進めた: 再送信(あと30秒) / 待っているタイマー: 1
act の中でさらに30秒進めた: 再送信(あと30秒) / 待っているタイマー: 1
act を抜けたあと: コードを再送信 / 待っているタイマー: 0

act の中では、setLeft で変えた state が、act を抜けるまで画面に反映されません。再描画がないのでエフェクトの後片づけも動かず、clearInterval が呼ばれません。そのため、runAllTimers から見ると、インターバルがいつまでも残ります。

act の中ではインターバルが何度動いても画面は「あと30秒」のままで clearInterval が呼ばれない。runAllTimers は1万回で打ち切られ、advanceTimersByTime は決めた時間だけ動かして act を抜け、そこで clearInterval が動く
act の中で runAllTimers と advanceTimersByTime を使ったときの違い
ポイント

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 か

​Posted by 86