LangChain4J Testing Strategies

Overview

LangChain4j の AI Services、RAG システム、ツール実行のためのユニットテスト、Testcontainers を使った統合テスト、エンドツーエンド検証のパターンです。

使用時機

• AI サービスのユニットテスト: LangChain4j AiServices を使用するサービスの高速で独立したテストが必要な場合
• LangChain4j コンポーネントの統合テスト: 実際の ChatModel、EmbeddingModel、RAG パイプラインを Testcontainers でテストする場合
• AI モデルのモック: 外部 API を呼び出さずに確定的なレスポンスが必要な場合
• LLM ベースの Java アプリケーションのテスト: RAG ワークフロー、ツール実行、取得チェーンを検証する場合

Instructions

1. モックを使用したユニットテスト

高速で独立したテストのためにモックモデルを使用します。references/unit-testing.md を参照してください。

ChatModel mockModel = mock(ChatModel.class);
when(mockModel.generate(any(String.class)))
    .thenReturn(Response.from(AiMessage.from("Mocked response")));

var service = AiServices.builder(AiService.class)
        .chatModel(mockModel)
        .build();

2. テスト用の依存関係を設定

Maven/Gradle の依存関係をセットアップします。references/testing-dependencies.md を参照してください。

• langchain4j-test - ガードレール アサーション
• testcontainers - コンテナ化されたテスト
• mockito - 外部依存関係のモック
• assertj - 流暢なアサーション

3. Testcontainers を使用した統合テスト

実際のサービスでテストします。references/integration-testing.md を参照してください。

@Testcontainers
class OllamaIntegrationTest {
    @Container
    static GenericContainer<?> ollama = new GenericContainer<>(
        DockerImageName.parse("ollama/ollama:0.5.4")
    ).withExposedPorts(11434);

    @Test
    void shouldGenerateResponse() {
        // コンテナのヘルスチェック
        assertTrue(ollama.isRunning());
        await().atMost(30, TimeUnit.SECONDS)
            .until(() -> ollama.getLogs().contains("API server listening"));

        ChatModel model = OllamaChatModel.builder()
                .baseUrl(ollama.getEndpoint())
                .build();

        // テスト前にモデルがレスポンスすることを確認
        assertDoesNotThrow(() -> model.generate("ping"));

        String response = model.generate("Test query");
        assertNotNull(response);
    }
}

4. 高度な機能

ストリーミング、メモリ、エラーハンドリング パターンは references/advanced-testing.md に記載されています。

5. テスティング ワークフロー

references/workflow-patterns.md のテスト ピラミッドに従います：

• 70% ユニットテスト: モックを使用した高速で独立したテスト
• 20% 統合テスト: ヘルスチェック付きの実際のサービス
• 10% エンドツーエンドテスト: 完全なワークフロー

70% ユニットテスト ─ Mock ChatModel、ガードレール、エッジケース
20% 統合テスト ─ Testcontainers、ベクトルストア、RAG
10% エンドツーエンドテスト ─ 完全なユーザージャーニー

トラブルシューティング

• コンテナが起動しない: Docker デーモンが実行中であることを確認し、イメージが存在することを確認し、タイムアウトを増やします
• モデルが応答しない: baseUrl が正しいことを確認し、コンテナログをチェックし、モデルが読み込まれていることを確認します
• テストタイムアウト: 遅いモデルの場合は @Timeout 期間を増やし、コンテナのリソース制限を確認します
• テストが不安定: アサーション前にリトライロジックまたはヘルスチェックを追加します

Examples

ユニットテスト

@Test
void shouldProcessQueryWithMock() {
    ChatModel mockModel = mock(ChatModel.class);
    when(mockModel.generate(any(String.class)))
        .thenReturn(Response.from(AiMessage.from("Test response")));

    var service = AiServices.builder(AiService.class)
            .chatModel(mockModel)
            .build();

    String result = service.chat("What is Java?");
    assertEquals("Test response", result);
}

Testcontainers を使用した統合テスト

@Testcontainers
class RAGIntegrationTest {
    @Container
    static GenericContainer<?> ollama = new GenericContainer<>(
        DockerImageName.parse("ollama/ollama:0.5.4")
    );

    @BeforeAll
    static void waitForContainerReady() {
        await().atMost(60, TimeUnit.SECONDS)
            .until(() -> ollama.getLogs().contains("API server listening"));
    }

    @Test
    void shouldCompleteRAGWorkflow() {
        assertTrue(ollama.isRunning());

        var chatModel = OllamaChatModel.builder()
                .baseUrl(ollama.getEndpoint())
                .build();

        var embeddingModel = OllamaEmbeddingModel.builder()
                .baseUrl(ollama.getEndpoint())
                .build();

        var store = new InMemoryEmbeddingStore<>();
        var retriever = EmbeddingStoreContentRetriever.builder()
                .chatModel(chatModel)
                .embeddingStore(store)
                .embeddingModel(embeddingModel)
                .build();

        var assistant = AiServices.builder(RagAssistant.class)
                .chatLanguageModel(chatModel)
                .contentRetriever(retriever)
                .build();

        String response = assistant.chat("What is Spring Boot?");
        assertNotNull(response);
        assertTrue(response.contains("Spring"));
    }
}

ベストプラクティス

• テスト分離のために @BeforeEach/@AfterEach を使用
• ユニットテストで実際の API を呼び出さない。常にモックを使用
• 外部サービス呼び出しに @Timeout を含める
• 成功とエラーハンドリングの両方のシナリオをテスト
• レスポンスの一貫性とエッジケースを検証

共通パターン

モック戦略

ChatModel mockModel = mock(ChatModel.class);
when(mockModel.generate(anyString())).thenReturn(Response.from(AiMessage.from("Mocked")));
when(mockModel.generate(eq("Hello"))).thenReturn(Response.from(AiMessage.from("Hi")));
when(mockModel.generate(contains("Java"))).thenReturn(Response.from(AiMessage.from("Java")));

アサーション ヘルパー

assertThat(response).isNotNull().isNotEmpty();
assertThat(response).containsAll(expectedKeywords);
assertThat(response).doesNotContain("error");

リファレンス ドキュメント

• Testing Dependencies - Maven/Gradle 設定
• Unit Testing - モックモデル、ガードレール
• Integration Testing - Testcontainers、実際のサービス
• Advanced Testing - ストリーミング、メモリ、エラーハンドリング
• Workflow Patterns - テスト ピラミッド、ベストプラクティス

制約と警告

• AI レスポンスは非決定論的。信頼性の高いユニットテストにはモックを使用
• テストでの実際の API 呼び出しを避け、コストとレート制限を防止
• 統合テストには Docker が必要。コンテナのヘルスチェックを使用
• RAG テストは適切にシードされたエンベディング ストアが必要
• モックベースのテストは実際の LLM の動作を保証できない。統合テストで補足
• テスト固有の設定プロファイルを使用。本番データに影響を与えない