テスト層
| 層 | コマンド | 備考 |
|---|---|---|
| API unit | cd apps/api && ADMIN_API_KEY=dummy PUBLIC_API_KEY=dummy OPENAI_API_KEY=dummy pytest tests/(rye の venv なら rye run pytest tests/)。先に下の「API テストの前提」を済ませる | 前提をそろえれば CI の server-pytest.yml と同じ条件 |
| analysis-core unit | cd packages/analysis-core && pytest tests/(hatchling パッケージで rye 管理外。CI は pip install -e ".[dev,clustering]" 相当の環境で素の pytest。UMAP 系テストは [clustering] extra が必要) | tests/test_pipeline_paths_integration.py でパイプライン統合 |
| analysis-core E2E (実 LLM) | cd packages/analysis-core && OPENAI_API_KEY=… pytest tests/e2e/ -v(unit と同じ環境で素の pytest) | 約 $0.01/run(gpt-4o-mini)。pyproject.toml の norecursedirs で既定除外、CI 非実行。キーが無いと全件 skip で終わる(成功したわけではない) |
| API → subprocess → analysis-core 手元 smoke | cd apps/api && ADMIN_API_KEY=dummy PUBLIC_API_KEY=dummy OPENAI_API_KEY=dummy rye run pytest tests/manual/report_launcher_subprocess_smoke.py -q -s | tests/manual/report_launcher_subprocess_smoke.py。execute_aggregation() の再集約 smoke に加えて、launch_report_generation() から 通常フロー全体 を本物の subprocess で起動し、hierarchical_result.json / hierarchical_status.json / report_status.json 更新まで確認する。full flow 側は local provider と OpenAI 互換の偽 LLM で extraction / embedding / clustering / overview まで踏む。既定収集の対象外で、明示実行専用。前提は下の「API テストの前提」の 3。source-codeより |
| Frontend unit (Jest) | apps/public-viewer/ と apps/admin/ で pnpm test | |
| Browser E2E (Playwright) | cd test/e2e && pnpm test(UI: pnpm run test:ui) | 設定詳細は test/e2e/CLAUDE.md |
API テストの前提
- analysis-core を API の環境に入れる: API のテストの一部(
tests/services/test_llm.py/test_parse_json_list.py)はファイル先頭でanalysis_coreを import する。analysis-core は API の依存に入っていないので、入れないとテストの収集の段階で止まる。CI と同じにするならcd apps/api && pip install -r requirements-dev.lock && pip install -e ../../packages/analysis-core(extras は不要)。rye の venv なら、rye syncのあとにrye run python -m ensurepip --upgrade && rye run python -m pip install -e ../../packages/analysis-core(rye の venv には pip が無い) - 必須キーを渡す:
tests/conftest.pyがsrc.configを読み込むので、ADMIN_API_KEY/PUBLIC_API_KEY/OPENAI_API_KEYが環境変数かapps/api/.envに無いと conftest の読み込みで落ちる。CI はダミー値を export している(上の表のコマンドと同じ)。同梱のapps/api/.env.testをENV_FILE=.env.test pytest tests/で読ませてもよい。リポジトリ直下の.envはapps/apiからは読まれない(local-dev-setup) - 手元 smoke はさらに 2 つ: (a) 子プロセスは PR #995(2026-10-13)以降
sys.executable、つまり pytest を動かしている API 側のインタプリタで起動されるので、そのインタプリタに analysis-core を[clustering]付きで入れる。(b) テストは最初にpackages/analysis-core/.venv/bin/pythonでpython -m analysis_core --versionが通るかを確かめ、通らないと 2 件とも skip して exit 0 で終わる(何も検証されない)。テスト冒頭の docstring にある「子プロセスは.venvの python を使う」は、この変更より前の挙動の説明 make test/apiは別の条件: API コンテナの中でpytest tests/を回す(docker compose run --rm api pytest tests/)。イメージに焼き込んだ analysis-core(ビルド時点のコピー)を使うので、analysis-core を変えたらdocker compose build apiが要る。pytest はENVIRONMENT=developmentでビルドしたイメージにしか入らない。この経路は CI では回していないので、CI と同じ条件で確かめるときは 1・2 のネイティブ手順を使う
Lint / format
- Python:
ruff—rye run ruff check .、またはmake lint/api-check/make lint/api-format - TS/JS: Biome(ESLint + Prettier の代替)— 各 app で
pnpm run lint/pnpm run format - lefthook が
pre-pushでruff check+ruff format --checkを実行。Biome はskip: trueで gating されていない - CI では
client-build.yml(public-viewer / utils/dummy-server)とclient-admin-build.yml(admin)がbiome ciを実行し、全体 lint が PR の gate になっている(PR #963 で 0 件化と同時に導入)。それ以前は 2026-02 以降 main の全体 lint が落ちたままだった。lint gate は 0 件化と同じ PR で入れないと戻る(biome-lint-main-drift-2026-10-09 の教訓)
CI ワークフロー
.github/workflows/ 配下は 2026-10-18 時点で 22 本(2026-11-07 追記: 23 本。10-26 に #1132 で infra-checks.yml が増えた。Docker のビルドコンテキストの除外設定と、コメントコマンドの権限条件をスクリプトで検査する)。テスト・lint 系の主なもの:
- Python:
server-pytest.yml(apps/api)、analysis-core-ci.yml(analysis-core の pytest + coverage)、ruff-check.yml、api-docker-dependency-smoke.yml - フロント:
client-jest.yml/client-admin-jest.yml(Jest。2026-11-07 追記:client-jest.yml(name: Client Tests)は Jest の後に Playwright の Chromium を入れ、playwright.viewer-states.config.tsで API なしの viewer states も確かめる。そのため Playwright のインストール失敗でも落ちる)、client-build.yml/client-admin-build.yml(build +biome ci) - E2E:
e2e-tests.yml(Playwright)、windows-setup-script.yml/windows-real-machine-e2e.yml、setup-scripts-env.yml(setup スクリプトと.env.exampleの整合) - その他:
codeql.yml、docs.yml、publish-analysis-core.yml、azure-deploy.yml、Issue/assign 系 bot
本体の docs/testing.md は 2026-10-18 時点でも workflow 5 本・rye run pytest 前提の記述のままで、実態とずれている(docs PR 候補)。static-site-builder には build / 型検査の CI が無い。
Playwright + Next.js のコツ
skills/kouchou-ai-testing/SKILL.md より:
page.goto後は必ずawait page.waitForLoadState("networkidle")- Server Components は実 HTTP を投げるので dummy server を立てる
- ハンドメイドの dummy より、本番形のフィクスチャを使うべし
既知の歴史的事故
- meeting-minutes 2025-10: import-order を ruff の lint がエラーにし続け、無関係 PR が全部ブロックされた → PR #708 で import-order チェックを無効化してすべての既存違反を一括修正
- meeting-minutes 2025-09 / PR #553: テストデータ汚染インシデント
- Devin がリント自動修正できないものを無限ループした事例も同時期(→ coding-agents)
現在の運用判断
analysis-coreのhierarchical_clusteringは、PR #829(2026-05-19 merge)以降、UMAP / KMeans に seed を渡さない。そのため、seed を固定していた頃にテストで出ていたumap-learnのUserWarning(random_state固定で並列性が制限される旨。2026-05-17 時点では既知として許容していた)は、今の main では出ない。代わりに、同じ入力でも再実行するとクラスタ番号・境界・散布図の座標が変わる。gotchas / seed-reproducibility-history / umap-seed-historyより
v5 移行期のテスト責務
2026-05-18 時点の計画では、9 月までに v4 の既存機能が壊れていないことをテストで保証しつつ、発展性の高い v5 へ移行する ことが重視されている。book-release-development-plan-2026-09より
したがって移行期のテストは、単に main が green かを見るだけでなく:
- v4 で守るべきユースケースを固定する
- v5 default path でもそのユースケースが壊れていないか確認する
- unit だけでなく integration / E2E を回帰検知帯として扱う
という責務を持つ。
Updates
- 2026-11-08: Playwright の件のその後。#1185(Playwright 1.64.1)が 11-07 に merge(main
0fb5a408)され、11-07 の merge 以降の main の Client Tests は 26.04 で green。#1184(24.04 固定)は conflict して不要になり、11-08 に close - 2026-11-07: GitHub の Actions と照合。workflow は 23 本(10-18 時点は 22 本)。
ubuntu-latestが Ubuntu 26.04 に移り、Playwright 1.57.0 が Chromium を入れられないため、main の E2E Tests の定時実行は 10-31 から、Client Tests(viewer states)は 11-07 の push から落ちている。手当ては shingo-ohki の PR #1184(ランナーを 24.04 に固定)と #1185(Playwright 1.64.1 に更新)で、11-07 時点で未 merge。Open Questions の「E2E は CI 非実行」に、今は CI で回っていることを書き足した - 2026-11-07(査読を受けて): 「CI ワークフロー」節の本数に 23 本目の
infra-checks.ymlを、client-jest.ymlが Jest だけでなく viewer states の Playwright も回すことを書き足した(上の「Client Tests(viewer states)が落ちている」の理由) - 2026-10-21: main
b71e0b79と照合し、API unit・analysis-core E2E・手元 smoke の実行前提(analysis-core の導入、必須キー、sys.executableで起動するようになった後の smoke の skip 条件)を訂正。make test/apiは CI と同じ条件ではないことを明記し、既定の代替として並べるのをやめた。あわせて、UMAP の warning を許容するという「現在の運用判断」を、PR #829 で seed を外した後の現状(warning は出ず、再実行で結果が揺れる)に訂正 - 2026-10-18: main
083593baと照合。Biome CI 導入済み(#963)、workflow 22 本、analysis-core は rye ではなく素の pytest、に訂正 - 2026-10-09: Biome が hook / CI のどこでも強制されておらず main の全体 lint が落ちている事実と、その由来を biome-lint-main-drift-2026-10-09 に記録
- 2026-05-17: UMAP の
random_state由来 warning は既知で、現時点では許容する判断を追記 - 2026-05-17: 初回作成
- 2026-05-18: v5 移行期における「v4 回帰保証」のテスト責務を追記
- 2026-05-23: API の
report_launcherがanalysis_coreを subprocess で起動する継ぎ目を、mock ではなく実 subprocess で踏む手元 smoke test (tests/manual/report_launcher_subprocess_smoke.py) を追加 - 2026-05-23:
launch_report_generation()から通常フロー全体を踏む manual smoke を追加し、その実行で workflow plugin が--input-dir/--output-dirを legacy step に渡していなかったバグを発見・修正
Updates — 2026-10-05 検証結果の保証範囲を分ける
9月9日の#943・#945・#946の記録をもとに、テスト結果の読み方を整理した。今回のコード再検証ではない。three-issues-progress-2026-09-09 / next-three-issues-progress-2026-09-09より。
- Server ActionからAPIへの通信はブラウザのpage.routeでは捕捉できないため、HTTP dummyで失敗応答・切断を作る。画面側の復帰動作の確認と、実プロバイダーの認証・接続確認は区別する。
- fixtureによるブラウザ試験は操作と値の受け渡し、実routerと一時ファイルの統合試験は保存・再取得を担う。設定画面では他項目の保持、不正値の拒否、取得失敗時に既定値で上書きしないことも確認する。
- Jest成功だけでは型検査成功を保証しない。#946ではChakra Textのlabel属性がビルド時に失敗し、asChildとnative labelで修正した。CI成功・自動レビュー完了・実サービス接続成功・ブラウザエラー不存在も、それぞれ別の確認結果として報告する。
上のOpen Questionsにある「E2EはCI非実行」は、ブラウザE2E全般の現在の説明としては使わない。9月9日の#943では全体86件、#946では81件のブラウザE2EがCIで成功している。実LLMを使うanalysis-core E2Eとは対象を区別する。
- 2026-11-07: Open Questions から除去 — 「E2E は CI 非実行のため、回帰検知はローカル運用次第。ステージング環境ベースの代替戦略の合意は未確認」。E2EはPRとscheduleでCI実行するworkflowがある。「CI非実行」という前提は解消。ステージングでの代替保証は主張しない。(根拠: kouchou-ai upstream/main@085366779(2026-10-29) .github/workflows/e2e-tests.yml:4)。
- 2026-11-07: Open Questions から除去 — 「Biome の CI ゲーティングは PR #963 で導入済み(2026-10-09 時点の「無い」は解消)」。#963で導入済みと問い自体に回答が残っている。(根拠: 0f2ebe6:wiki/concepts/testing.md:88(既存 Updates);kouchou-ai 2b0079a1d)。