사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill langchain4j-testing-strategies시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
LangChain4J Testing Strategies
Overview
Patterns for unit testing with mocks, integration testing with Testcontainers, and end-to-end validation of RAG systems, AI Services, and tool execution.
When to Use
- Unit testing AI services: When you need fast, isolated tests for services using LangChain4j AiServices
- Integration testing LangChain4j components: When testing real ChatModel, EmbeddingModel, or RAG pipelines with Testcontainers
- Mocking AI models: When you need deterministic responses without calling external APIs
- Testing LLM-based Java applications: When validating RAG workflows, tool execution, or retrieval chains
Instructions
1. Unit Testing with Mocks
Use mock models for fast, isolated testing. See 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. Configure Testing Dependencies
Setup Maven/Gradle dependencies. See references/testing-dependencies.md.
langchain4j-test- Guardrail assertionstestcontainers- Containerized testingmockito- Mock external dependenciesassertj- Fluent assertions
3. Integration Testing with Testcontainers
Test with real services. See 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() {
// Verify container is healthy
assertTrue(ollama.isRunning());
await().atMost(30, TimeUnit.SECONDS)
.until(() -> ollama.getLogs().contains("API server listening"));
ChatModel model = OllamaChatModel.builder()
.baseUrl(ollama.getEndpoint())
.build();
// Verify model responds before running tests
assertDoesNotThrow(() -> model.generate("ping"));
String response = model.generate("Test query");
assertNotNull(response);
}
}4. Advanced Features
Streaming, memory, error handling patterns in references/advanced-testing.md.
5. Testing Workflow
Follow the testing pyramid from references/workflow-patterns.md:
- 70% Unit Tests: Fast, isolated with mocks
- 20% Integration Tests: Real services with health checks
- 10% End-to-End Tests: Complete workflows
70% Unit Tests ─ Mock ChatModel, guardrails, edge cases
20% Integration Tests ─ Testcontainers, vector stores, RAG
10% End-to-End Tests ─ Complete user journeysTroubleshooting
- Container fails to start: Check Docker daemon is running, verify image exists, increase timeout
- Model not responding: Verify baseUrl is correct, check container logs, ensure model is loaded
- Test timeout: Increase
@Timeoutduration for slow models, check container resource limits - Flaky tests: Add retry logic or health checks before assertions
Examples
Unit Test
@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
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"));
}
}Best Practices
- Use
@BeforeEach/@AfterEachfor test isolation - Never call real APIs in unit tests; use mocks
- Include
@Timeoutfor external service calls - Test both success and error handling scenarios
- Validate response coherence and edge cases
Common Patterns
Mock Strategy
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")));Assertion Helpers
assertThat(response).isNotNull().isNotEmpty();
assertThat(response).containsAll(expectedKeywords);
assertThat(response).doesNotContain("error");Reference Documentation
- [Testing Dependencies](references/testing-dependencies.md) - Maven/Gradle configuration
- [Unit Testing](references/unit-testing.md) - Mock models, guardrails
- [Integration Testing](references/integration-testing.md) - Testcontainers, real services
- [Advanced Testing](references/advanced-testing.md) - Streaming, memory, error handling
- [Workflow Patterns](references/workflow-patterns.md) - Test pyramid, best practices
Constraints and Warnings
- AI responses are non-deterministic; use mocks for reliable unit tests
- Avoid real API calls in tests to prevent costs and rate limiting
- Integration tests require Docker; use container health checks
- RAG tests need properly seeded embedding stores
- Mock-based tests cannot guarantee actual LLM behavior; supplement with integration tests
- Use test-specific configuration profiles; never affect production data

