CtrlK

Community Documentation Log in Get started

tessl/maven-com-embabel-agent--embabel-agent-test-support

Multi-module test support framework for Embabel Agent applications providing integration testing, mock AI services, and test configuration utilities

Overview

Eval results

Files

Your First Test

Name: tessl/maven-com-embabel-agent--embabel-agent-test-support
Author: tessl

Write your first integration test in 2 minutes.

Prerequisites

Installation completed
Basic understanding of JUnit 5
An agent or service that uses LLM operations

Simplest Possible Test

Here's a complete, minimal integration test:

import com.embabel.agent.test.integration.EmbabelMockitoIntegrationTest;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

public class MyFirstTest extends EmbabelMockitoIntegrationTest {

    @Test
    void testLlmStubbing() {
        // 1. Stub the LLM response
        whenGenerateText(prompt -> prompt.contains("hello"))
            .thenReturn("Hello, world!");

        // 2. Call your code that uses the LLM
        // String result = myService.askLlm("hello");

        // 3. Verify the LLM was called
        verifyGenerateText(prompt -> prompt.contains("hello"));
    }
}

What This Does

extends EmbabelMockitoIntegrationTest: Sets up Spring Boot test context with mocked LLM
whenGenerateText(...): Stubs the LLM to return "Hello, world!" when prompt contains "hello"
verifyGenerateText(...): Asserts the LLM was called with expected prompt

Step-by-Step Walkthrough

Step 1: Create Test Class

Create a test class that extends EmbabelMockitoIntegrationTest:

import com.embabel.agent.test.integration.EmbabelMockitoIntegrationTest;

public class MyAgentTest extends EmbabelMockitoIntegrationTest {
    // Tests go here
}

This base class provides:

Spring Boot test context
Mocked LLM operations
Stubbing and verification helper methods

Step 2: Write a Test Method

Add a test method with JUnit 5's @Test annotation:

import org.junit.jupiter.api.Test;

@Test
void testAgentBehavior() {
    // Test code goes here
}

Step 3: Stub the LLM

Stub the LLM to control its response:

whenGenerateText(prompt -> prompt.contains("expected text"))
    .thenReturn("Mocked response");

The predicate prompt -> prompt.contains("expected text") matches prompts that contain "expected text".

Step 4: Execute Your Code

Call your agent or service that uses the LLM:

String result = myAgent.process("user input");

When your code calls the LLM, it will receive the stubbed response.

Step 5: Verify and Assert

Verify the LLM was called and assert the result:

verifyGenerateText(prompt -> prompt.contains("expected text"));
assertEquals("Expected output", result);

Complete Example

Here's a complete working test:

import com.embabel.agent.test.integration.EmbabelMockitoIntegrationTest;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

public class GreetingAgentTest extends EmbabelMockitoIntegrationTest {

    @Test
    void testGreetingGeneration() {
        // Stub: When LLM receives prompt with "greet", return greeting
        whenGenerateText(prompt -> prompt.contains("greet"))
            .thenReturn("Hello! How can I help you today?");

        // Execute: Call the agent
        GreetingAgent agent = new GreetingAgent();
        String greeting = agent.generateGreeting("John");

        // Verify: LLM was called correctly
        verifyGenerateText(prompt ->
            prompt.contains("greet") && prompt.contains("John")
        );

        // Assert: Result is as expected
        assertNotNull(greeting);
        assertTrue(greeting.contains("Hello"));
    }
}

Kotlin Version

If you're using Kotlin:

import com.embabel.agent.test.integration.EmbabelMockitoIntegrationTest
import org.junit.jupiter.api.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull

class MyFirstTest : EmbabelMockitoIntegrationTest() {

    @Test
    fun `test LLM stubbing`() {
        // Stub the LLM response
        whenGenerateText { it.contains("hello") }
            .thenReturn("Hello, world!")

        // Call your code
        // val result = myService.askLlm("hello")

        // Verify the LLM was called
        verifyGenerateText { it.contains("hello") }
    }
}

Testing Object Creation

If your agent creates structured objects from LLM responses:

@Test
void testObjectCreation() {
    // Create expected object
    Person person = new Person("Alice", 30);

    // Stub object creation
    whenCreateObject(
        prompt -> prompt.contains("extract person"),
        Person.class
    ).thenReturn(person);

    // Execute
    Person result = myAgent.extractPerson("Alice is 30 years old");

    // Verify
    verifyCreateObject(
        prompt -> prompt.contains("extract person"),
        Person.class
    );

    // Assert
    assertEquals(person, result);
}

Common Patterns

Pattern: Multiple Stubs

@Test
void testMultiStepProcess() {
    // First LLM call
    whenGenerateText(p -> p.contains("step 1"))
        .thenReturn("Step 1 result");

    // Second LLM call
    whenGenerateText(p -> p.contains("step 2"))
        .thenReturn("Step 2 result");

    // Execute multi-step process
    String result = myAgent.multiStepProcess();

    // Verify both steps
    verifyGenerateText(p -> p.contains("step 1"));
    verifyGenerateText(p -> p.contains("step 2"));
}

Pattern: No LLM Verification

@Test
void testFastPath() {
    // Execute code path that shouldn't use LLM
    String result = myAgent.fastPath();

    // Verify no LLM calls were made
    verifyNoInteractions();
}

What You've Learned

✓ How to extend EmbabelMockitoIntegrationTest ✓ How to stub LLM text generation with whenGenerateText ✓ How to verify LLM calls with verifyGenerateText ✓ How to stub object creation with whenCreateObject ✓ How to write assertions for your tests

Next Steps

Common Tasks - More things you can do
Stubbing Guide - Advanced stubbing techniques
Verification Guide - Advanced verification techniques
Testing Patterns - Common testing patterns

Troubleshooting

Test Class Won't Compile

Ensure you have the integration testing module dependency:

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-test</artifactId>
    <version>0.3.3</version>
    <scope>test</scope>
</dependency>

Stub Not Working

Check that:

Your predicate matches the actual prompt text
The stub is set up before your code executes
You're testing the right LLM operation (text vs object creation)

Verification Failing