akka-net-testing-patterns

Akka.NET-Testmuster

Wann dieses Skill verwenden

Verwenden Sie dieses Skill, wenn:

• Sie Unit-Tests für Akka.NET-Aktoren schreiben
• Sie persistente Aktoren mit Event Sourcing testen
• Sie Aktorinteraktionen und Nachrichtenflüsse überprüfen
• Sie Aktor-Überwachung und Lebenszyklus testen
• Sie externe Abhängigkeiten in Aktortests simulieren
• Sie Cluster-Sharding-Verhalten lokal testen
• Sie die Zustandswiederherstellung und Persistenz von Aktoren überprüfen

Referenzdateien

• examples.md: Vollständige Codebeispiele für alle Testmuster (Muster 1–8 plus Erinnerungen)
• anti-patterns-and-reference.md: Anti-Patterns, traditionelles TestKit, CI/CD-Integration

Auswahl des Testansatzes

Akka.Hosting.TestKit verwenden (Empfohlen für 95% der Anwendungsfälle)

Wann:

• Sie moderne .NET-Anwendungen mit Microsoft.Extensions.DependencyInjection erstellen
• Sie Akka.Hosting für die Aktorkonfiguration in der Produktion verwenden
• Sie Dienste in Aktoren injizieren müssen (IOptions, DbContext, ILogger, HTTP-Clients usw.)
• Sie Anwendungen testen, die ASP.NET Core, Worker Services oder .NET Aspire verwenden
• Sie mit modernen Akka.NET-Projekten arbeiten (Akka.NET v1.5+)

Vorteile:

• Native Dependency Injection-Unterstützung – Überschreiben Sie Dienste in Tests mit Fakes
• Konfigurationsparität mit der Produktion (dieselben Erweiterungsmethoden funktionieren in Tests)
• Saubere Trennung zwischen Aktorlogik und Infrastruktur
• Typsichere Aktorregistrierung zum Abrufen von Aktoren

Traditionelles Akka.TestKit verwenden

Wann:

• Sie zur Entwicklung der Akka.NET-Kernbibliothek beitragen
• Sie in Umgebungen ohne Microsoft.Extensions arbeiten (Konsolenanwendungen, Legacy-Systeme)
• Sie mit Legacy-Codebasen arbeiten, die manuelle Props-Erstellung ohne DI verwenden

Siehe anti-patterns-and-reference.md für traditionelle TestKit-Muster.

---

Kernprinzipien (Akka.Hosting.TestKit)

1. Von Akka.Hosting.TestKit.TestKit erben – Dies ist eine Framework-Basisklasse, keine benutzerdefinierte
2. ConfigureServices() überschreiben – Ersetzen Sie echte Dienste durch Fakes/Mocks
3. ConfigureAkka() überschreiben – Konfigurieren Sie Aktoren mit denselben Erweiterungsmethoden wie in der Produktion
4. ActorRegistry verwenden – Typsicheres Abrufen von Aktorreferenzen
5. Komposition vor Vererbung – Fake-Dienste als Felder, nicht als Basisklassen
6. Keine benutzerdefinierten Basisklassen – Verwenden Sie Methodenüberschreibungen, keine Vererbungshierarchien
7. Einen Aktor nach dem anderen testen – Verwenden Sie TestProbes für Abhängigkeiten
8. Produktionsmuster nachbilden – Gleiche Erweiterungsmethoden, anderer AkkaExecutionMode

---

Erforderliche NuGet-Pakete

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

  <!-- xUnit (oder Ihr bevorzugtes Testframework) -->
  <PackageReference Include="xunit" Version="*" />
  <PackageReference Include="xunit.runner.visualstudio" Version="*" />
  <PackageReference Include="Microsoft.NET.Test.Sdk" Version="*" />

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

  <!-- In-Memory-Persistenz für Tests -->
  <PackageReference Include="Akka.Persistence.Hosting" Version="*" />

  <!-- Falls Cluster-Sharding getestet wird -->
  <PackageReference Include="Akka.Cluster.Hosting" Version="*" />
</ItemGroup>

---

KRITISCH: Dateiüberwacher-Fix für Testprojekte

Akka.Hosting.TestKit startet echte IHost-Instanzen, die standardmäßig Dateiüberwacher für das Neuladen der Konfiguration aktivieren. Wenn viele Tests ausgeführt werden, erschöpft dies die Dateideskriptorgrenzen unter Linux (inotify-Überwachungslimit).

Fügen Sie dies zu Ihrem Testprojekt hinzu – es wird ausgeführt, bevor Tests ausgeführt werden:

// TestEnvironmentInitializer.cs
using System.Runtime.CompilerServices;

namespace YourApp.Tests;

internal static class TestEnvironmentInitializer
{
    [ModuleInitializer]
    internal static void Initialize()
    {
        // Deaktivieren Sie die Konfigurationsdateiüberwachung in Test-Hosts
        // Verhindert die Erschöpfung von Dateideskriptoren (inotify-Überwachungslimit) unter Linux
        Environment.SetEnvironmentVariable("DOTNET_HOSTBUILDER__RELOADCONFIGONCHANGE", "false");
    }
}

Warum das wichtig ist:

• [ModuleInitializer] wird automatisch vor jedem Testcode ausgeführt
• Setzt die Umgebungsvariable global für alle IHost-Instanzen
• Verhindert kryptische inotify-Fehler bei der Ausführung von 100+ Tests
• Gilt auch für Aspire-Integrationstests, die IHost verwenden

---

