テスト設計書

概要

MorningStatusApp のテストは Vitest で実行する。 テストコマンド: bun run test

画面の見た目の回帰確認は、Vitest とは別系統で Playwright の toHaveScreenshot() を使うビジュアル回帰テストで行う（ビジュアル回帰テスト）。 テストコマンド: bun run test:visual

テスト分類

テストファイル一覧

ライブラリ（lib/）

コンポーネント（components/）

ページ（app/）

API Route（app/api/）

スクリプト（scripts/）

テスト実装指針

モックパターン

fetch モックには必ず ok: true を含めること（省略すると正常系が全失敗する）。

exa-js のようなクラスコンストラクタのモックは function キーワードを使うこと （アロー関数では「is not a constructor」エラーになる）。

クリーンアップ

afterEach(() => {
  vi.unstubAllGlobals();
  vi.unstubAllEnvs();
  vi.useRealTimers();   // useFakeTimers を使った場合
  // vi.restoreAllMocks() はタイマーを戻さないため useRealTimers が別途必要
});

Server Component のテスト

Server Component（async function Page()）は render() を使わず直接 await して結果を検証する。

const result = await Home();
const html = JSON.stringify(result);
expect(html).toContain('"isRecentlyUpdated":true');

next/link の Link は JSON.stringify で循環参照エラーになるため vi.mock('next/link', ...) で差し替えること。

曜日依存ロジックのテスト

曜日によって結果が変わるロジック（shouldSyncOG() 等）は Date を固定してテストする。

vi.useFakeTimers({ toFake: ['Date'] });
vi.setSystemTime(new Date('2026-01-05T11:30:00Z')); // 月曜日

再試行ロジックのテスト

setTimeout を含む再試行ループは vi.useFakeTimers() 全面適用 + vi.runAllTimersAsync() で完走させる。

ビジュアル回帰テスト

見た目が変わらないはずの変更（Panda CSS のメジャー更新など、依存パッケージの更新）の前後で画面のスクリーンショットを比較し、型チェックやユニットテストでは検出できない見た目の回帰がないことを確認する。合格条件は、比較した全画面で差分が出ないことである。

用途

配置とファイル構成

• 画面ごとのファイルを、対象画面のディレクトリに page.visual.ts として置く（例: app/timeline/page.visual.ts）。ユニットテスト（page.test.tsx）と同じ置き方である。
• 各ファイルには、画面への遷移、操作（モード切替・データ選択等）、撮影する状態を定義する。
• 撮影の共通処理（画面の表示待ち・スクロール・画像の読み込み待ち・スクリーンショットの比較）は、test/visual/helpers.ts の expectScreenshot() にまとめ、各ファイルから呼ぶ。
• 拡張子 .visual.ts は Vitest の対象（*.test.* / *.spec.*）と重ならないため、bun run test には含まれない。
• 共通設定は、リポジトリ直下の playwright.config.ts に集約する。

共通設定

画面ごとの *.visual.ts は、ロード中表示（loading.tsx のフォールバック）が消えたことを待ってから撮影する。

基準画像と比較結果

• 保存先の .visual-regression/ は、.claude/tmp/（Issue の登録・編集、レビュー、動作確認用スクリプトなどの作業用一時ファイル）とは別のディレクトリとし、Git 管理外とする。
• Git 管理しない理由: 表示データ（Vercel Blob・Neon）は随時更新されるため、コミットした基準画像は CSS を変えなくても古くなり、偽の差分を出す。フォントの描画も OS・端末で変わるため、他の端末で撮った基準画像とは一致しない。基準画像は比較のたびに同じ端末で作り直す一時的な成果物であり、保管しない。
• PR に添付する動作確認のスクリーンショットは、従来どおり screenshots/<PR番号>/ に格納する。基準画像とは別物である。

運用手順

1. 変更前（main）で、基準画像を作成する: bun run test:visual --update-snapshots
2. 作業ブランチに切り替えて変更を適用する（依存パッケージの更新など）。
3. 同じ端末で、時間を空けずに比較する: bun run test:visual。差分のあった画面だけが失敗し、差分画像が出力される。
4. 差が出たら、node test/visual/crop-diff.mjs で差のある箇所を切り出し、差の場所が日付に依存する表示などに限られるかを確認する（差のある箇所の切り出し）。

