TESTING.md

September 12, 2026 · View on GitHub

更新日: 2026-04-25

フレームワーク使い分け

フレームワーク	用途	ファイル数	実行コマンド
`bun:test`	memory-server / SDK / MCP / 契約テスト / ベンチマーク	87	`bun test`
`vitest`	harness-mem-ui コンポーネントテスト + 一部契約テスト	9	`cd harness-mem-ui && npx vitest run`
`@playwright/test`	harness-mem-ui E2E テスト	3	`cd harness-mem-ui && npx playwright test`

使い分けルール

bun:test: デフォルト。memory-server, SDK, MCP サーバー, CLI 契約テスト, ベンチマークすべてに使用
repo root の bun test からは UI tests を file pattern で切り離す。harness-mem-ui/tests/ui は *.vitest.ts(x)、harness-mem-ui/tests/e2e は *.e2e.ts
ただし stable な full run の入口は npm test。UI は引き続き vitest / @playwright/test を正本 runner とする
vitest: harness-mem-ui（React/Vite プロジェクト）のコンポーネントテストに使用。React Testing Library / jsdom 環境が必要なため
@playwright/test: harness-mem-ui の E2E テスト。ブラウザ上の実動作を検証

テストディレクトリ構造

memory-server/tests/

ディレクトリ	カテゴリ	テスト数	説明
`unit/`	ユニットテスト	~21ファイル	個別モジュールの単体テスト（パーサー、アダプタ、ユーティリティ）
`core-split/`	ドメインユニットテスト	5ファイル (87テスト)	分割モジュール（ConfigManager, EventRecorder, ObservationStore, SessionManager, IngestCoordinator）の直接テスト
`integration/`	統合テスト	~22ファイル	HarnessMemCore 経由の E2E 的テスト（API 契約、検索品質、インジェスト）
`benchmark/`	ベンチマーク	1ファイル	LoCoMo recall 計測

tests/ (ルート)

ディレクトリ/パターン	カテゴリ	テスト数	説明
`benchmarks/`	ベンチマーク	~17ファイル	LoCoMo ワークフロー、パフォーマンス 100k、リランク品質ゲート
`*-contract.test.ts`	契約テスト	~14ファイル	CLI/MCP/UI の外部契約（ファイル存在、JSON スキーマ等）

sdk/tests/

ファイル	カテゴリ	説明
`client.test.ts`	ユニットテスト	TS SDK クライアントの fetch モックテスト

vscode-extension/tests/

ファイル	カテゴリ	説明
`client.test.ts`	ユニットテスト	VS Code 拡張のクライアントテスト

harness-mem-ui/tests/

ディレクトリ	フレームワーク	説明
`ui/`	vitest	React コンポーネントテスト（`*.vitest.ts(x)` naming。Bun discovery から分離）
`e2e/`	Playwright	ブラウザ E2E テスト（`*.e2e.ts` naming。Bun discovery から分離）

テスト実行方法

全テスト（bun:test）

npm test

初回のクリーン環境で npm test を回すときは、長期記憶ベンチマークが使うローカル埋め込みモデルを 1 回だけ取得しておくと再現性が安定します。

bash scripts/harness-mem model pull multilingual-e5 --yes
npm test

理由:

tests/benchmarks/memory-durability.test.ts は単純な文字一致ではなく、意味ベースの埋め込み検索を前提にしています
multilingual-e5 が未導入だと fallback embedding に切り替わり、ベンチマークが本来の条件を満たしません
現在はその状態を低い recall ではなく「前提不足」として明示エラーで止めます

npm test は内部で 2 段に分けて実行します。