Übersicht über die Testmuster

Jedes Muster unten enthält eine Kurzbeschreibung. Vollständige Codebeispiele finden Sie in examples.md.

Muster 1: Basis-Aktortest

Das grundlegende Muster. Überschreiben Sie ConfigureServices(), um Fakes zu injizieren, überschreiben Sie ConfigureAkka(), um Aktoren mit denselben Erweiterungsmethoden wie in der Produktion zu registrieren.

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);
    }
}

Muster 2: TestProbe für Aktorinteraktionen

Registrieren Sie eine TestProbe in der ActorRegistry als Stellvertreter für einen Abhängigkeitsaktor. Verwenden Sie ExpectMsgAsync<T>(), um zu überprüfen, ob Nachrichten gesendet wurden.

Muster 3: Automatisch antwortende TestProbe

Wenn der zu testende Aktor Ask zur Kommunikation mit Abhängigkeiten verwendet, erstellen Sie einen automatisch antwortenden Aktor, der Nachrichten an eine Probe weiterleitet UND antwortet, um Timeouts zu vermeiden.

Muster 4: Testen persistenter Aktoren

Verwenden Sie WithInMemoryJournal() und WithInMemorySnapshotStore(). Testen Sie die Wiederherstellung, indem Sie den Aktor mit PoisonPill beenden und abfragen, um die Wiederherstellung aus dem Journal zu erzwingen.

Muster 5: Wiederverwendung der Produktionskonfiguration

Verwenden Sie in Tests immer die Erweiterungsmethoden der Produktion wieder, anstatt HOCON-Konfiguration zu duplizieren. Dadurch wird sichergestellt, dass Tests dieselbe Konfiguration wie die Produktion verwenden.

protected override void ConfigureAkka(AkkaConfigurationBuilder builder, IServiceProvider provider)
{
    builder
        .AddDraftSerializer()                                    // Gleich wie in der Produktion
        .AddOrderDomainActors(AkkaExecutionMode.LocalTest)      // Gleich, aber lokaler Modus
        .WithInMemoryJournal().WithInMemorySnapshotStore();      // Testspezifische Überschreibungen
}

Muster 6: Cluster-Sharding lokal

Verwenden Sie AkkaExecutionMode.LocalTest mit GenericChildPerEntityParent, um Sharding-Verhalten ohne ein echtes Cluster zu testen. Gleiche Erweiterungsmethoden, anderer Modus.

Muster 7: AwaitAssertAsync für asynchrone Vorgänge

Verwenden Sie AwaitAssertAsync, wenn Aktoren asynchrone Vorgänge ausführen. Es wiederholt Assertions, bis sie erfolgreich sind oder ein Timeout eintritt, und vermeidet so flaky Tests.

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

Muster 8: Szenariobasierte Integrationstests

Testen Sie vollständige Geschäftsworkflows Ende-zu-Ende mit mehreren Aktoren und Zustandsübergängen. Registrieren Sie alle Domain-Aktoren und überprüfen Sie den Zustand bei jedem Schritt.

---

Zusammenfassung der gängigen Muster

Muster	Anwendungsfall
Basis-Aktortest	Einzelner Aktor mit injizierten Diensten
TestProbe	Überprüfen, ob ein Aktor Nachrichten an Abhängigkeiten sendet
Auto-Responder	Ask-Timeouts beim Testen vermeiden
Persistenter Aktor	Event Sourcing und Wiederherstellung testen
Cluster-Sharding	Sharding-Verhalten lokal testen
AwaitAssertAsync	Asynchrone Vorgänge in Aktoren behandeln
Szenariotests	Ende-zu-Ende-Geschäftsworkflows

---

Bewährte Verfahren

1. Eine Testklasse pro Aktor – Halten Sie Tests fokussiert
2. ConfigureServices/ConfigureAkka überschreiben – Erstellen Sie keine Basisklassen
3. Fakes, nicht Mocks verwenden – Einfacher und wartbarer
4. Einen Aktor nach dem anderen testen – Verwenden Sie TestProbes für Abhängigkeiten
5. Produktionsmuster nachbilden – Gleiche Erweiterungsmethoden, anderer AkkaExecutionMode
6. AwaitAssertAsync für asynchrone Vorgänge verwenden – Verhindert flaky Tests
7. Wiederherstellung testen – Aktoren beenden und neu starten, um Persistenz zu überprüfen
8. Szenariotests für Workflows – Vollständige Geschäftsabläufe Ende-zu-Ende testen
9. Tests schnell halten – In-Memory-Persistenz, keine echten Datenbanken
10. Aussagekräftige Namen verwenden – Scenario_FirstTimePurchase_SuccessfulPayment

---

Debugging-Tipps

1. Debug-Logging aktivieren – Übergeben Sie LogLevel.Debug an den TestKit-Konstruktor
2. ITestOutputHelper verwenden – Aktorsystem-Logs in der Testausgabe sehen
3. TestProbe inspizieren – Überprüfen Sie probe.Messages, um zu sehen, was gesendet wurde
4. Aktorzustand abfragen – Fügen Sie Zustandsabfragenachrichten zum Debuggen hinzu
5. AwaitAssertAsync mit Logging verwenden – Sehen Sie, warum Assertions fehlschlagen
6. ActorRegistry überprüfen – Stellen Sie sicher, dass Aktoren korrekt registriert sind

// Konstruktor mit Debug-Logging
public OrderActorTests(ITestOutputHelper output)
    : base(output: output, logLevel: LogLevel.Debug)
{
}