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)
anti-patterns-and-reference.md: Anti-patterns, traditional TestKit, CI/CD integration

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

xml

<ItemGroup>
  <!-- Core testing framework -->
  <PackageReference Include="Akka.Hosting.TestKit" Version="*" />

  <!-- xUnit (or your preferred test framework) -->
  <PackageReference Include="xunit" Version="*" />
  <PackageReference Include="xunit.runner.visualstudio" Version="*" />
  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="*" />

  <!-- Assertions (recommended) -->
  <PackageReference Include="FluentAssertions" Version="*" />

  <!-- In-memory persistence for testing -->
  <PackageReference Include="Akka.Persistence.Hosting" Version="*" />

  <!-- If testing cluster sharding -->
  <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:

csharp

// 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.

csharp

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

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.

csharp

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.

csharp

await AwaitAssertAsync(() =>
{
    _fakeReadModelService.SyncCallCount.Should().BeGreaterOrEqualTo(1);
}, TimeSpan.FromSeconds(3));

Pattern 8: Scenario-Based Integration Tests

Test complete business workflows end-to-end with multiple actors and state transitions. Register all domain actors, verify state at each step.

Common Patterns Summary

Pattern	Use Case
Basic Actor Test	Single actor with injected services
TestProbe	Verify actor sends messages to dependencies
Auto-Responder	Avoid `Ask` timeouts when testing
Persistent Actor	Test event sourcing and recovery
Cluster Sharding	Test sharding behavior locally
AwaitAssertAsync	Handle async operations in actors
Scenario Tests	End-to-end business workflows

Best Practices

One test class per actor - Keep tests focused
Override ConfigureServices/ConfigureAkka - Don't create base classes
Use fakes, not mocks - Simpler, more maintainable
Test one actor at a time - Use TestProbes for dependencies
Match production patterns - Same extension methods, different
```
AkkaExecutionMode
```
Use AwaitAssertAsync for async - Prevents flaky tests
Test recovery - Kill and restart actors to verify persistence
Scenario tests for workflows - Test complete business flows end-to-end
Keep tests fast - In-memory persistence, no real databases

Use meaningful names -

Scenario_FirstTimePurchase_SuccessfulPayment

Debugging Tips

Enable debug logging - Pass
```
LogLevel.Debug
```
to TestKit constructor
Use ITestOutputHelper - See actor system logs in test output
Inspect TestProbe - Check
```
probe.Messages
```
to see what was sent
Query actor state - Add state query messages for debugging
Use AwaitAssertAsync with logging - See why assertions fail
Check ActorRegistry - Verify actors are registered correctly

csharp

// Constructor with debug logging
public OrderActorTests(ITestOutputHelper output)
    : base(output: output, logLevel: LogLevel.Debug)
{
}

akka-net-testing-patterns

NPX Install

Tags

SKILL.md Content

Akka.NET Testing Patterns

When to Use This Skill

Reference Files

Choosing Your Testing Approach

Use Akka.Hosting.TestKit (Recommended for 95% of Use Cases)

Use Traditional Akka.TestKit

Core Principles (Akka.Hosting.TestKit)

Required NuGet Packages

CRITICAL: File Watcher Fix for Test Projects

Testing Patterns Overview

Pattern 1: Basic Actor Test

Pattern 2: TestProbe for Actor Interactions

Pattern 3: Auto-Responding TestProbe

Pattern 4: Testing Persistent Actors

Pattern 5: Reuse Production Configuration

Pattern 6: Cluster Sharding Locally

Pattern 7: AwaitAssertAsync for Async Operations

Pattern 8: Scenario-Based Integration Tests

Common Patterns Summary

Best Practices

Debugging Tips