akka-testing-patterns_skill

Overview

This skill teaches modern patterns for unit and integration testing Akka.NET actors using Akka.Hosting.TestKit. It covers dependency injection, TestProbes, persistence testing, auto-responders, and when to prefer traditional TestKit. The guidance focuses on practical recipes that match production configuration and enable reliable, fast tests.

How this skill works

The approach uses Akka.Hosting.TestKit as a framework base class to spin up IHost-backed test ActorSystems with the same extension methods you use in production. Override ConfigureServices to inject fake dependencies and ConfigureAkka to register actors and test probes. Use ActorRegistry for type-safe retrieval, TestProbe for interaction verification, and in-memory persistence for event-sourced actor tests.

When to use it

• Unit testing individual actors that depend on DI-registered services (IOptions, DbContext, ILogger, HTTP clients).
• Integration tests for persistent actors using in-memory journal and snapshot stores.
• Verifying message flows and actor-to-actor interactions with TestProbe.
• Testing supervision, lifecycle, and state recovery behaviors locally.
• Local cluster sharding experiments where cluster hosting packages are used.

Best practices

• Prefer Akka.Hosting.TestKit for modern .NET projects (production parity and DI support).
• Override ConfigureServices to register fake services as fields (composition, not inheritance).
• Use ActorRegistry.Register/Get<T>() for type-safe lookups instead of hard-coded paths.
• Use TestProbe and auto-responders to avoid Ask timeouts when an actor expects replies.
• Disable host config file watching in tests (DOTNET_HOSTBUILDER__RELOADCONFIGONCHANGE=false) to avoid inotify exhaustion on Linux.
• Test one actor at a time; stub dependencies with probes or fakes to keep tests focused and deterministic.

Example use cases

• Testing OrderActor with a fake repository and fake email service to assert persistence and side effects.
• Using a TestProbe as PaymentActor to verify that InvoiceActor sends InitiatePayment messages and handles PaymentCompleted.
• Running event-sourced actor tests with WithInMemoryJournal and WithInMemorySnapshotStore to validate recovery.
• Creating an auto-responding probe to satisfy Ask calls and assert messages were forwarded to the probe.
• Switching to traditional Akka.TestKit when you need low-level ActorSystem control or work in pre-1.5 codebases.