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

Architecture Reference

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

Understanding how the Embabel Agent Test Support framework is organized and how its components relate to each other.

Module Architecture

The test support framework consists of three independent but complementary modules:

embabel-agent-test-support (parent POM)
│
├── embabel-agent-test
│   ├── Purpose: Mockito integration testing
│   ├── Language: Java
│   └── Provides: EmbabelMockitoIntegrationTest
│
├── embabel-agent-test-common
│   ├── Purpose: Fake AI services
│   ├── Language: Kotlin
│   └── Provides: FakeEmbeddingModel
│
└── embabel-agent-test-internal
    ├── Purpose: Spring test configuration
    ├── Language: Kotlin
    └── Provides: FakeAiConfiguration, OptionsConverterTestSupport

Module Dependencies

Dependency Graph

embabel-agent-test-internal
├── depends on: embabel-agent-test
├── depends on: embabel-agent-test-common
└── depends on: embabel-agent-domain

embabel-agent-test
└── depends on: embabel-agent-api

embabel-agent-test-common
└── depends on: embabel-agent-common

External Dependencies

embabel-agent-test
├── Spring Boot Test
├── Mockito
└── JUnit 5

embabel-agent-test-common
├── Spring AI
└── Kotlin stdlib

embabel-agent-test-internal
├── Spring Boot Test
├── MockK
└── Kotlin stdlib

Component Architecture

Integration Testing Component (embabel-agent-test)

EmbabelMockitoIntegrationTest (abstract base class)
│
├── Annotations
│   ├── @SpringBootTest
│   └── @TestPropertySource
│
├── Injected Components
│   ├── AgentPlatform (autowired)
│   └── LlmOperations (mocked via @MockitoBean)
│
├── Stubbing Methods
│   ├── whenGenerateText(...)
│   └── whenCreateObject(...)
│
├── Verification Methods
│   ├── verifyGenerateText(...)
│   ├── verifyCreateObject(...)
│   ├── verifyNoInteractions()
│   └── verifyNoMoreInteractions()
│
└── Capture Methods
    ├── capturePrompt()
    ├── captureLlmInteraction()
    └── captureOutputClass()

Fake AI Services Component (embabel-agent-test-common)

FakeEmbeddingModel
│
├── Implements: EmbeddingModel (Spring AI)
│
├── Properties
│   └── dimensions: Int
│
└── Methods
    ├── embed(document: Document): FloatArray
    ├── embed(texts: List<String>): MutableList<FloatArray>
    └── call(request: EmbeddingRequest): EmbeddingResponse

Test Configuration Component (embabel-agent-test-internal)

FakeAiConfiguration
│
├── Annotation: @TestConfiguration
│
└── Beans
    ├── cheapest(): LlmService<*>
    │   └── SpringAiLlmService with mocked ChatModel
    ├── best(): LlmService<*>
    │   └── SpringAiLlmService with mocked ChatModel
    └── embedding(): EmbeddingService
        └── SpringAiEmbeddingService with FakeEmbeddingModel

OptionsConverterTestSupport<O>
│
├── Type Parameter: O extends ChatOptions
│
├── Properties
│   └── optionsConverter: OptionsConverter<O>
│
└── Tests
    └── should preserve core values()

Data Flow

Stubbing Flow

Test Code
    ↓
whenGenerateText(predicate)
    ↓
Mockito Configuration
    ↓
LlmOperations Mock
    ↓
Code Under Test calls LLM
    ↓
Mock intercepts call
    ↓
Predicate evaluated
    ↓
Stubbed response returned
    ↓
Test Code receives result

Verification Flow

Test Code executes
    ↓
Code Under Test calls LLM
    ↓
Mockito records interaction
    ↓
Test Code calls verifyGenerateText(predicate)
    ↓
Mockito checks recorded interactions
    ↓
Predicate evaluated against actual calls
    ↓
Verification passes or fails
    ↓
Test continues or throws AssertionError

Embedding Flow

Test Code
    ↓
FakeEmbeddingModel.embed(document)
    ↓
generateRandomFloatArray(dimensions)
    ↓
Random FloatArray created
    ↓
Returned to caller
    ↓
Used in code under test

Spring Configuration Flow

Test Class
    ↓
@Import(FakeAiConfiguration::class)
    ↓
Spring Boot Test Context loads
    ↓
FakeAiConfiguration beans created
    ├── cheapest bean (mocked LlmService)
    ├── best bean (mocked LlmService)
    └── embedding bean (with FakeEmbeddingModel)
    ↓
Beans injected into test
    ↓
Test code uses beans

Integration Points

With Spring Boot

Test Class
    │
    ├── extends EmbabelMockitoIntegrationTest
    │   └── provides @SpringBootTest context
    │
    └── @Import(FakeAiConfiguration::class)
        └── adds fake AI beans to context

Result: Full Spring Boot test with mocked LLMs and fake embeddings

With Mockito

