Write unit and integration tests for Akka.NET actors using modern Akka.Hosting.TestKit patterns. Covers dependency injection, TestProbes, persistence testing, and actor interaction verification. Includes guidance on when to use traditional TestKit.
SKILL.md
Akka.NET Testing Patterns
When to Use This Skill
Use this skill when:
Writing unit tests for Akka.NET actors
Testing persistent actors with event sourcing
Verifying actor interactions and message flows
Testing actor supervision and lifecycle
Mocking external dependencies in actor tests
Testing cluster sharding behavior locally
Verifying actor state recovery and persistence
Reference Files
examples.md: Complete code samples for all testing patterns (Patterns 1-8 plus Reminders)
Akka.Hosting.TestKit spins up real IHost instances, which by default enable file watchers for configuration reload. When running many tests, this exhausts file descriptor limits on Linux (inotify watch limit).
Add this to your test project - it runs before any tests execute:
// TestEnvironmentInitializer.cs
using System.Runtime.CompilerServices;
namespace YourApp.Tests;
internal static class TestEnvironmentInitializer
{
[ModuleInitializer]
internal static void Initialize()
{
// Disable config file watching in test hosts
// Prevents file descriptor exhaustion (inotify watch limit) on Linux
Environment.SetEnvironmentVariable("DOTNET_HOSTBUILDER__RELOADCONFIGONCHANGE", "false");
}
}
Why this matters:
[ModuleInitializer] runs automatically before any test code
Sets the environment variable globally for all IHost instances
Prevents cryptic inotify errors when running 100+ tests
Also applies to Aspire integration tests that use IHost
Testing Patterns Overview
Each pattern below has a condensed description. See examples.md for complete code samples.
Pattern 1: Basic Actor Test
The foundation pattern. Override ConfigureServices() to inject fakes, override ConfigureAkka() to register actors with the same extension methods as production.
Register a TestProbe in the ActorRegistry as a stand-in for a dependency actor. Use ExpectMsgAsync<T>() to verify messages were sent.
Pattern 3: Auto-Responding TestProbe
When the actor under test uses Ask to communicate with dependencies, create an auto-responder actor that forwards messages to a probe AND replies to avoid timeouts.
Pattern 4: Testing Persistent Actors
Use WithInMemoryJournal() and WithInMemorySnapshotStore(). Test recovery by killing the actor with PoisonPill and querying to force recovery from journal.
Pattern 5: Reuse Production Configuration
Always reuse production extension methods in tests instead of duplicating HOCON config. This ensures tests use the exact same configuration as production.
protected override void ConfigureAkka(AkkaConfigurationBuilder builder, IServiceProvider provider)
{
builder
.AddDraftSerializer() // Same as production
.AddOrderDomainActors(AkkaExecutionMode.LocalTest) // Same, but local mode
.WithInMemoryJournal().WithInMemorySnapshotStore(); // Test-specific overrides
}
Pattern 6: Cluster Sharding Locally
Use AkkaExecutionMode.LocalTest with GenericChildPerEntityParent to test sharding behavior without an actual cluster. Same extension methods, different mode.
Pattern 7: AwaitAssertAsync for Async Operations
Use AwaitAssertAsync when actors perform async operations. It retries assertions until they pass or timeout, preventing flaky tests.
