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
Choosing Your Testing Approach
Use Akka.Hosting.TestKit (Recommended for 95% of Use Cases)
When:
- Building modern .NET applications with
Microsoft.Extensions.DependencyInjection
- Using Akka.Hosting for actor configuration in production
- Need to inject services into actors (
IOptions, DbContext, ILogger, HTTP clients, etc.)
- Testing applications that use ASP.NET Core, Worker Services, or .NET Aspire
- Working with modern Akka.NET projects (Akka.NET v1.5+)
Advantages:
- Native dependency injection support - override services with fakes in tests
- Configuration parity with production (same extension methods work in tests)
- Clean separation between actor logic and infrastructure
- Type-safe actor registry for retrieving actors
Use Traditional Akka.TestKit
When:
- Contributing to Akka.NET core library development
- Working in environments without
Microsoft.Extensions (console apps, legacy systems)
- Legacy codebases using manual
Props creation without DI
See anti-patterns-and-reference.md for traditional TestKit patterns.
Core Principles (Akka.Hosting.TestKit)
- Inherit from
Akka.Hosting.TestKit.TestKit - This is a framework base class, not a user-defined one
- Override
ConfigureServices() - Replace real services with fakes/mocks
- Override
ConfigureAkka() - Configure actors using the same extension methods as production
- Use
ActorRegistry - Type-safe retrieval of actor references
- Composition over Inheritance - Fake services as fields, not base classes
- No Custom Base Classes - Use method overrides, not inheritance hierarchies
- Test One Actor at a Time - Use TestProbes for dependencies
- Match Production Patterns - Same extension methods, different
AkkaExecutionMode
Required NuGet Packages
<ItemGroup>
<PackageReference Include="Akka.Hosting.TestKit" Version="*" />
<PackageReference Include="xunit" Version="*" />
<PackageReference Include="xunit.runner.visualstudio" Version="*" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="*" />
<PackageReference Include="FluentAssertions" Version="*" />
<PackageReference Include="Akka.Persistence.Hosting" Version="*" />
<PackageReference Include="Akka.Cluster.Hosting" Version="*" />
</ItemGroup>
CRITICAL: File Watcher Fix for Test Projects
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:
using System.Runtime.CompilerServices;
namespace YourApp.Tests;
internal static class TestEnvironmentInitializer
{
[ModuleInitializer]
internal static void Initialize()
{
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.
public class OrderActorTests : TestKit
{
private readonly FakeOrderRepository _fakeRepository = new();
protected override void ConfigureServices(HostBuilderContext context, IServiceCollection services)
{
services.AddSingleton<IOrderRepository>(_fakeRepository);
}
protected override void ConfigureAkka(AkkaConfigurationBuilder builder, IServiceProvider provider)
{
builder.WithInMemoryJournal().WithInMemorySnapshotStore();
builder.WithActors((system, registry, resolver) =>
{
registry.Register<OrderActor>(system.ActorOf(resolver.Props<OrderActor>(), "order-actor"));
});
}
[Fact]
public async Task CreateOrder_Success_SavesToRepository()
{
var orderActor = ActorRegistry.Get<OrderActor>();
var response = await orderActor.Ask<OrderCommandResult>(
new CreateOrder("ORDER-123", "CUST-456", 99.99m), RemainingOrDefault);
response.Status.Should().Be(CommandStatus.Success);
_fakeRepository.SaveCallCount.Should().Be(1);
}
}
Pattern 2: TestProbe for Actor Interactions
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()
.AddOrderDomainActors(AkkaExecutionMode.LocalTest)
.WithInMemoryJournal().WithInMemorySnapshotStore();
