Skip to content

Add ControlledTestKit for simulated-time actor tests#45

Open
nb-ceffa wants to merge 1 commit into
cloudmark:mainfrom
nb-ceffa:introduce-ControlledTestKit
Open

Add ControlledTestKit for simulated-time actor tests#45
nb-ceffa wants to merge 1 commit into
cloudmark:mainfrom
nb-ceffa:introduce-ControlledTestKit

Conversation

@nb-ceffa

Copy link
Copy Markdown

Summary

Adds a new cross-platform cats-actors-testkit module that lets you test actors under simulated time using Cats Effect's TestControl. Time-dependent behaviour (schedulers, receive timeouts,
retries) can be tested deterministically and instantly — no real-world sleeps, no flaky timing thresholds. Also includes a few quality-of-life improvements to the existing TestKit.

Motivation

Actor tests that involve delays currently have to sleep in real time, which makes suites slow and timing-sensitive. Cats Effect provides TestControl to drive an IO program over a simulated clock,
but wiring an ActorSystem into it correctly (execute → tick → interpret outcome) is fiddly boilerplate. This PR packages that pattern into a reusable, framework-agnostic helper.

What's included

  • ControlledTestKit — a trait (extending TestKit) exposing withActorSystemIO, which:
    • provisions an ActorSystem[IO],
    • runs your test body inside TestControl,
    • advances the simulated clock (testTimeWindow, default 90s),
    • and interprets the outcome.
  • ControlledTestException — a small sealed hierarchy (Canceled, TimedOut(window)) for the non-success outcomes that don't originate from the test logic itself.
  • TestKit improvements (existing module):
    • new expectMsgTypeSingle / expectMsgTypeCountN helpers (count-based, snapshot-independent message-type assertions),
    • the failing-expectMsg path now logs the current queue state to aid debugging,
    • extended Scaladoc on expectMsgType documenting the snapshot/splitAt race that can make it flaky, with a pointer to the more robust count-based helpers.
  • Build wiring — new testkit cross-project (JVM / JS / Native), aggregated under root.
  • README — a new "Testing Actors" section with a runnable example.

Backward compatibility

Fully additive. The only change to existing code is in TestKit (new methods + extra logging + Scaladoc); no signatures changed and no behaviour removed.

Introduce a cross-platform cats-actors-testkit module built on Cats Effect
TestControl. withActorSystemIO runs test logic under simulated time.

Also extend the existing TestKit:
- add expectMsgTypeSingle / expectMsgTypeCountN helpers
- log the queue state when an expectMsg assertion fails
- document the snapshot/splitAt race that makes expectMsgType flaky
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant