Testkit

GoAkt comes packaged with a testkit that can help test that actors receive expected messages within unit tests. The testkit in GoAkt uses underneath the https://github.com/stretchr/testify package. To test that an actor receive and respond to messages one will have to:

1. Create an instance of the testkit: testkit := New(ctx, t) where ctx is a go context and t the instance of *testing.T. This can be done in setup before the run of each test.

2. Create the instance of the actor under test. Example:testkit.Spawn(ctx, "pinger", &pinger{})

3. Create an instance of test probe: probe := testkit.NewProbe(ctx) where ctx is a go context. One can set some options

4. Use the probe to send a message to the actor under test. Example:probe.Send("pinger", new(testpb.Ping)) for a Tell assertion and probe.SendSync("pinger", new(testpb.Ping), time.Second) for an Ask assertion.

5. Assert that the actor under test has received the message and responded as expected using the Probe methods:

// exactly matches the given protobuf message.
// It fails the test if no message is received or the message does not match.
ExpectMessage(message proto.Message)

// ExpectMessageWithin asserts that the expected message is received within the given duration.
// It fails the test if the timeout is reached or the message differs.
ExpectMessageWithin(duration time.Duration, message proto.Message)

// ExpectNoMessage asserts that no message is received within a short, default time window.
// This is useful for asserting inactivity or idle actors.
ExpectNoMessage()

// ExpectAnyMessage waits for and returns the next message received by the probe.
// It fails the test if no message is received in a reasonable default timeout.
ExpectAnyMessage() proto.Message

// ExpectAnyMessageWithin waits for and returns the next message received within the specified duration.
// It fails the test if no message is received in the given time window.
ExpectAnyMessageWithin(duration time.Duration) proto.Message

// ExpectMessageOfType asserts that the next received message matches the given message type.
// It fails the test if no message is received or the type does not match.
ExpectMessageOfType(messageType protoreflect.MessageType)

// ExpectMessageOfTypeWithin asserts that a message of the given type is received within the specified duration.
// It fails the test if the type does not match or if the timeout is reached.
ExpectMessageOfTypeWithin(duration time.Duration, messageType protoreflect.MessageType)

// ExpectTerminated asserts that the actor with the specified name has terminated.
// This is useful when verifying actor shutdown behavior.
ExpectTerminated(actorName string)

1. Make sure to shut down the testkit and the probe. Example: probe.Stop(), testkit.Shutdown(ctx) where ctx is a go context. These two calls can be in a tear down after all tests run.

To help implement unit tests in applications. See Testkit

Note

The current implementation of the Testkit does not support clustering, extensions, or dependency injection out of the box. However, with some creative adaptation, it can still be used effectively for specific use cases. Future enhancements may extend its capabilities in these areas.