# バッチ設計書 28-pod-test

## 概要

本ドキュメントは、clojure-lspプロジェクトにおけるBabashka PODテストバッチ（pod-test）の設計を記載したものである。

### 本バッチの処理概要

本バッチは、clojure-lspのBabashka POD機能をテストする処理である。Babashka PODは、clojure-lspをBabashkaスクリプトから利用可能にする機能であり、このテストではPODプロトコルを介したAPI呼び出しが正常に動作することを検証する。

**業務上の目的・背景**：clojure-lspはBabashka PODとしても利用可能であり、BabashkaスクリプトからLSP機能（clean-ns、format、diagnostics等）を呼び出すことができる。このテストは、PODプロトコルの実装が正しく動作し、Babashkaとの連携が問題なく行えることを保証する。POD機能により、開発者はBabashkaスクリプトからclojure-lspの機能を活用でき、CIパイプラインや自動化スクリプトでの利用が可能になる。

**バッチの実行タイミング**：POD機能に関連する変更があった場合に手動で実行される。CI/CDパイプラインでリリース前に実行されることがある。testバッチには含まれず、別途実行される。

**主要な処理内容**：
1. cliディレクトリで clojure -M:pod-test を実行
2. Cognitect test-runnerを使用してテストを実行
3. babashka.podsライブラリを使用してPODをロード
4. clojure-lsp APIの各機能をPOD経由でテスト

**前後の処理との関連**：PODテストを実行する前に、clojure-lspが正しくビルドされている必要がある。ネイティブイメージを使用する場合は、CLOJURE_LSP_TEST_ENV=native環境変数を設定する。testバッチには含まれない独立したテストである。

**影響範囲**：テスト実行中に一時的なファイル操作が行われる可能性があるが、永続的な変更は行わない。

## バッチ種別

テスト処理 / 統合テスト

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | 手動（bb pod-test） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| JDK | Java Development Kit がインストールされていること |
| Babashka | bb コマンドが利用可能であること |
| Clojure CLI | clojure コマンドが利用可能であること |
| 依存関係 | cli/deps.edn に定義された依存関係が解決可能であること |

### 実行可否判定

特別な実行可否判定は行わない。前提条件が満たされていれば実行可能である。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| CLOJURE_LSP_TEST_ENV | 環境変数 | No | なし | "native"を設定するとネイティブバイナリを使用 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| cli/pod-test/**/*.clj | Clojureテストコード | PODテストファイル |
| cli/integration-test/sample-test/ | テストプロジェクト | テスト対象のサンプルプロジェクト |
| cli/deps.edn | EDN | 依存関係定義（:pod-test エイリアス） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト実行結果 |
| 終了コード | 整数 | 0=成功、1以上=失敗 |

### 出力ファイル仕様

ファイル出力は行わない。

## 処理フロー

### 処理シーケンス

```
1. テスト環境判定
   └─ CLOJURE_LSP_TEST_ENV 環境変数をチェック
   └─ "native" の場合は ../clojure-lsp バイナリを使用
   └─ それ以外は clojure -M:run で起動

2. Clojure CLI実行
   └─ cliディレクトリで clojure -M:pod-test を実行
   └─ Cognitect test-runner が起動

3. PODロード
   └─ babashka.pods/load-pod で clojure-lsp をPODとしてロード
   └─ clojure-lsp.api 名前空間が利用可能になる

4. テスト実行
   └─ analyze-project-only! テスト
   └─ analyze-project-and-deps! テスト
   └─ clean-ns! テスト
   └─ diagnostics テスト
   └─ format! テスト

5. 結果出力
   └─ 各テストの成功/失敗を出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[clojure -M:pod-test 実行]
    B --> C[Cognitect test-runner起動]
    C --> D{CLOJURE_LSP_TEST_ENV?}
    D -->|native| E[../clojure-lsp バイナリ使用]
    D -->|その他| F[clojure -M:run 使用]
    E --> G[PODロード]
    F --> G
    G --> H[clojure-lsp.api require]
    H --> I[各APIテスト実行]
    I --> J{全テスト成功?}
    J -->|Yes| K[終了コード0で終了]
    J -->|No| L[非ゼロ終了コードで終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベースを使用しない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | N/A |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1+ | テスト失敗 | POD API呼び出しが期待通りでない | テストコードまたは実装を修正 |
| - | PODロード失敗 | clojure-lspの起動に失敗 | ビルドを確認、依存関係を解決 |
| - | タイムアウト | PODプロセスが応答しない | プロセスを終了して再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. PODロード失敗の場合：
   - clojure-lspが正しくビルドされているか確認
   - clojure -M:run で単独起動できるか確認
2. テスト失敗の場合：
   - 失敗したAPIのログを確認
   - sample-testプロジェクトの状態を確認

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 5テストケース |
| 目標処理時間 | 5分以内 |
| メモリ使用量上限 | JVMデフォルト |

## 排他制御

同一プロジェクトディレクトリでの同時実行は非推奨。PODプロセスが競合する可能性がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | テスト開始時 | - |
| 進捗ログ | テスト実行中 | 各テストケースの結果 |
| 終了ログ | テスト終了時 | テストサマリー |
| エラーログ | テスト失敗時 | 失敗したテストの詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDシステム |
| 処理時間 | 10分 | CI/CDシステム |

## 備考

- テスト対象API：
  - `analyze-project-only!` - プロジェクトのみを解析
  - `analyze-project-and-deps!` - プロジェクトと依存関係を解析
  - `clean-ns!` - 名前空間のクリーンアップ（dry?オプション対応）
  - `diagnostics` - 診断情報の取得
  - `format!` - コードフォーマット（dry?オプション対応）
- PODプロトコル：
  - Transit + JSONフォーマットで通信
  - babashka.podsライブラリがプロトコルを抽象化
- テスト環境の違い：
  - JVM版（デフォルト）: `clojure -M:run` で起動、開発中のテストに適している
  - ネイティブ版: `../clojure-lsp` バイナリを使用、リリース前の最終確認に適している
- testバッチに含まれない理由：
  - PODプロセスの起動が必要で、通常のユニットテストより時間がかかる
  - ネイティブバイナリのテストを含むため、ビルド後に実行する必要がある
