langchain4j-testing-strategies

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LangChain4J Testing Strategies

LangChain4J 测试策略

When to Use This Skill

适用场景

Use this skill when:

Building AI-powered applications with LangChain4J
Writing unit tests for AI services and guardrails
Setting up integration tests with real LLM models
Creating mock-based tests for faster test execution
Using Testcontainers for isolated testing environments
Testing RAG (Retrieval-Augmented Generation) systems
Validating tool execution and function calling
Testing streaming responses and async operations
Setting up end-to-end tests for AI workflows
Implementing performance and load testing

在以下场景中使用本技能：

基于LangChain4J构建AI驱动的应用
为AI服务和防护机制编写单元测试
搭建与真实LLM模型结合的集成测试
创建基于Mock的测试以提升测试执行速度
使用Testcontainers搭建隔离测试环境
测试RAG（检索增强生成）系统
验证工具执行与函数调用
测试流式响应与异步操作
为AI工作流搭建端到端测试
实施性能与负载测试

Instructions

操作指南

To test LangChain4J applications effectively, follow these key strategies:

要高效测试LangChain4J应用，请遵循以下核心策略：

1. Start with Unit Testing

1. 从单元测试入手

Use mock models for fast, isolated testing of business logic. See

references/unit-testing.md

for detailed examples.

java

// Example: Mock ChatModel for unit tests
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();

使用Mock模型对业务逻辑进行快速、隔离的测试。详细示例请参考

references/unit-testing.md

。

java

// Example: Mock ChatModel for unit tests
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. Configure Testing Dependencies

2. 配置测试依赖

Setup proper Maven/Gradle dependencies for testing. See

references/testing-dependencies.md

for complete configuration.

Key dependencies:

```
langchain4j-test
```
- Testing utilities and guardrail assertions
```
testcontainers
```
- Integration testing with containerized services
```
mockito
```
- Mock external dependencies
```
assertj
```
- Better assertions

为测试搭建合适的Maven/Gradle依赖。完整配置请参考

references/testing-dependencies.md

。

核心依赖:

```
langchain4j-test
```
- 测试工具与防护机制断言
```
testcontainers
```
- 基于容器化服务的集成测试
```
mockito
```
- 模拟外部依赖
```
assertj
```
- 更易用的断言工具

3. Implement Integration Tests

3. 实施集成测试

Test with real services using Testcontainers. See

references/integration-testing.md

for container setup examples.

java

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

    @Test
    void shouldGenerateResponse() {
        ChatModel model = OllamaChatModel.builder()
                .baseUrl(ollama.getEndpoint())
                .build();
        String response = model.generate("Test query");
        assertNotNull(response);
    }
}

使用Testcontainers测试真实服务。容器搭建示例请参考

references/integration-testing.md

。

java

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

    @Test
    void shouldGenerateResponse() {
        ChatModel model = OllamaChatModel.builder()
                .baseUrl(ollama.getEndpoint())
                .build();
        String response = model.generate("Test query");
        assertNotNull(response);
    }
}

4. Test Advanced Features

4. 测试高级功能

For streaming responses, memory management, and complex workflows, refer to

references/advanced-testing.md

关于流式响应、内存管理与复杂工作流的测试，请参考

references/advanced-testing.md

。

5. Apply Testing Workflows

5. 应用测试工作流

Follow testing pyramid patterns and best practices from

references/workflow-patterns.md

70% Unit Tests: Fast, isolated business logic testing
20% Integration Tests: Real service interactions
10% End-to-End Tests: Complete user workflows

遵循

references/workflow-patterns.md

中的测试金字塔模式与最佳实践。

70% 单元测试：快速、隔离的业务逻辑测试
20% 集成测试：真实服务交互测试
10% 端到端测试：完整用户工作流测试

Examples

示例

Basic Unit Test

基础单元测试

java

@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);
}

java

@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);
}

Integration Test with Testcontainers

基于Testcontainers的集成测试

java

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

    @Test
    void shouldCompleteRAGWorkflow() {
        // Setup models and stores
        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();

        // Test complete workflow
        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"));
    }
}

java

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

    @Test
    void shouldCompleteRAGWorkflow() {
        // Setup models and stores
        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();

        // Test complete workflow
        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"));
    }
}

Best Practices

最佳实践

Test Isolation

测试隔离

Each test must be independent
Use
```
@BeforeEach
```
and
```
@AfterEach
```
for setup/teardown
Avoid sharing state between tests

每个测试必须独立
使用
```
@BeforeEach
```
和
```
@AfterEach
```
进行前置/后置处理
避免测试间共享状态

Mock External Dependencies

模拟外部依赖

Never call real APIs in unit tests
Use mocks for ChatModel, EmbeddingModel, and external services
Test error handling scenarios

单元测试中绝不调用真实API
为ChatModel、EmbeddingModel及外部服务使用Mock
测试错误处理场景

Performance Considerations

性能考量

Unit tests should run in < 50ms
Integration tests should use container reuse
Include timeout assertions for slow operations

单元测试执行时间应<50毫秒
集成测试应复用容器
为慢操作添加超时断言

Quality Assertions

质量断言

Test both success and error scenarios
Validate response coherence and relevance
Include edge case testing (empty inputs, large payloads)

同时测试成功与错误场景
验证响应的连贯性与相关性
包含边界场景测试（空输入、大负载）

