dotnet-skills Akka.NET 系列（二）：TestProbe 与 Akka.Hosting.TestKit 测试模式完全教程

Actor 测试总是又慢又"飘"？这篇文章带你系统掌握TestProbe和Akka.Hosting.TestKit—— dotnet-skills 开源项目中总结的现代 Akka.NET 测试模式。通过 8 个生产级实战模式（skills/akka-testing-patterns/ 技能文档），你将学会用依赖注入替换真实服务、用 TestProbe 拦截 Actor 消息、用内存存储测试事件溯源，彻底告别 Sleep 等待和 Flaky 测试。

为什么 Akka.NET Actor 测试这么难写？

Actor 是异步的、消息驱动的：

• 你发一条命令，Actor 可能立刻响应，也可能 100ms 后才发出一条内部消息——Thread.Sleep式的断言注定不稳定；
• Actor 之间通过消息通信，"它到底有没有给 PaymentActor 发过消息"很难直接验证；
• 持久化 Actor、Cluster Sharding 等高级特性依赖基础设施，单测环境里根本起不来。

dotnet-skills 项目给出的答案是：用 Akka.Hosting.TestKit 统一测试框架 + TestProbe 消息拦截器，95% 的场景都适用。

系列（一）讲过 Akka.NET 最佳实践（EventStream、监督策略等），见 skills/akka-best-practices/SKILL.md。本篇聚焦"怎么测"。

选型指南：Akka.Hosting.TestKit vs 传统 Akka.TestKit

dotnet-skills 的技能文档明确建议：优先使用 Akka.Hosting.TestKit（skills/akka-testing-patterns/SKILL.md）。两者核心差异一目了然：

三个关键动作，构成所有测试的骨架：

1. 继承Akka.Hosting.TestKit.TestKit基类（这是框架类，不是让你自定义基类）；
2. 重写ConfigureServices()—— 把真实服务替换成 fake 实现（Fake 优于 Mock，更简单可维护）；
3. 重写ConfigureAkka()—— 用和生产完全相同的扩展方法注册 Actor，只是执行模式不同。

完整代码可参考 skills/akka-testing-patterns/examples.md。

模式一：基础 Actor 测试（依赖注入）

最基础的套路：注册 fake 服务 → 注册被测 Actor → 用Ask发命令并断言。

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

注意两点：fake 服务以字段形式持有（组合优于继承）；ConfigureServices先于ConfigureAkka执行，服务对 Actor 可见。

TestProbe 测试模式：验证 Actor 间消息投递

TestProbe 本质是一个"消息拦截器"——它可以伪装成任意依赖 Actor 注册进 Actor 系统，接收被测 Actor 发出的所有消息，再用断言方法逐一验证。

核心用法三步走（examples.md Pattern 2）：

