テストと確認コマンド
まず変更箇所に近いテストを実行し、API契約やDBを変えた場合は利用側まで確認します。すべてのテストが同じ実行環境で動くわけではありません。
どれを実行するか
すべてリポジトリルートからのコマンドです。
| 変更箇所 | 確認コマンド | 前提 |
|---|---|---|
| 全TypeScriptワークスペース | npm run lint / npm run typecheck / npm run test:lint | npm ci 済み |
| TypeScriptの共有契約 | npm run typecheck | npm ci 済み |
| 画面 | npm run lint / npm run test:web / npm run build | Node.js |
| 公開ページのWorkerとLPの動画配信 | npm run test:worker --workspace @videoq/web | 先に npm run build |
| API | npm run test:api | Node.jsとWorkersのテスト実行環境 |
| DB定義 | npm run db:check / npm run db:verify | 生成したmigration |
| UIの操作と見た目 | npm run test:storybook / npm run build:storybook | Chromium |
| 文書 | npm run build:docs | Node.js |
npm test はAPIとフロントエンドのテストを実行します。PythonとStorybookのテストは別コマンドです。
TypeScriptとESLint
全5ワークスペースの tsc・ビルド・型チェックには最新安定版のネイティブTypeScript(現在7.0.2)を使います。
ESLintなど従来のコンパイラAPIを使うツールには、公式の @typescript/typescript6 互換パッケージを使います。
@typescript/native のnpmエイリアスが tsc を、typescript のエイリアスが互換APIと tsc6 を提供します。
npm run lint はAPI・Web・Docs・demo-video・trpcのソース、スクリプト、テストを確認します。
個別実行は npm run lint --workspace @videoq/api などです。
共通ルールは eslint.shared.mjs にあり、ReactではHooks、WebではFast Refreshとレイアウトのimport制約も確認します。
npm run test:lint は全ワークスペースでネイティブコンパイラとESLintが併用でき、違反を検出できることを確認します。
TypeScriptには recommendedTypeChecked を適用し、Promiseの処理漏れ、同期コールバックへのasync関数の受け渡し、不適切なawaitを検出します。
各ワークスペースの tsconfig.eslint.json はテストと設定ファイルも含め、WebのWorkerには実行環境専用のtsconfigを使います。
本番ビルドの対象範囲を変えずにすべてを検査するため、parserOptions.project でこれらの設定を明示しています。
テスト用モックやStorybookでは不正入力を再現する自由度を残しますが、Promiseの検査は無効にしていません。
併用テストは実際に存在する一時ソースを使い、未処理Promiseと誤ったasyncコールバックを検出し、await・catch済みPromiseを許容することも確認します。
メモリに型情報を蓄積しないよう、ワークスペースごとに別プロセスで実行します。
CIでも各ワークスペースの既存チェックと一緒にLintを実行します。
Dependabotはコンパイラと互換パッケージをまとめて更新し、安定版のメジャー更新も対象にします。
ただし新しい構文を採用する場合はtypescript-eslintの解析対応も必要です。
TS 7で削除された baseUrl は、Docusaurusから継承する値を null で解除し、@site/* をDocs基準の相対パスに設定しています。
APIの単体テストを絞る
npm run test:unit --workspace @videoq/api -- test/rag-agent.test.ts
APIの通常の test は、単体テストの後にWorkers環境のテストも実行します。Workers側だけなら次のコマンドです。
npm run test:workers --workspace @videoq/api
DB統合テスト
一部のテストは実際のPostgreSQLとpgvectorを使います。QUOTA_TEST_DATABASE_URL を指定しない場合にスキップされるテストがあるため、単体テストの成功だけでDBの挙動まで確認できたとは判断しません。
QUOTA_TEST_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:55432/postgres npm run test:api
上記は標準ローカル接続先の例です。検証用DBだけを指定してください。 テストによってDB・スキーマを作成して後片付けするため、接続ユーザーにはテストDBの作成権限も必要です。
画面・Storybook
特定のフックを確認する例です。
npm test --workspace @videoq/web -- src/hooks/__tests__/useTags.test.ts
Storybookの操作テストには、先にChromiumを導入します。
npm exec --workspace @videoq/web -- playwright install chromium
npm run test:storybook
画面遷移や親レイアウトを変更した場合は src/__tests__/App.navigation.test.tsx と Application/Navigation のStoryも確認します。
Python worker
Python 3.12以上で、専用の仮想環境を作ります。次のコマンドだけは apps/worker/ に移動して実行します。
cd apps/worker
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest tests/ -q
DBを使うworkerテストには、テスト用の DATABASE_URL が必要です。個別のテストの前提も確認してください。
実モデルを使うテスト
回答処理を変更したときは、実モデルを呼ぶ前に固定データのテストで確認します。
| 確認する挙動 | 対応するテスト |
|---|---|
| ツールの選択・アクセス範囲・独立した質問 | apps/api/test/rag-agent.test.ts |
| 構造化出力・逐次配信・引用の境界 | apps/api/test/structured-answer.test.ts、apps/api/test/answer-content-stream.test.ts |
| 描画フレーム・非表示タブ・完了・中断 | apps/web/src/lib/__tests__/chatStreamController.test.ts |
通常のCIとは別に、モデルが検索ツールを適切に選ぶかを確認するテストがあります。
RAG_SELECTION_LIVE=1 npm run test:unit --workspace @videoq/api -- test/rag-agent-selection.live.test.ts
これはOpenAI互換APIへ実際に接続し、利用料金が発生します。OPENAI_API_KEY、OPENAI_BASE_URL、LLM_MODEL は環境変数またはAPIの .dev.vars から読みます。初回参加時の必須手順ではありません。
構造化回答の有料比較テストとブラウザー測定は切り替えと検証を参照してください。