# バッチ設計書 29-integration-test

## 概要

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

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

本バッチは、clojure-lspの統合テストを実行する処理である。実際のclojure-lsp実行ファイル（スクリプトまたはネイティブバイナリ）をLSPサーバーとして起動し、LSPプロトコルを介した各種機能の動作を検証する。

**業務上の目的・背景**：ユニットテストでは個々のコンポーネントをテストするが、統合テストではclojure-lsp全体が正しく動作することを検証する。LSPクライアント（エディタ）から見た視点で、初期化、定義ジャンプ、補完、リネーム、コードアクション等のLSP機能が期待通りに動作することを確認する。これにより、リリース前の最終的な品質保証を行う。

**バッチの実行タイミング**：リリース前の最終確認時、CI/CDパイプラインでネイティブバイナリビルド後に実行される。testバッチには含まれず、別途実行される。

**主要な処理内容**：
1. プロジェクトルートでclojure-lsp実行ファイルを検索
2. 実行ファイルの一意性を検証（複数存在する場合はエラー）
3. cliディレクトリでBabashkaを使用してintegration-testを実行
4. 各種LSP機能の統合テストを実行（タイムアウト付き）

**前後の処理との関連**：実行前にprod-cli、native-cli、debug-cliのいずれかでclojure-lsp実行ファイルをビルドしておく必要がある。testバッチとは独立しており、ネイティブバイナリの動作確認が主目的である。

**影響範囲**：テスト実行中にサンプルプロジェクト内で一時ファイルが作成される可能性があるが、永続的な変更は行わない。

## バッチ種別

テスト処理 / 統合テスト

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース前）/ ビルド後（CI/CD） |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | 手動（bb integration-test）またはCI/CD |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| clojure-lsp実行ファイル | プロジェクトルートにclojure-lspまたはclojure-lsp.batが存在すること |
| Babashka | bb コマンドが利用可能であること |
| 実行ファイルの一意性 | clojure-lspとclojure-lsp.batが同時に存在しないこと |

### 実行可否判定

- 実行ファイルが見つからない場合、"No clojure-lsp executables found." エラーで終了
- 複数の実行ファイルが見つかった場合、"More than one clojure-lsp executables found." エラーで終了

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | コマンドラインパラメータは不要 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| clojure-lsp / clojure-lsp.bat | 実行ファイル | テスト対象の実行ファイル |
| cli/integration-test/**/*.clj | Clojureテストコード | 統合テストファイル |
| cli/integration-test/sample-test/ | テストプロジェクト | テスト対象のサンプルプロジェクト |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト実行結果 |
| 標準エラー | テキスト | テスト失敗時の詳細ログ |
| 終了コード | 整数 | 0=成功、1以上=失敗 |
| ログファイル | テキスト | clojure-lsp.integration-test.out |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | clojure-lsp.integration-test.out |
| 出力先 | cli/integration-test/sample-test/ |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. 実行ファイル検索
   └─ lsp-bin-filename関数で対象ファイル名を決定
   └─ :native と :script の両方をチェック
   └─ 存在するファイルをフィルタリング

2. 実行ファイル検証
   └─ 0個の場合: "No clojure-lsp executables found." で例外
   └─ 2個以上の場合: "More than one clojure-lsp executables found." で例外
   └─ 1個の場合: テスト続行

3. Babashkaプロセス起動
   └─ cliディレクトリで bb integration-test <実行ファイルパス> を実行

4. テストスイート実行
   └─ entrypoint.clj の run-all 関数が呼び出される
   └─ 全テスト名前空間をrequire
   └─ タイムアウト設定（Win/Mac: 25分、その他: 15分）

5. 各テスト実行
   └─ initialize-test, definition-test, completion-test 等
   └─ LSPクライアントを模したテストを実行
   └─ 各リクエスト/レスポンスを検証

6. 結果出力
   └─ テスト失敗時はログ末尾100行を出力
   └─ タイムアウト時はエラーメッセージを出力

7. 終了
   └─ 失敗+エラー数を終了コードとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[実行ファイル検索]
    B --> C{実行ファイル数?}
    C -->|0| D[No executables found エラー]
    C -->|2+| E[Multiple executables found エラー]
    C -->|1| F[bb integration-test 実行]
    F --> G[テスト名前空間ロード]
    G --> H[タイムアウト設定]
    H --> I[テストスイート実行]
    I --> J{タイムアウト?}
    J -->|Yes| K[タイムアウトエラー、ログ出力]
    J -->|No| L{テスト結果?}
    L -->|失敗あり| M[失敗ログ出力]
    L -->|全成功| N[終了コード0で終了]
    M --> O[非ゼロ終了コードで終了]
    K --> O
```

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

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

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

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1+ | テスト失敗 | LSP機能が期待通りでない | テストコードまたは実装を修正 |
| 1 | タイムアウト | テストが制限時間内に完了しない | 個別テストを実行して原因を特定 |
| - | 実行ファイルなし | clojure-lspがビルドされていない | prod-cli/native-cliでビルド |
| - | 複数実行ファイル | スクリプトとネイティブ両方存在 | 不要な方を削除 |

### リトライ仕様

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

### 障害時対応

1. タイムアウトの場合：
   - ログファイルを確認して停止箇所を特定
   - 個別のテスト名前空間を実行して問題を絞り込み
2. テスト失敗の場合：
   - 出力されたログから失敗したテストを特定
   - sample-testプロジェクトの状態を確認
3. 実行ファイル関連エラーの場合：
   - bb clean でクリーンアップ
   - 適切なビルドコマンドを実行

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約30テスト名前空間 |
| 目標処理時間 | 15分以内（Linux）、25分以内（Win/Mac） |
| メモリ使用量上限 | clojure-lsp実行ファイルの要件に依存 |

## 排他制御

同一プロジェクトディレクトリでの同時実行は非推奨。LSPサーバープロセスやログファイルが競合する可能性がある。

## ログ出力

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

## 監視・アラート

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

## 備考

- テスト対象の主要名前空間：
  - initialize-test - 初期化プロトコルのテスト
  - definition-test - 定義ジャンプのテスト
  - declaration-test - 宣言ジャンプのテスト
  - implementation-test - 実装ジャンプのテスト
  - completion-test - 補完機能のテスト
  - rename-test - リネーム機能のテスト
  - code-action-test - コードアクションのテスト
  - diagnostics-test - 診断機能のテスト
  - formatting-test - フォーマット機能のテスト
  - document-symbol-test - ドキュメントシンボルのテスト
  - api/clean-ns-test, api/format-test 等 - CLI API機能のテスト
- タイムアウト設定の理由：
  - Windows/Mac CIは一般的に実行が遅いため、長めに設定
  - Linuxは高速なため、短めの15分に設定
- 失敗時のログ出力機能：
  - テスト失敗時に最初に失敗したテストでログ末尾100行を出力
  - CIでのデバッグを容易にするための機能
- testバッチに含まれない理由：
  - 実行ファイルのビルドが必要
  - 実行時間が長い
  - ユニットテストとは性質が異なる