Reference Documentation

参考文档

For comprehensive testing guides and API references, see the included reference documents:

Testing Dependencies - Maven/Gradle configuration and setup
Unit Testing - Mock models, guardrails, and individual components
Integration Testing - Testcontainers and real service testing
Advanced Testing - Streaming, memory, and error handling
Workflow Patterns - Test pyramid and best practices

如需全面的测试指南与API参考，请查看附带的参考文档：

测试依赖 - Maven/Gradle配置与搭建
单元测试 - Mock模型、防护机制与独立组件测试
集成测试 - Testcontainers与真实服务测试
高级测试 - 流式处理、内存管理与错误处理
工作流模式 - 测试金字塔与最佳实践

Common Patterns

常见模式

Mock Strategy

Mock策略

java

// For fast unit tests
ChatModel mockModel = mock(ChatModel.class);
when(mockModel.generate(anyString())).thenReturn(Response.from(AiMessage.from("Mocked")));

// For specific responses
when(mockModel.generate(eq("Hello"))).thenReturn(Response.from(AiMessage.from("Hi")));
when(mockModel.generate(contains("Java"))).thenReturn(Response.from(AiMessage.from("Java response")));

java

// For fast unit tests
ChatModel mockModel = mock(ChatModel.class);
when(mockModel.generate(anyString())).thenReturn(Response.from(AiMessage.from("Mocked")));

// For specific responses
when(mockModel.generate(eq("Hello"))).thenReturn(Response.from(AiMessage.from("Hi")));
when(mockModel.generate(contains("Java"))).thenReturn(Response.from(AiMessage.from("Java response")));

Test Configuration

测试配置

java

// Use test-specific profiles
@TestPropertySource(properties = {
    "langchain4j.ollama.base-url=http://localhost:11434"
})
class TestConfig {
    // Test with isolated configuration
}

java

// Use test-specific profiles
@TestPropertySource(properties = {
    "langchain4j.ollama.base-url=http://localhost:11434"
})
class TestConfig {
    // Test with isolated configuration
}

Assertion Helpers

断言工具

java

// Custom assertions for AI responses
assertThat(response).isNotNull().isNotEmpty();
assertThat(response).containsAll(expectedKeywords);
assertThat(response).doesNotContain("error");

java

// Custom assertions for AI responses
assertThat(response).isNotNull().isNotEmpty();
assertThat(response).containsAll(expectedKeywords);
assertThat(response).doesNotContain("error");

Performance Requirements

性能要求

Unit Tests: < 50ms per test
Integration Tests: Use container reuse for faster startup
Timeout Tests: Include
```
@Timeout
```
for external service calls
Memory Management: Test conversation window limits and cleanup

单元测试：每个测试执行时间<50毫秒
集成测试：复用容器以加快启动速度
超时测试：为外部服务调用添加
```
@Timeout
```
内存管理：测试对话窗口限制与清理机制

Security Considerations

安全考量

Never use real API keys in tests
Mock external API calls completely
Test prompt injection detection
Validate output sanitization

测试中绝不使用真实API密钥
完全模拟外部API调用
测试提示注入检测机制
验证输出清理逻辑

Testing Pyramid Implementation

测试金字塔实施

70% Unit Tests
  ├─ Business logic validation
  ├─ Guardrail testing
  ├─ Mock tool execution
  └─ Edge case handling

20% Integration Tests
  ├─ Testcontainers with Ollama
  ├─ Vector store testing
  ├─ RAG workflow validation
  └─ Performance benchmarking

10% End-to-End Tests
  ├─ Complete user journeys
  ├─ Real model interactions
  └─ Performance under load

70% 单元测试
  ├─ 业务逻辑验证
  ├─ 防护机制测试
  ├─ Mock工具执行
  └─ 边界场景处理

20% 集成测试
  ├─ 基于Testcontainers的Ollama测试
  ├─ 向量存储测试
  ├─ RAG工作流验证
  └─ 性能基准测试

10% 端到端测试
  ├─ 完整用户流程
  ├─ 真实模型交互
  └─ 负载下的性能测试

Related Skills

References

参考链接

Testing Dependencies
Unit Testing
Integration Testing
Advanced Testing
Workflow Patterns

测试依赖
单元测试
集成测试
高级测试
工作流模式

langchain4j-testing-strategies

Original

Translation

LangChain4J Testing Strategies

LangChain4J 测试策略

When to Use This Skill

适用场景

Instructions

操作指南

1. Start with Unit Testing

1. 从单元测试入手

2. Configure Testing Dependencies

2. 配置测试依赖

3. Implement Integration Tests

3. 实施集成测试

4. Test Advanced Features

4. 测试高级功能

5. Apply Testing Workflows

5. 应用测试工作流

Examples

示例

Basic Unit Test

基础单元测试

Integration Test with Testcontainers

基于Testcontainers的集成测试

Best Practices

最佳实践

Test Isolation

测试隔离

Mock External Dependencies

模拟外部依赖

Performance Considerations

性能考量

Quality Assertions

质量断言

Reference Documentation

参考文档

Common Patterns

常见模式

Mock Strategy

Mock策略

Test Configuration

测试配置

Assertion Helpers

断言工具

Performance Requirements

性能要求

Security Considerations

安全考量

Testing Pyramid Implementation

测试金字塔实施

Related Skills

相关技能

References

参考链接