How meamidos/gopactor works
Project Type and Purpose
• Type: A Go testing library for actor systems
• Purpose:
– Provide assertion functions (e.g., ShouldReceive, ShouldSendTo) for actors built with ProtoActor
– Intercept inbound, outbound & system messages
File Structure
Top-level packages:
• assertions/… — assertion helper functions
• catcher/… — core interception logic, middleware & context wrappers
• gopactor/… — high-level API: SpawnFromInstance, SpawnNullActor, singleton management
• options/… — configuration options and builder methods
• root files (options.go, should.go, spawn_test.go, etc.) tie packages together and define public API
README for Additional Insights
• Integrates with ProtoActor (github.com/AsynkronIT/protoactor-go)
• Uses Goconvey for BDD-style test syntax
• Provides adapters for intercepting actor messages and system events
Main Components
a. Test Harness (User’s BDD Test Code)
• Uses Goconvey’s Convey/So functions
• Calls Gopactor API (SpawnFromInstance, SpawnNullActor)
b. Gopactor Library
• High-Level API (package “gopactor”)
• Assertion Layer (package “assertions” + should.go)
• Interception Engine (package “catcher”)
• Middleware chain intercepting actor context
• Context wrapper capturing inbound/outbound messages
• Configuration (package “options”)
c. ProtoActor Runtime
• Actor spawning, mailbox, message dispatching
• System messages (Stop, Restart)
d. Mock/Null Actors
• SpawnNullActor creates no-op actors to replace real children
e. External Test Runner & Libraries
• Go test runner (go test)
• Goconvey for assertion rendering
Relationships and Data Flow
1. Test Harness → Gopactor API
2. Gopactor API uses Options to configure interceptors → Instructs Catcher
3. SpawnFromInstance wraps the real actor’s Context in Catcher middleware
4. Messages from Requestor actor → Sent via ProtoActor → Arrive at Catcher Context
5. Catcher Context captures “inbound” → forwards to real actor
6. Actor .Receive executes → calls ctx.Respond or ctx.Send
7. Catcher Context captures “outbound” → records for assertions → forwards to real ProtoActor mailbox
8. Assertions (ShouldReceive, ShouldSendTo, etc.) query the interceptor’s recorded events
Architectural Patterns & Design Principles
• Decorator/Middleware
– Catcher wraps ProtoActor Context to intercept calls
• Singleton / Global Registry
– gopactor singleton for managing active interceptors
• Fluent Builder
– Options.WithX methods for configuration chaining
• Dependency Inversion
– Test code works against Gopactor interfaces, not directly on ProtoActor