EmbabelMockitoIntegrationTest
    │
    ├── @MockitoBean for LlmOperations
    │   └── Mockito creates mock
    │
    └── Helper methods use Mockito API
        ├── whenGenerateText → Mockito.when()
        ├── verifyGenerateText → Mockito.verify()
        └── capturePrompt → ArgumentCaptor

With Spring AI

FakeEmbeddingModel implements EmbeddingModel
    │
    └── Compatible with Spring AI APIs
        ├── VectorStore
        ├── EmbeddingClient
        └── DocumentTransformer

FakeAiConfiguration provides EmbeddingService
    │
    └── Uses SpringAiEmbeddingService
        └── Wraps FakeEmbeddingModel

Layered Architecture

Test Layer

Your Test Class
    ├── extends EmbabelMockitoIntegrationTest
    ├── imports FakeAiConfiguration
    └── uses FakeEmbeddingModel directly

Purpose: Write tests for agent applications

Test Support Layer

embabel-agent-test-support modules
    ├── Stubbing/Verification helpers
    ├── Fake implementations
    └── Spring configuration

Purpose: Provide testing infrastructure

Agent Framework Layer

embabel-agent-api, embabel-agent-common, embabel-agent-domain
    ├── LlmOperations interface
    ├── AgentPlatform
    └── Domain types

Purpose: Core agent functionality

Spring AI Layer

Spring AI framework
    ├── EmbeddingModel interface
    ├── ChatModel interface
    └── Spring AI types

Purpose: AI service abstractions

Module Selection Guide

Decision Tree

What do you need to test?

├── LLM text generation or object creation?
│   └── Use: embabel-agent-test
│       └── Extend EmbabelMockitoIntegrationTest
│
├── Embedding operations?
│   └── Use: embabel-agent-test-common
│       └── Create FakeEmbeddingModel
│
├── Spring components with AI services?
│   └── Use: embabel-agent-test-internal
│       └── @Import(FakeAiConfiguration::class)
│
└── All of the above?
    └── Use: All three modules together
        ├── Extend EmbabelMockitoIntegrationTest
        └── @Import(FakeAiConfiguration::class)

Testing Strategies

Strategy 1: Pure Mockito

embabel-agent-test only
    │
    └── For: Unit/integration tests of agent logic
        ├── Mock LLM calls
        ├── Verify interactions
        └── No Spring context needed (optional)

Strategy 2: Pure Fakes

embabel-agent-test-common only
    │
    └── For: Embedding pipeline tests
        ├── Use FakeEmbeddingModel
        ├── Test storage/retrieval
        └── No mocking needed

Strategy 3: Spring Integration

embabel-agent-test-internal only
    │
    └── For: Spring component tests
        ├── Inject fake beans
        ├── Test service integration
        └── Full Spring context

Strategy 4: Complete Testing

All three modules
    │
    └── For: Comprehensive agent tests
        ├── Mock LLM (embabel-agent-test)
        ├── Fake embeddings (embabel-agent-test-common)
        └── Spring context (embabel-agent-test-internal)

Design Principles

1. Independence

Each module can be used independently:

embabel-agent-test: Standalone Mockito support
embabel-agent-test-common: Standalone fake implementations
embabel-agent-test-internal: Ties them together for Spring

2. Composability

Modules work together seamlessly:

Combine Mockito stubs with fake embeddings
Use Spring beans with Mockito mocks
Mix and match based on needs

3. Framework Compatibility

Built on standard frameworks:

Spring Boot Test for test infrastructure
Mockito for mocking (Java standard)
Spring AI for embedding interfaces
JUnit 5 for test execution

4. No API Calls

All modules avoid real API calls:

Mockito intercepts LLM calls
FakeEmbeddingModel generates locally
No network dependencies

5. Fast Execution

Optimized for speed:

In-memory operations only
No I/O or network
Instant test execution

Extension Points

Custom Converters

Extend OptionsConverterTestSupport:

class MyConverterTest : OptionsConverterTestSupport<MyOptions>(
    MyOptionsConverter()
) {
    // Add custom tests
}

Custom Beans

Override FakeAiConfiguration beans:

@TestConfiguration
class CustomConfig {
    @Bean
    @Primary
    fun customEmbedding(): EmbeddingService {
        // Custom implementation
    }
}

Custom Predicates

Create reusable predicates:

public class TestPredicates {
    public static final Predicate<String> CONTAINS_ANALYZE =
        p -> p.contains("analyze");

    public static final Predicate<String> LONG_PROMPT =
        p -> p.length() > 100;
}

Performance Characteristics

Operation Speeds

Operation	Speed	Notes
Stub setup	Instant	In-memory Mockito configuration
LLM mock call	Instant	No network, returns stub
Fake embedding	< 1ms	Simple random generation
Spring context load	1-3s	One-time per test class
Verification	Instant	Memory lookup

Scalability

Test Execution: Thousands of tests per minute
Batch Embeddings: 10,000+ embeddings per second
Mock Interactions: Unlimited stubbing/verification
Spring Context: Reused across tests in same class