Unit testing

Unit testing in Akka exercises one component at a time. Every component ships with a matching TestKit. The pattern is the same for every component: create the TestKit, invoke the component, assert on the emitted effect or resulting state.

The shortest possible unit test

class CounterTest {

  @Test
  void incrementsFromZero() {
    var testKit = EventSourcedTestKit.of(Counter::new);

    var result = testKit.method(Counter::increment).invoke();

    assertThat(result.getReply()).isEqualTo(1);
    assertThat(testKit.getState()).isEqualTo(1);
  }
}

TestKit by component

The table lists every component and the TestKit facility to use. Each entry links to the deterministic-testing section on that component’s own page.

Component What the TestKit gives you Documentation

Agent

TestModelProvider for deterministic model replies; whenMessage and whenToolResult shaping.

Testing the agent

Autonomous agent

TestKitSupport with autonomous-agent bootstrap and controllable task lifecycle.

Testing

Event Sourced Entity

EventSourcedTestKit. Apply commands, assert on emitted events and next state.

sdk:event-sourced-entities.adoc#_testing_the_entity

Key Value Entity

KeyValueEntityTestKit. Apply commands, assert on state transitions.

sdk:key-value-entities.adoc#_testing_the_entity

Workflow

WorkflowTestKit. Drive step by step, assert on deterministic step results.

Implementing Workflows

Timer

A virtual clock the test advances; assert on scheduled firings.

Timers

Consumer

Feed events through the consumer; assert on side-effects.

Consuming and producing

HTTP endpoint

Deployable in-process runtime; call over HTTP with the injected client.

Designing HTTP Endpoints

gRPC endpoint

Deployable in-process runtime; call over gRPC with the injected client.

Designing gRPC Endpoints

MCP endpoint

Deployable in-process runtime; call over MCP with the injected client.

Designing MCP Endpoints

View

Feed source events, query the view, assert on rows.

Implementing Views

Best practices

  • Extend TestKitSupport once per test class.

  • Register a TestModelProvider for every agent under test.

  • Assert on effects and state, not on log output.

  • Reset the TestKit between tests when the component holds durable state.

  • Keep unit tests under 100 ms. Move anything longer to integration.

  • Use a separate TestModelProvider instance per agent when multiple agents share a test.

Related