@aiquants/duckdb-helper 1.5.0 → 1.6.2

package/docs/specs/2026.07.05 [AI] 07-testing.md

@@ -0,0 +1,184 @@
+# テスト仕様書
+
+> 対象: `@aiquants/duckdb-helper` v1.6.0
+> テストソース: `tests/**`
+> 作成: 2026-07-05
+
+## 1. 目的とスコープ
+
+本パッケージのロジック整合性を担保するための**単体テスト仕様**。全ランタイムモジュール（`src/**`、型定義 `src/types` を除く）に対して **カバレッジ 100%（lines / functions / branches / statements）** を目標とし、v1.6.0 で修正した各不具合が再発しないことを保証する回帰テストを含む。
+
+## 2. テスト環境・ツール
+
+| 項目 | 内容 |
+|------|------|
+| ランナー | Vitest 3.2.6（`vitest.config.ts`） |
+| 実行環境 | `jsdom`（`window` / `URL` / `Blob` / React フックのレンダリングに必要） |
+| カバレッジ | `@vitest/coverage-v8`。対象 `src/**`、除外 `src/types/**`。閾値 100% |
+| React テスト | `@testing-library/react`（`renderHook` / `act` / `waitFor`） |
+| 型チェック | `tsconfig.test.json`（`tests/**` を含む）を `tsc --noEmit` で検証 |
+
+### 実行コマンド
+
+```bash
+pnpm run test              # 全テスト実行
+pnpm run test:coverage     # カバレッジ付き（閾値 100% を満たさなければ失敗）
+pnpm run typecheck:test    # tests を含む型チェック
+```
+
+## 3. テスト方針（モック戦略）
+
+DuckDB-WASM は実際の Worker と WASM ダウンロードを伴うため、単体テストでは**外部依存を完全にフェイク化**して全経路を決定論的に検証する。
+
+| 対象 | 手法 |
+|------|------|
+| `@duckdb/duckdb-wasm` | `vi.mock` で `getJsDelivrBundles` / `selectBundle` / `ConsoleLogger` / `AsyncDuckDB` を差し替え。`vi.hoisted` の共有状態で「バンドル選択」「instantiate」「connect」「query」「close」「terminate」の振る舞いをテストごとに制御し、発行 SQL を記録する |
+| `Worker` | `vi.stubGlobal` でフェイク（`terminate` 呼び出しを記録） |
+| `URL.createObjectURL` / `revokeObjectURL` | スタブして呼び出し回数を記録（Blob URL リーク検証用） |
+| `Blob` | 空のフェイククラス |
+| タイマー（120s/60s タイムアウト） | `vi.useFakeTimers()` + `advanceTimersByTimeAsync()` |
+| `DuckDBService`（フックのテスト） | `useDuckDB` のテストでは `../services/duckdb` を丸ごとモックし、`getStatus` とリスナー通知を制御 |
+
+## 4. テストファイル構成
+
+| ファイル | 対象モジュール | 主眼 |
+|---------|--------------|------|
+| `tests/services/duckdb.test.ts` | `services/duckdb.ts` | ライフサイクル・並行性・SQL 生成・型推定・トランザクション |
+| `tests/hooks/useDuckDB.test.tsx` | `hooks/useDuckDB.ts` | ステータス同期・操作ガード・`useDuckDBQuery` |
+| `tests/utils/duckdb-helpers.test.ts` | `utils/duckdb-helpers.ts` | 結果変換ヘルパーの境界値 |
+| `tests/utils/simple-logger.test.ts` | `utils/simple-logger.ts` | レベルフィルタ・整形・静的/インスタンス API |
+| `tests/index.test.ts` | `index.ts` | 公開エクスポートの存在確認 |
+| `tests/integration/dummy.test.ts` | 公開 API（結果ハンドリング） | ユーティリティを利用側の流れで組み合わせるスモークテスト |
+
+## 5. テストケース一覧
+
+### 5.1 `DuckDBService`（`tests/services/duckdb.test.ts`）
+
+#### initialize()
+
+| ケース | 検証内容 | 関連修正 |
+|--------|---------|---------|
+| 正常初期化 | `ready` に遷移、Blob URL を revoke、splink 一時コネクションを close | |
+| 高速パス | 初期化済みなら Worker を作り直さない | |
+| 同時呼び出しの重複排除 | 2 回同時呼び出しでも Worker は 1 つ | |
+| splink 失敗時の続行 | 拡張ロード失敗でも `ready`、一時コネクションは close | |
+| **instantiate 失敗 → 再試行可能** | `error` に遷移し `isReady() === false`、Worker terminate + Blob URL revoke、その後 `initialize()` で復旧 | 初期化復旧不能（High） |
+| 非 Error の reject | 文字列 reject でも `error` に遷移 | |
+| Worker 生成前の失敗 | `selectBundle` reject で Worker/URL 未生成のまま `error` | |
+| **タイムアウト（pending worker 無し）** | 120s 経過で reject、`error`、再試行可能 | タイマーリーク / 復旧 |
+| **タイムアウト（instantiate ハング）** | pending worker を terminate、Blob URL を revoke、遅延解決を無視 | Worker/Blob リーク・遅延結果 |
+| 破棄処理自体の例外 | terminate/revoke が例外を投げても握りつぶす | |
+
+#### getStatus()
+
+- 初期は `not-initialized`
+- 初期化中は `initializing`
+
+#### executeQuery / executeQueries
+
+| ケース | 検証内容 | 関連修正 |
+|--------|---------|---------|
+| 実行と単一コネクション再利用 | 2 回実行で二重 connect しない | getConnection 競合 |
+| クエリエラー伝播 | 失敗後も次クエリが実行可能（キューが詰まらない） | 操作直列化 |
+| クエリタイムアウト | 60s 経過で reject | タイマーリーク |
+| **タイムアウト時のコネクション破棄** | 詰まったコネクションを close し、次クエリは新しいコネクションで実行 | タイムアウト詰まり |
+| **コネクション取得ハング時のタイムアウト** | getConnection がハングしても 60s で reject（破棄対象なし） | 同上 |
+| 逐次実行 | 複数クエリを順に実行し結果配列を返す（単一キュー単位） | executeQueries 割り込み防止 |
+
+#### getConnection()
+
+- 同時アクセスで二重 connect しない（同一コネクションを返す）
+- connect 失敗時にリセットしてリトライ可能
+
+#### createTableFromData — バリデーション
+
+- `data` が null / 空配列 → `Data array is empty`
+- 列が無い（`[{}]`）→ `no columns`
+- 非文字列 / 空文字列のテーブル名 → `Invalid SQL identifier`
+
+#### createTableFromData — 型推定
+
+- `BIGINT`（int32 超含む）/ `DOUBLE` / `BOOLEAN` / `TIMESTAMP`（Date・厳密日付文字列）/ `VARCHAR`（非日付ハイフン文字列・無効日付・NaN・全 null）を正しく推定 → **BIGINT 化・厳密 TIMESTAMP** の回帰テスト
+
+#### createTableFromData — 値フォーマット
+
+- 文字列エスケープ（`O'Brien` → `'O''Brien'`）、Date、`TRUE`/`FALSE`、bigint、整数・小数、**NaN/Infinity → NULL**、**配列/オブジェクト → JSON**、**関数/循環参照 → NULL** → 値フォーマットの回帰テスト
+
+#### createTableFromData — スキーマ/行
+
+| ケース | 検証内容 | 関連修正 |
+|--------|---------|---------|
+| **列名の和集合** | 先頭行に無い列も CREATE/INSERT に含む、null 行は全 NULL | 列取りこぼし |
+| **トランザクション順序** | `BEGIN → DROP → CREATE → INSERT → COMMIT` の順序 | 原子性 |
+| primaryKey / DROP スキップ | `PRIMARY KEY ("id")` を付与、DROP なし | |
+| **識別子の安全なクォート** | ダブルクォートを含む名前を `""` にエスケープ | SQL 識別子 |
+| **INSERT 失敗でロールバック** | `ROLLBACK` を発行し reject | 原子性 |
+| ロールバック自体の失敗 | warn を出しつつ元エラーで reject | |
+
+#### createTableFromData — 重複排除 / verbose
+
+- **同名テーブルの同時呼び出しで構築は 1 回だけ**（verbose 有効/無効の両経路）→ dedup 回帰テスト
+
+#### getTableInfo / listTables
+
+- `DESCRIBE "a""b"`（クォート）、`SHOW TABLES`
+
+#### ステータスリスナー
+
+- 追加後に通知、削除後は通知されない
+- 例外を投げるリスナーが他のリスナーを妨げない
+
+#### cleanup / resetInstance
+
+- コネクション close + Worker terminate + `not-initialized` へ復帰
+- 未初期化での cleanup は安全
+- teardown 中の例外を握りつぶす
+- `resetInstance` はシングルトンを差し替え、`null` 状態での再呼び出しも安全
+
+### 5.2 React フック（`tests/hooks/useDuckDB.test.tsx`）
+
+| グループ | ケース |
+|---------|--------|
+| 初期化 | `autoInitialize` 既定でマウント時に `initialize()` を呼ぶ / `false` で呼ばない / リスナーをマウントで登録・アンマウントで解除 |
+| ステータス同期 | `ready` で `error` クリア / `error` でメッセージ設定（push リスナー経由） |
+| 操作ガード | 未 ready で全操作（`executeQuery`/`executeQueries`/`createTableFromData`/`getTableInfo`/`listTables`）が throw / ready で各サービスメソッドに委譲 |
+| 手動 initialize | Error reject でメッセージ設定 / 非 Error reject で汎用メッセージ / 成功時は静かに解決 |
+| `useDuckDBQuery` | 未 ready で fetch しない / 空 SQL で fetch しない / ready で data 取得 / エラー（Error・非 Error）で error 設定・data クリア / 手動 refetch / 依存配列変更で再 fetch / **依存配列の長さ変更でもエラーにならず再 fetch** |
+
+> 1 秒ポーリングの撤去により、フックは push リスナーのみで状態同期する。上記「ステータス同期」ケースがリスナー経由で全遷移を受け取れることを担保する。
+
+### 5.3 ユーティリティ（`tests/utils/duckdb-helpers.test.ts`）
+
+`duckdbTableToArray` / `getDuckDBRowCount` / `getDuckDBColumnCount` / `isDuckDBTable` について、非オブジェクト・メソッド/プロパティ欠如・型不一致・正常値の各分岐を網羅。
+
+### 5.4 ロガー（`tests/utils/simple-logger.test.ts`）
+
+- `LogLevel` の数値
+- コンストラクタ既定（WARN / `[duckdb-helper]` / console）
+- DEBUG で全レベル出力 / NONE で全抑制
+- 文字列メッセージのプレフィックス結合 / 非文字列は別引数
+- インスタンス/静的の `setLevel` / `setPrefix` / `setImplementation`
+
+### 5.5 公開 API（`tests/index.test.ts`）
+
+`useDuckDB` / `useDuckDBQuery` / `DuckDBService` / `duckDBService` / 各ユーティリティ / **`Logger` / `LogLevel`**（v1.6.0 で追加）がエクスポートされていることを確認。
+
+## 6. カバレッジ結果
+
+`pnpm run test:coverage` の結果（v1.6.0 時点、88 テスト）:
+
+| File | % Stmts | % Branch | % Funcs | % Lines |
+|------|---------|----------|---------|---------|
+| All files | 100 | 100 | 100 | 100 |
+| `index.ts` | 100 | 100 | 100 | 100 |
+| `hooks/useDuckDB.ts` | 100 | 100 | 100 | 100 |
+| `services/duckdb.ts` | 100 | 100 | 100 | 100 |
+| `utils/duckdb-helpers.ts` | 100 | 100 | 100 | 100 |
+| `utils/simple-logger.ts` | 100 | 100 | 100 | 100 |
+
+> カバレッジ閾値は `vitest.config.ts` で 100% に設定。下回るとテストは失敗する。
+
+## 7. 既知の制約
+
+- 本テストは**単体テスト**であり、実 DuckDB-WASM / 実 Worker を用いた結合は対象外（実 SQL の意味的正しさ、例えば `BEGIN/COMMIT` のトランザクション意味論は DuckDB 側の責務）。
+- `types/duckdb.ts` は型のみでランタイムコードを持たないためカバレッジ対象から除外。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/duckdb-helper",
-  "version": "1.5.0",
+  "version": "1.6.2",
   "description": "DuckDB helper utilities with React hooks, worker initialization, and typed query helpers",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -36,8 +36,12 @@
     "@duckdb/duckdb-wasm": "^1.30.0"
   },
   "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
+    "@vitest/coverage-v8": "3.2.6",
+    "jsdom": "^26.1.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "rimraf": "^6.1.2",
@@ -70,6 +74,7 @@
     "dev": "tsup --watch",
     "watch": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
     "clean": "rimraf dist",
     "publish:patch": "npm version patch && pnpm publish --no-git-checks",
     "publish:minor": "npm version minor && pnpm publish --no-git-checks",