memory-server/ は cd memory-server && bun run test
- これは tests/*.test.ts を scripts/run-bun-test-safe.sh 経由で、tests/unit, tests/core-split, tests/integration, tests/benchmark, tests/performance を scripts/run-bun-test-batches.sh 経由で小分けに実行する安定 runner です
- 理由: memory-server/tests/unit のような個別スイートでも、テスト自体は全件通っているのに Bun 本体が終了時に panic することがあるためです
- 既知の 0 fail 後だけ起きる Bun panic は safe runner が warning 扱いにし、本当のテスト失敗や途中クラッシュはそのまま fail にします
ルート / SDK / MCP は bash scripts/run-bun-test-batches.sh tests sdk/tests mcp-server/tests
- この runner は *.test.ts / *.test.js だけを拾い、既定では 1ファイルずつ bun test に分けて実行します
- 理由: ./tests/ sdk/tests/ mcp-server/tests/ を 1 本の大きい bun test にすると、こちらも終了時 panic に当たるため
- テスト対象の意図は変えず、実行経路だけを小分けにしています
- 内部では scripts/run-bun-test-safe.sh を通し、0 fail を出したあとにだけ起きる既知の Bun panic は upstream runtime noise として扱います。テスト失敗や途中クラッシュは従来どおり fail です

特定ディレクトリ

# ユニットテストのみ
bun test memory-server/tests/unit/

# core-split テスト（ドメインモジュール単体）
bun test memory-server/tests/core-split/

# 統合テスト
bun test memory-server/tests/integration/

# SDK テスト
bun test sdk/tests/

# 契約テスト
bun test tests/

# root 相当の実行（panic mitigation 版）
(cd memory-server && bun run test) && bash scripts/run-bun-test-batches.sh tests sdk/tests mcp-server/tests

# memory-server 単体の安定 runner
cd memory-server && bun run test

# ベンチマーク（手動実行推奨）
bun test tests/benchmarks/
bun test memory-server/tests/benchmark/

UI テスト

# コンポーネントテスト
cd harness-mem-ui && npx vitest run

# E2E テスト（サーバー起動が必要）
cd harness-mem-ui && npx playwright test

特定ファイル

bun test memory-server/tests/unit/postgres-adapter.test.ts

テストファイル一覧

memory-server/tests/unit/ (bun:test)

ファイル	テスト対象
`core.test.ts`	HarnessMemCore 基本動作
`postgres-adapter.test.ts`	PostgresStorageAdapter SQL 変換 + async API
`storage-adapter.test.ts`	StorageAdapter ファクトリ
`embedding-provider.test.ts`	埋め込みプロバイダー
`reranker.test.ts`	リランカー
`retrieval-router.test.ts`	検索ルーター
`answer-compiler.test.ts`	回答コンパイラー
`token-budget.test.ts`	トークン予算
`signal-extraction.test.ts`	シグナル抽出
`shadow-sync.test.ts`	シャドウ同期
`workspace-boundary.test.ts`	ワークスペース境界
`mem-links-relation.test.ts`	リンク関係
`derives-links.test.ts`	derives リンク推論
`audn-consolidation.test.ts`	統合処理
`background-maintenance-worker.test.ts`	consolidation / WAL checkpoint の子プロセス隔離、FIFO/coalesce、timeout、停止・回収、search audit idle/min/max-age待機・search完了後batch dispatch、実HTTP search phase・retrieval内訳帰属
`search-side-effect-spool.test.ts`	search audit/access-count intent の0600耐久spool、bounded backpressure、true batch 3-transaction apply、crash replay冪等性、shutdown drain
`external-connectors.test.ts`	外部コネクタ
`knowledge-connector.test.ts`	ナレッジコネクタ
`codex-sessions-ingest.test.ts`	Codex セッションパーサー
`opencode-db-ingest.test.ts`	OpenCode DB パーサー
`opencode-storage-ingest.test.ts`	OpenCode ストレージパーサー
`cursor-hooks-ingest.test.ts`	Cursor フックパーサー
`antigravity-files-ingest.test.ts`	Antigravity ファイルパーサー
`antigravity-logs-ingest.test.ts`	Antigravity ログパーサー

memory-server/tests/core-split/ (bun:test)

ファイル	テスト数	テスト対象
`config-manager.test.ts`	24	ConfigManager（委譲 + SQL 直接実行）
`event-recorder.test.ts`	11	EventRecorder（ストリームバッファ、書き込みキュー）
`observation-store.test.ts`	17	ObservationStore（検索、フィード、タイムライン）
`session-manager.test.ts`	19	SessionManager（セッション管理、チェックポイント、ファイナライズ）
`ingest-coordinator.test.ts`	16	IngestCoordinator（委譲パターン検証）

memory-server/tests/integration/ (bun:test)

ファイル	テスト対象
`api-contract.test.ts`	HTTP API 契約
`admin.test.ts`	管理 API
`consolidation.test.ts`	統合処理 E2E
`consolidation-admin-api.test.ts`	統合管理 API
`embedding-provider.test.ts`	埋め込みプロバイダー統合
`environment-api.test.ts`	環境 API
`feed-stream.test.ts`	フィード・ストリーム
`import-claude-mem.test.ts`	claude-mem インポート
`managed-mode-wiring.test.ts`	マネージドモード
`postgres-adapter-integration.test.ts`	PostgreSQL アダプタ統合
`resume-pack-behavior.test.ts`	resume-pack 動作
`resume-pack-cache-sections.test.ts`	resume-pack キャッシュ
`search-quality.test.ts`	検索品質
`search-rerank.test.ts`	検索リランキング
`security-hardening.test.ts`	セキュリティ硬化
`shadow-sync-measurement.test.ts`	シャドウ同期計測
`token-estimate-meta.test.ts`	トークン見積もりメタ
`ingest-codex-sessions.test.ts`	Codex セッションインジェスト
`ingest-cursor-hooks.test.ts`	Cursor フックインジェスト
`ingest-opencode-db.test.ts`	OpenCode DB インジェスト
`ingest-opencode-storage.test.ts`	OpenCode ストレージインジェスト
`ingest-antigravity-files.test.ts`	Antigravity ファイルインジェスト
`ingest-antigravity-logs.test.ts`	Antigravity ログインジェスト

CI での実行方針

ステージ	対象	トリガー
unit	`memory-server/tests/unit/` + `core-split/` + `sdk/`	全 PR
contract	`tests/*-contract.test.ts`	全 PR
integration	`memory-server/tests/integration/`	全 PR
ui	`harness-mem-ui/tests/`	UI 変更 PR
benchmark	`tests/benchmarks/` + `memory-server/tests/benchmark/`	スケジュール or 手動

File reference isolation regression

bun test memory-server/tests/unit/project-registry.test.ts memory-server/tests/unit/project-path-resolver.test.ts memory-server/tests/unit/reference-process-ledger.test.ts memory-server/tests/unit/project-reference-core.test.ts memory-server/tests/unit/project-selection-roundtrip.test.ts
bun test memory-server/tests/core-split/source-reader-isolation.test.ts memory-server/tests/integration/file-reference-isolation.test.ts memory-server/tests/integration/health-source-reference.test.ts memory-server/tests/integration/source-reader-lost-ack.test.ts

The tests preserve original project IDs, inject permanent source and resolver stalls, verify HTTP record/search after cold restart, bound 1,000 requests, retain unconfirmed process reservations, and test save-ACK replay. The FIFO test is POSIX-specific. The normal six-source ingest integration suites and UI selection/SSE suites remain required regression checks after changes to these paths.