网测试模式

安全 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时使用此技能

在以下情况下使用此技能: 为 Akka.NET Actor 编写单元测试 通过事件源测试持久 Actor 验证 Actor 交互和消息流 测试 Actor 监督和生命周期

参考文件

example.md:所有测试模式的完整代码示例(模式 1-8 加提醒) anti-patterns-and-reference.md:反模式、传统 TestKit、CI/CD 集成

使用 Akka.Hosting.TestKit(推荐用于 95% 的用例)

何时:使用 Microsoft.Extensions.DependencyInjection 构建现代 .NET 应用程序 在生产中使用 Akka.Hosting 进行 Actor 配置 需要将服务注入到 Actor 中(IOptions、DbContext、ILogger、HTTP 客户端等) 测试使用 ASP.NET Core、Worker Services 或 .NET Aspire 的应用程序

使用传统的 Akka.TestKit

时间:为 Akka.NET 核心库开发做出贡献 在没有 Microsoft.Extensions 的环境中工作(控制台应用程序、遗留系统) 使用手动 Props 创建的遗留代码库,无需 DI 请参阅 anti-patterns-and-reference.md 了解传统 TestKit 模式。

核心原理(Akka.Hosting.TestKit)

继承自 Akka.Hosting.TestKit.TestKit - 这是一个框架基类,而不是用户定义的类 覆盖 ConfigureServices() - 用假冒/模拟替换真实服务 覆盖 ConfigureAkka() - 使用与生产相同的扩展方法配置参与者 使用 ActorRegistry - 参与者引用的类型安全检索 继承之上的组合 - 将假服务作为字段,而不是基类

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
安全
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@Aaronontheweb · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
Linux
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) 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](examples.md): Complete code samples for all testing patterns (Patterns 1-8 plus Reminders)
- [anti-patterns-and-reference.md](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](anti-patterns-and-reference.md) for traditional TestKit patterns.

---

## Core Principles (Akka.Hosting.TestKit)

1. **Inherit from `Akka.Hosting.TestKit.TestKit`** - This is a framework base class, not a user-defined one
2. **Override `ConfigureServices()`** - Replace real services with fakes/mocks
3. **Override `ConfigureAkka()`** - Configure actors using the same extension methods as production
4. **Use `ActorRegistry`** - Type-safe retrieval of actor references
5. **Composition over Inheritance** - Fake services as fields, not base classes
6. **No Custom Base Classes** - Use method overrides, not inheritance hierarchies
7. **Test One Actor at a Time** - Use TestProbes for dependencies
8. **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](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

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.

```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

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

---

## Debugging Tips

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

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

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。