protected override void ConfigureAkka(AkkaConfigurationBuilder builder, IServiceProvider provider) { _paymentProbe = CreateTestProbe("payment-probe"); registry.Register<PaymentActor>(_paymentProbe); // Probe 顶替 PaymentActor var invoiceActor = system.ActorOf(resolver.Props<InvoiceActor>(), "invoice-actor"); registry.Register<InvoiceActor>(invoiceActor); // 被测 Actor } [Fact] public async Task CreateInvoice_Success_SendsPaymentRequest() { var invoiceActor = ActorRegistry.Get<InvoiceActor>(); await invoiceActor.Ask<InvoiceCommandResult>( new CreateInvoice(InvoiceId: "INV-001", Amount: 100.00m), RemainingOrDefault); // 断言：PaymentActor 确实收到了开票请求 var paymentRequest = await PaymentProbe.ExpectMsgAsync<InitiatePayment>(TimeSpan.FromSeconds(3)); paymentRequest.InvoiceId.Should().Be("INV-001"); }

ExpectMsgAsync<T>()会阻塞等待直到匹配的消息到达（或超时），比轮询状态可靠得多。测试时还可以直接检查probe.Messages查看全部已收到的消息。

如何避免 Ask 超时：Auto-Responding TestProbe

坑点：如果被测 Actor 用Ask（请求-响应模式）与依赖 Actor 通信，而 TestProbe 默认只收不回，Ask就会超时。

解决方案是"自动应答 Actor"：写一个薄薄的ReceiveActor，把消息转发给 TestProbe 做断言，同时立即回一条响应防止超时（examples.md Pattern 3）：

internal sealed class PaymentAutoResponder : ReceiveActor { private readonly IActorRef _probe; public PaymentAutoResponder(IActorRef probe) { _probe = probe; Receive<InitiatePayment>(msg => { _probe.Tell(msg, Sender); // 转发给 Probe 验证 Sender.Tell(new PaymentStarted(...), Self); // 自动应答防超时 }); ReceiveAny(msg => _probe.Tell(msg, Sender)); // 其余消息直接转发 } }

持久化 Actor 测试：内存存储验证事件溯源与状态恢复

测持久化 Actor 不需要真数据库——WithInMemoryJournal()+WithInMemorySnapshotStore()即可在内存中记录事件（examples.md Pattern 4）。

经典恢复测试思路：

1. 创建订单，触发事件持久化；
2. 用PoisonPill杀死 Actor，模拟被动化（passivation）；
3. 再次查询状态——Actor 会强制从 Journal 恢复，断言数据完整无误。

这条"杀死再查询"的路径，能真实验证你的事件溯源实现是否可恢复。

复用生产配置：避免重复 HOCON 配置

技能文档反复强调一条铁律：测试中永远复用生产代码的扩展方法，而不是复制一份 HOCON 配置。

• ❌ 反模式：在测试里ConfigurationFactory.ParseString(...)手抄序列化绑定——改一处要改两处，测试通过但生产失败的情况屡见不鲜；
• ✅ 正确姿势：测试与生产调用同一个AddDraftSerializer()、AddOrderDomainActors(...)，仅追加测试专属覆盖：

builder .AddDraftSerializer() // 与生产相同 .AddOrderDomainActors(AkkaExecutionMode.LocalTest) // 换成本地测试模式 .WithInMemoryJournal().WithInMemorySnapshotStore(); // 仅测试覆盖

AkkaExecutionMode.LocalTest与Clustered的切换机制详见 skills/akka-hosting-actor-patterns/SKILL.md——同一套 Actor 代码，测试时本地跑、生产时上集群。

不搭真实集群，本地测试 Cluster Sharding

配合GenericChildPerEntityParent（一个按 EntityId 路由到子 Actor 的轻量父 Actor），LocalTest模式可以完整模拟 Sharding 路由语义（examples.md Pattern 6）：

• 生产分支用WithShardRegion<OrderActor>(...)走 ShardRegion；
• 测试分支用GenericChildPerEntityParent按实体 ID 路由到子 Actor。

于是你可以直接验证"两条不同 EntityId 的消息落到两个独立实体"这类 Sharding 行为，无需起一个真正的集群。

AwaitAssertAsync：告别 Flaky 测试的关键

Actor 执行异步操作（调外部服务、同步读模型）时，断言必须"重试到通过为止"，这正是AwaitAssertAsync的职责：

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

它会在超时前持续重试断言，是消除时序性 Flaky 测试的首选工具（examples.md Pattern 7）。

场景式集成测试：端到端验证业务工作流

单个 Actor 测试之外，还需要覆盖完整业务流。技能文档建议"一个场景一个测试方法"，命名带Scenario_前缀，例如Scenario_FirstTimePurchase_SuccessfulPayment（examples.md Pattern 8）：

• 一次性注册订阅、发票、支付等全部领域 Actor（LocalTest模式）；
• 按步骤推进：创建订阅 → 验证发票生成 → 模拟支付成功 → 验证订阅激活；
• 每个异步节点用AwaitAssertAsync兜底，保证步骤间的时序鲁棒。

Akka.NET 测试常见反模式清单

来自 anti-patterns-and-reference.md 的三大禁忌：

另外两个细节：fake 服务保持"可注入故障"（如FailNextSave = true），才能覆盖错误分支；测试命名用场景_条件_预期三段式，可读性拉满。

测试项目必做配置：Linux 下 inotify 文件描述符问题

⚠️ 这是最容易踩的坑：Akka.Hosting.TestKit 会启动真实的IHost，而 Host 默认开启配置热加载的文件监视。在 Linux 上跑 100+ 个测试时，会耗尽 inotify watch 限额，报出令人困惑的 inotify 错误。

修复方法：在测试项目中放一个[ModuleInitializer]类，在任何测试执行前设置环境变量：

internal static class TestEnvironmentInitializer { [ModuleInitializer] internal static void Initialize() { Environment.SetEnvironmentVariable("DOTNET_HOSTBUILDER__RELOADCONFIGONCHANGE", "false"); } }

[ModuleInitializer]自动在任何测试代码之前运行，对所有IHost实例全局生效。

必备 NuGet 包清单

调试技巧速查

1. 开 Debug 日志：构造函数传logLevel: LogLevel.Debug；
2. 查看 Actor 系统日志：用ITestOutputHelper把日志输出到测试面板；
3. 检查 TestProbe：直接读probe.Messages看对方发了什么；
4. 给 Actor 加状态查询消息：调试时随时Ask当前状态；
5. AwaitAssertAsync内加日志：看清断言为何失败。

延伸阅读：dotnet-skills 项目资料

• 完整 8 大模式代码示例：skills/akka-testing-patterns/examples.md
• 反模式、传统 TestKit 写法与 CI/CD 集成：skills/akka-testing-patterns/anti-patterns-and-reference.md
• 技能入口与最佳实践总表：skills/akka-testing-patterns/SKILL.md
• LocalTest/Clustered 双模式 Actor 设计：skills/akka-hosting-actor-patterns/SKILL.md
• Akka.NET 专项调试 Agent：agents/akka-net-specialist.md

掌握 TestProbe 与 Akka.Hosting.TestKit 后，你的 Akka.NET 测试将做到：不 Sleep、不连真库、不起真集群、不 Flaky——这正是 dotnet-skills 从 Petabridge 等生产系统沉淀出的测试纪律。