品質保証 2026年11月16日

テストの順番を30通り入れ替えたら、後片付けを忘れた5本がすべて落ちた。retryでは1本も直らず、手元で1回おきに落ちる原因はVitestの前回の結果による並べ方だった

XECIN テスト自動化テスト設計Vitest技術検証

先週、社内サイトの問い合わせフォームまわりのテストを整理していて、妙な赤に当たりました。CI で落ちた「保存前の問い合わせは0件」を手元で流し直すと緑。もう一度流すと赤。その次はまた緑です。

正直なところ、最初は「よくある flaky だろう」と思っていました。ただ、色が1回ごとに入れ替わるのは、偶然にしては規則的すぎるんですよね。

テストは目的ではなく手段です。流す順番しだいで色が変わるテストは、手段として信用できません。そこで、テスト同士が知らないうちに頼り合っている「順序依存」を手元でわざと作り、流し方を変えると何が起きるかを測りました。

後片付けを忘れたテストを5種類書いた

題材は、問い合わせフォームと見積もり画面を想定した小さなテスト一式です。6ファイル・11テストのうち5本が、前に流れた別のテストの「残しもの」で落ちるように書いてあります。残しものは次の5種類です。

  • 税率の値: モジュールの中の設定を8%に書き換えたまま戻さない
  • 環境変数: process.env.MAINTENANCE を書き換えたまま戻さない
  • 偽の時計: vi.useFakeTimers() のあと vi.useRealTimers() を呼ばない
  • DOM: エラーを出すモーダルを document.body に足したまま消さない
  • 保存ファイル: 問い合わせを書いたファイルを消さない(別のファイルのテストが0件を期待する)

最初の2種類は、同じファイルに同居しています。

// tests/quote.test.js
import { it, expect } from 'vitest';
import { withTax, isFormOpen } from '../src/quote.js';
import { setTaxRate } from '../src/settings.js';

it('1,000円は税込1,100円', () => {
  expect(withTax(1000)).toBe(1100);
});

it('通常時はフォームを開いている', () => {
  expect(isFormOpen()).toBe(true);
});

it('軽減税率8%なら1,080円', () => {
  setTaxRate(0.08); // 元に戻していない
  expect(withTax(1000)).toBe(1080);
});

it('メンテナンス中はフォームを閉じる', () => {
  process.env.MAINTENANCE = '1'; // 元に戻していない
  expect(isFormOpen()).toBe(false);
});

どのファイルも、影響を受ける側を先に書きました。書いた順に流れる限り、全部緑です。環境は手元の Windows 11 で、Node 22.14.0、Vitest 5.1.0(11月時点の最新)、DOM のテストだけ jsdom 26.1.0 を使いました。設定は include を書いただけで、ほかは既定値です。

既定の順番では、ほとんど落ちない

何も指定せずに10回流すと、税率・環境変数・時計・DOM の4本は10回とも緑でした。同じファイルの中は書いた順に流れるので、影響を受ける側が先に終わってしまうからです。

落ちたのは保存ファイルの1本だけで、10回中5回。それも1回目・3回目・5回目・7回目・9回目と、きれいに1回おきでした。前の回の保存ファイルを消さずに流し直すと、3回とも赤です。

Vitest が手元に残す前回の結果(あとで出てきます)を毎回消して流すと、10回中8回が赤でした。node_modules を毎回作り直す CI に近い条件です。この条件ではたいてい赤、前回の結果を残したまま手元で流し直すと半分は緑。冒頭の「CI だけ落ちる flaky」は、この形でした。

最初は retry を足した。1本も緑にならなかった

今思えば、ここで遠回りをしています。flaky だと決めつけて、まず --retry=2 を付けました。

5本がそろって落ちる並び(後で出てくる seed 3)に retry を足すと、5本とも赤のままでした。前のテストが残した税率もモーダルも、retry の合間にだれも片付けないので、何度やり直しても同じものを見ます。時計の1本はタイムアウトの5秒を3回待って15.0秒かかり、全体も5.5秒から15.6秒に延びました。

