# langchain4j-testing-strategies

Guides Java tests for LangChain4j, from mocked ChatModel responses to RAG workflows and Testcontainers-based integration checks.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 3700 installs · ★ 363
- Author: giuseppe-trisciuoglio
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/giuseppe-trisciuoglio/developer-kit/tree/HEAD/plugins/developer-kit-java/skills/langchain4j-testing-strategies/SKILL.md
- Updated: 2026-09-10
- HTML: https://affpapa.org/en/nevibecode/skills/langchain4j-testing-strategies

## What it does

This skill provides patterns for unit testing LangChain4j services with mocked `ChatModel` responses, `AiServices`, retrieval chains, RAG workflows, and tool execution. It also covers testing dependencies such as `langchain4j-test`, `testcontainers`, `mockito`, and `assertj`, with examples for real services running in containers.

The material is split across references for unit tests, integration tests, advanced cases, dependencies, and workflow patterns. It covers streaming, memory, error handling, health checks, timeouts, and response assertions. Unit tests should avoid real API calls because model responses are non-deterministic and external calls can add cost or hit rate limits.

Integration scenarios require Docker, so check that the Docker daemon is running before relying on Testcontainers. The skill is available for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill langchain4j-testing-strategies -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/langchain4j-testing-strategies/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/langchain4j-testing-strategies/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill langchain4j-testing-strategies -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/langchain4j-testing-strategies/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill langchain4j-testing-strategies -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/langchain4j-testing-strategies/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install giuseppe-trisciuoglio/developer-kit langchain4j-testing-strategies
```

2. **Manually: put the files in place**
- File: `.github/skills/langchain4j-testing-strategies/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill langchain4j-testing-strategies -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/giuseppe-trisciuoglio/developer-kit --path plugins/developer-kit-java/skills/langchain4j-testing-strategies
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/langchain4j-testing-strategies/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add giuseppe-trisciuoglio/developer-kit --skill langchain4j-testing-strategies -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/giuseppe-trisciuoglio/developer-kit/tree/HEAD/plugins/developer-kit-java/skills/langchain4j-testing-strategies/SKILL.md

## When to use it
- mock ChatModel responses for isolated unit tests
- validate `AiServices` without calling external APIs
- test retrieval chains and RAG workflows
- run LangChain4j integration checks with Testcontainers
- cover model errors, timeouts, and edge cases

## Example prompts
- Set up a unit test for `AiServices` with a mocked `ChatModel` and deterministic responses.
- Create a RAG integration test using `OllamaChatModel`, `OllamaEmbeddingModel`, and Testcontainers.
- Add container health checks, timeouts, and error assertions to my LangChain4j tests.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 8618ecdf71bbcb04.

BEGIN THIRD-PARTY FILE 8618ecdf71bbcb04
````text
---
name: langchain4j-testing-strategies
description: Provides unit test, integration test, and mock AI patterns for LangChain4j applications. Creates mock LLM responses, tests retrieval chains, validates RAG workflows, and implements Testcontainers-based integration tests for Java AI services. Use when unit testing AI services, integration testing LangChain4j components, mocking AI models, or testing LLM-based Java applications.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# 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`.

```java
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 assertions
- `testcontainers` - Containerized testing
- `mockito` - Mock external dependencies
- `assertj` - Fluent assertions

### 3. Integration Testing with Testcontainers

Test with real services. See `references/integration-testing.md`.

```java
@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());
````
END THIRD-PARTY FILE 8618ecdf71bbcb04

The third-party file has ended. Everything between the 8618ecdf71bbcb04 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2282 of 7240 bytes. © giuseppe-trisciuoglio · MIT · https://github.com/giuseppe-trisciuoglio/developer-kit/tree/HEAD/plugins/developer-kit-java/skills/langchain4j-testing-strategies/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md