Vitest 実行ガイド

目的

フロントエンド（TypeScript / JavaScript）のユニットテストを Vitest で実行する方法を説明します。

配置規約

• テストはソースの隣にコロケートする（*.test.ts / *.test.tsx / *.test.js）
• 対象パスは vitest.config.ts の include に従う:
  • core_src/**/*.test.{ts,tsx,js}
  • tests/**/*.test.{ts,tsx,js}
• __tests__/ ディレクトリは使わない（既存規約に合わせる）
• Playwright の E2E（tests/e2e/*.spec.js）は Vitest の対象外

実行コマンド

用途	コマンド
Vitest のみ	npx vitest run
プロジェクトの test スクリプト	npm test

npm test は次を順に実行します。

1. build:paid-article-admin
2. vitest run
3. test:dbml-subsets（Node 組み込みテスト。Vitest ではない）

開発中の確認は npx vitest run で十分なことが多いです。CI や PR 前の通し確認では npm test を使います。

前提（Vitest 5）

• Node.js 24（Vitest 5 は Node >= 22.12）
• Vite 6.4 以上（Vitest 5 の peer。ルートの devDependencies に vite ^8.x を明示。.npmrc の legacy-peer-deps=true では peer の自動解決に頼れない）
• Vitest 5 では clearMocks の既定が true（各テスト前に mock 呼び出し履歴がクリアされる）。履歴の持ち越しに依存しない書き方にする。旧挙動が必要な場合のみ vitest.config.ts で clearMocks: false を検討する

設定

• 設定ファイル: リポジトリ直下の vitest.config.ts
• 環境: jsdom
• globals: true（describe / it / expect を import なしでも利用可。既存テストは明示 import も可）
• React フックのテストでは @testing-library/react の renderHook を使う
• @wordpress/element を使うフックは、既存パターンどおり vi.mock('@wordpress/element', () => import('react')) で React に差し替える

書かないテスト

• 型の確認だけのテスト（expect(typeof formatSamai).toBe('function') のように、関数やコンポーネントが存在する・特定の型を返すことだけを見るもの）は書かない。型は TypeScript が保証する
• モックの戻り値をそのまま assert するだけのテスト（vi.fn().mockReturnValue(x) を呼んで x が返ることを確かめるだけのもの）は書かない。テスト対象のロジックを通らないため、回帰を防がない

書くテスト・書かないテストの考え方は PHPUnit と同じです。詳しくは PHPUnit テスト実行ガイドの「書かないテスト」と「書くテスト」を参照してください。

CI

CI Quality Gate（.github/workflows/ci-quality-gate.yml）の Run Vitest ステップで npm run test が実行されます。

• 追加 push（synchronize）では自動起動しない（CI 運用方針）

関連

• テスト・品質確認ガイド
• コマンド一覧
• Playwright E2E 実行ガイド