反対に、同じ並びのまま影響を受ける側だけを -t で選んで流すと、5本とも緑でした。単独で緑になったからといって、そのテストが一式の中で正しく動くとは言えません。「動いた=品質OK ではない」の典型です。

並べ替えを30通り流した

Vitest には、ファイルとテストの順番を入れ替える --sequence.shuffle があります。乱数の種(seed)は --sequence.seed で固定できるので、seed を1から30まで変えて流しました。

for seed in $(seq 1 30); do
  rm -rf data   # 前の回の保存ファイルを消す
  npx vitest run --sequence.shuffle --sequence.seed=$seed > /dev/null 2>&1 \
    || echo "seed=$seed で失敗"
done
# 実行結果(抜粋。30回中23回が失敗):
# seed=2 で失敗
# seed=3 で失敗
# seed=7 で失敗
# ...
# seed=30 で失敗

落ちた回数を、残しものの種類ごとに並べるとこうなります。数字は落ちた回数で、単独と retry は seed 3 の並びで測りました。

残しもの単独既定10回並べ替え30回retry 2回
税率の値緑0回15回赤
環境変数緑0回12回赤
偽の時計緑0回12回赤
DOM緑0回12回赤
保存ファイル緑5回10回赤

30回のうち24回はどれかが落ちましたが、5本がそろって落ちたのは3回(seed 3・14・24)だけです。6回は全部緑でした。並べ替えを1回足しただけでは、順序依存の大半を見逃すことがあります。

では何回続けて流せば足りるのか。seed 1〜30 から続けて流す区間を取り出し、その区間の中で5本とも一度は落ちたかを数えました。

続けて流す回数5本とも落とせた区間
1回30区間中3(10.0%)
2回29区間中9(31.0%)
3回28区間中19(67.9%)
4回27区間中22(81.5%)
5回26区間中24(92.3%)
6回25区間中25(100%)

6回続けて流せば、どこから始めても5本とも一度は落ちました。もちろん、これはこの11テストでの数字です。テストが増えれば、必要な回数も変わるはずです。

もう1つ、時計とモーダルの2本は、30回とも同じ回に落ちていました。どちらもテストが2本だけのファイルです。seed が同じだと、本数の同じファイルは同じ並びになるように見えますが、理由までは確かめていません。

時計の1本が落ちた12回は、1回あたり約5.5秒(中央値5,521ミリ秒)かかりました。ほかの回は約1.0秒です。30回の合計は84.6秒でした。

ただ、seed で固定できるのは順番までです。上のループは30回中23回が失敗で、表を作ったとき(同じ seed 1〜30 を別の回に流したもの)より1回少ない結果でした。違ったのは seed 1 だけで、表の回では保存ファイルの1本が落ち、ループでは緑でした。順番は seed で固定されても、並行に流れるファイル同士のタイミングまでは固定されないためだと考えています。

1回おきに落ちた理由は、前回の結果で決まる順番だった

保存ファイルの1本が1回おきに落ちた理由は、Vitest のファイルの並べ方にありました。答えは CLI のヘルプにそのまま書いてあります。--cache(既定で有効)は「テストの結果を保存して、落ちたファイルと時間のかかるファイルを先に流す」ためのものです。5.1.0 の並べ方の実装を読むと、プロジェクトの区別などを除けば、順番は次のように決まっていました。

  1. 前回の結果が無いファイルが混ざっていれば、ファイルの大きい順
  2. そうでなければ、前回落ちたファイルが先
  3. 残りは、前回の所要時間が長い順

前回の結果は node_modules/.vite/vitest/ の下(ハッシュ値のフォルダ)の results.json に残ります。保存ファイルの1本が落ちた直後は、こうなっていました(抜粋して整形し、小数は丸めました)。

{
  "tests/campaign.test.js": { "failed": false, "duration": 317.8 },
  "tests/hours.test.js": { "failed": false, "duration": 84.4 },
  "tests/store-empty.test.js": {
    "failed": true,
    "duration": 5.1,
    "failedTests": ["保存前の問い合わせは0件"]
  },
  "tests/store-save.test.js": { "failed": false, "duration": 3.2 }
}

