Akka TestKit

As explained in Akka in Action, Second Edition

ActorTestKit is an Akka testing utility that provides an actor test environment, including facilities for creating actors and test probes.

ActorTestKit is the asynchronous testing environment for actor behavior that must run with a real ActorSystem. It supports black-box tests: send messages to actors, observe their externally visible effects, and account for parallel execution and nondeterministic delivery order. This makes it suitable for scheduled messages and asynchronous calls that isolated, stubbed testing cannot exercise. section 4.1 section 4.3

Figure 4.2 Testing components of the ActorTestKit

A typical test creates a real ActorSystem containing the actor under test and a probe that monitors eventual message effects. section 4.3

Test a forwarded message

Create one ActorTestKit for the test suite, spawn the actor with testKit.spawn, and create a typed probe with testKit.createTestProbe. Send the actor a command containing probe.ref, then use probe.expectMessage to assert the forwarded value. Shut down the test kit after all tests so its ActorSystem is terminated; reusing it avoids repeatedly creating an ActorSystem. section 4.3.1 section 4.3.1

Use probes to observe actor communication without exposing actor internals:

• Pass a probe reference as the recipient of a reply or forwarded message, then assert with expectMessage. section 4.3.1
• Wrap a behavior with Behaviors.monitor(probe.ref, behavior) when every message sent to a real actor should also be visible to the probe. section 4.3.1
• Treat monitoring as useful for message cascades, where a command triggers further messages and the resulting stream must be checked. section 4.3.1

Because messages can arrive in an undetermined order, assertions may need to wait rather than assume an immediate sequence. ActorTestKit probe APIs include awaiting assertions, running code within a time limit, and fishing for messages of selected types. section 4.3

Fish for a timer-driven resume

For a counter that pauses and later receives Resume through a single timer, monitor the counter with a probe and send Pause(1). Fish for up to three seconds. Ignore observed Increase and Pause messages, and complete when Resume arrives. A fishing strategy must decide how to handle every encountered message: retain and complete, retain and continue, discard and continue, or fail after disregarding prior catches. section 4.3.2 section 4.3.2

ScalaTestWithActorTestKit can supply the test kit implicitly, letting tests call spawn and createTestProbe directly while avoiding manual creation and termination. Successful-test logging can be muted with CapturingAppender; LogCapturing and CapturingAppenderDelegate restore captured logs when a test fails. section 4.3.2 section 4.4

ActorTestKit loads application-test.conf when present, otherwise follows the normal configuration fallback. A ConfigFactory.parseString configuration can override properties directly or be combined with the default configuration through withFallback. section 7.4 section 7.4

How Akka in Action, Second Edition covers it

How deep it goes

Explains spawning, probes, monitoring, timed fishing, lifecycle management, logging, and test configuration; defers cluster testing.

Examples

Demonstrates forwarding through SimplifiedManager and fishing for a Resume message from a paused timer-driven counter.

What it assumes

Builds from basic actor message testing while distinguishing synchronous isolated testing from real-system asynchronous testing.

What you can do after

Apply it to spawn actors, observe messages with probes, test asynchronous effects, and configure or manage test ActorSystems.

How it connects

Connects ActorTestKit with ActorSystem, TestProbe, BehaviorTestKit, TestInbox, Behaviors.monitor, ScalaTestWithActorTestKit, and ConfigFactory.

liveBookmanning.com

Read Akka in Action, Second Edition on liveBook Get the book at manning.com

Related concepts

• BehaviorTestKitcontrasts with · BehaviorTestKit is an Akka Typed testing utility that runs actor behavior under test and exposes generated effects, messages, and log output for inspection.
• ActorSystemuses · An Akka ActorSystem is the runtime container and entry point for creating and managing actors, their execution, and lifecycle.
• actoruses · An actor is an independent entity or participant that performs actions, maintains or pursues state or goals, and interacts with other entities or systems.
• TestProbeuses · TestProbe is an Akka Typed test utility that receives messages from actors and provides operations for inspecting and asserting them.

This explainer was generated by Manning's knowledge graph from the text of Akka in Action, Second Edition. The section links point to the parts of the book it draws on.