表示データの更新が手順1と3の間に入ると、CSS と無関係な差分が出る。日付・最新データなど毎回変わる領域は、toHaveScreenshot() の mask でマスクする。

差のある箇所の切り出し

比較で差が出たとき、差のある箇所を、基準画像と今回の画像から同じ範囲で切り出して並べて確認する。Playwright が出す差分画像（*-diff.png）は、一致する部分を薄く描くため白っぽく、実際の配色の違いを確認する証拠には向かない。切り出した画像は、PR に添付する確認用の画像として使える。

node test/visual/crop-diff.mjs [--out <出力先>] [--top <領域の数>] [--margin <余白>]

• 入力: .visual-regression/results/ を走査し、同じディレクトリに *-expected.png（基準画像）と *-actual.png（今回の画像）が揃った組をすべて対象にする。画面の一覧はスクリプトに持たない。
• 差の判定: 画素の RGB のいずれかが、基準画像と今回の画像で 8 より大きく違えば、差ありとする。差のある画素を 16px 単位のブロックにまとめ、隣り合うブロック（斜めを含む）を 1 つの領域にする。領域は差のある画素の多い順に並べ、上位 --top 件を切り出す。
• 切り出す範囲: 領域の範囲に --margin を足す。小さすぎて見づらくならないよう、幅 320px・高さ 160px を最小とし、画像の内側に収める。画像の端に近く、最小のサイズを確保すると画像の外に出る場合は、画像の内側に収めることを優先する。このとき、切り出し範囲は最小のサイズを下回ることがある。
• 出力: 領域ごとに、同じ範囲を <ディレクトリ名>-<ベース名>-<通し番号>-expected.png と -actual.png で出力する。通し番号は 0 から始まり、差の大きい順である。ディレクトリ名のうち、ファイル名に使えない文字（\ / : * ? " < > |）は _ に置き換える。
• 比較できない組: 基準画像と今回の画像の大きさが違う組は切り出さず、その旨を出力して次の組へ進む。
• 対象の組がない場合: 対象の組が 1 つもなければ、その旨を出力して終了コード 0 で終了する。.visual-regression/results/ 自体がなければ、先に bun run test:visual を実行するよう案内して、終了コード 1 で終了する。
• 差のない組: 基準画像と今回の画像の大きさが同じで、差のあるピクセルがない組は、画像を出力しない。
• 引数が不正な場合: 値のない引数、数値でない --top・--margin、不明な引数は、メッセージを出して終了コード 1 で終了する。
• 画像の処理には sharp を使う。devDependencies に直接宣言する。実行は node で行う。
• 切り出しスクリプト（crop-diff.mjs）のテストは test/visual/crop-diff.test.ts に置き、Vitest で実行する。scripts/ 配下のバッチスクリプトのテスト（スクリプトテスト）とは別物で、ビジュアル回帰テスト（*.visual.ts）とも異なり、拡張子が .test.ts のため bun run test に含まれる。

対象画面

初期は、Panda CSS 2.x への更新（#1672）の回帰確認に必要な、メンバー一覧・タイムライン・メンバー関係性マップ（関係性レーダーチャートを含む）とする。他の画面は、その画面に触れるときに追加する。

メンバー詳細は、モバイルで投稿を表示する領域が極端に縦長になり（#1741）、ページ全体のスクリーンショットを撮れないため、#1741 の対応後に追加する。

テスト実行

bun run test            # 全テスト実行
bun run test --watch    # ウォッチモード
bun run test path/to/file.test.ts  # 特定ファイルのみ
bun run test:visual                        # ビジュアル回帰テスト（基準画像との比較）
bun run test:visual --update-snapshots     # ビジュアル回帰テストの基準画像を作成・更新
node test/visual/crop-diff.mjs             # ビジュアル回帰の差のある箇所を切り出す（差が出たあとに実行）

CI では bun run lint（0 warnings）・bun run type-check も合わせて通過させること。

改訂履歴（バージョン降順に記載）