落ちたファイルは次の回で先に流れるので、保存より先に数えて緑になります。緑になると所要時間の順に戻って保存の後ろに回り、また赤。これを繰り返していました。前回の結果を消した条件では、ファイルの大きい順になります。いちばん小さい store-empty.test.js(159バイト)は後ろに回るので、10回中8回の赤はこのためだと考えています(ファイルは並行に流れるので、毎回そうなるとは限りません)。

同じことは、ディスクを介さなくても起きます。ファイルごとにモジュールを読み直す仕組み(isolate)を切り、ファイルを1つずつ順に流す設定で、税率を書き換える2つのファイルだけを流しました。isolate: false は速くなるので、設定している現場もあると思います。

前回の結果を消してから6回流すと、緑・赤・緑・赤・緑・赤でした。1回目は前回の結果が無いので、大きい quote.test.js(616バイト)が先に流れて緑。2回目は所要時間の長い campaign.test.js(300ミリ秒待つテストがある)が先に流れ、そこで書き換えた税率0%のまま「1,000円は税込1,100円」を計算して赤。3回目は前回落ちた quote.test.js が先に戻って緑です。

ここは好みが分かれるところですが、私は --cache を切る方向には進みませんでした。並べ方が変わるのは速さのための仕様で、順番が変わっても通るテストに直すほうが筋が良いと考えたからです。

直したのはテストの後片付け

直し方そのものは地味です。共通の後片付けを setup ファイルに集め、環境変数は vi.stubEnv に替えて、設定の unstubEnvs: true で毎回戻します。保存先は、呼ぶたびに process.env.STORE_DIR から決めるように1か所変えて、テストごとに別の一時フォルダを渡しました。

// tests-fixed/setup.js
import { afterEach, beforeEach, vi } from 'vitest';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { resetSettings } from '../src-fixed/settings.js';

beforeEach(() => {
  vi.stubEnv('STORE_DIR', fs.mkdtempSync(path.join(os.tmpdir(), 'inquiry-')));
});

afterEach(() => {
  resetSettings();
  vi.useRealTimers();
  if (typeof document !== 'undefined') document.body.replaceChildren();
});

// vitest.fixed.mjs(直した版の設定)
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    include: ['tests-fixed/**/*.test.js'],
    setupFiles: ['tests-fixed/setup.js'],
    unstubEnvs: true,
  },
});

直した版を同じ条件で流すと、既定の順番13回(保存ファイルを残した3回を含む)、並べ替え30回、isolate を切った6回が、すべて緑でした。並べ替え30回の合計は84.6秒から31.0秒に縮んでいます。ほぼ、時計の5秒待ち12回分です。

正直に書くと、この setup にはまだ改善の余地があります。後片付けの中でアプリ側の resetSettings を直接呼んでいるので、設定を持つモジュールが増えるたびに書き足す必要があります。DOM は body の中身しか消していないので、head に足した要素やイベントリスナーは残ります。そして一時フォルダは作るだけで消していません。この実験だけで、OS の一時フォルダに514個残っていました。

受け入れ基準にした3つ

順序依存は、レビューで読んで見つけるのが難しい種類の不具合です。そこで、テストの一式そのものに受け入れ基準を置くことにしました。

  • 影響を受けそうなテストを -t で単独で流しても、一式で流しても、同じ結果になる
  • seed を変えた並べ替えを6回続けて流し、すべて緑になる(6回は、今回の11テストで5本とも落とせた回数)
  • 前回の結果を消した回と残した回で、結果が変わらない

落ちたときは、seed をそのまま記録して、同じ seed で再現してから直します。retry で緑にするのは、原因が順番ではないと分かってからです。

おわりに

今回の5種類のうち、保存ファイルだけは isolate を有効にしていても防げませんでした。プロセスの外にある状態は、Vitest の仕組みでは分けられないからです。次は、データベースを使うテストで同じ並べ替えを試して、何回続けて流せば足りるのかを測り直したいと思っています。

それと、CI に並べ替えを1回足すだけで安心しないこと。夜間に seed を変えて6回流し、落ちた seed をチケットに貼る仕組みを作るところまでやるつもりです。