Testing
A module is tested in its directory with rudder module test: no build, no server, no
database. Generation writes a test client into rudder_gen_test.go, and rudder runs the
module in memory with the same rules for its fields as Rudder.
rudder module test # generate, then go test ./...rudder module test -v -run TestDonate # flags go to go testrudder module test --json # the events of go test -json, for tools and agentsA failed test exits with 1; with --json the events are followed by
{"error": {"code": "tests_failed", ...}}. Plain go test ./... and your editor work too,
through the go.work the CLI writes, with rudder on your PATH.
func TestDonate(t *testing.T) { game := NewGame(t) game.Assets("gold") settings.Put(game, Settings{Energy: rudder.RegenRule{Every: 300, Max: 5}, Limit: 1})
game.As("ann") game.Player().Wallet().Credit("gold", 100)
if _, err := game.Join(JoinArguments{Clan: "wolves"}); err != nil { t.Fatal(err) }
if _, err := game.Donate(DonateArguments{Gold: 30}); err != nil { t.Fatal(err) }
game.As("bob")
if _, err := game.Join(JoinArguments{Clan: "bears"}); !errors.Is(err, ErrLimit) { t.Fatalf("join: %v, want ErrLimit", err) }
if treasury := game.Project().Clans.Get("wolves").Treasury.Get(); treasury != 30 { t.Fatalf("treasury %d, want 30", treasury) }}The test client
Section titled “The test client”| Meaning | |
|---|---|
NewGame(t) | A test with one player, no catalog rows, and the clock at 2026-01-05 12:00 UTC. |
game.<Function>(arguments) | Calls a function as a client would. |
game.On<Event>(payload) | Calls an event handler, as the delivery of an event would. |
game.As("bob") | Switches the player. Every player has its own data and timers; all share the shared data. |
game.Player() | The player type of the current player, to prepare or check its data outside a call. |
game.Project() | The shared type. |
game.Advance(duration) | Moves the clock and runs the timers that came due, each at its own time. |
game.Assets("gems", "gold") | The currencies of the project. Without it any currency is accepted. |
game.DayStart(3 * time.Hour) | Moves the start of the day of the project. |
<catalog>.Put(game, rows...) | Puts rows into a catalog, checked by the rules of a release. A single catalog takes one row. |
The names Game, NewGame and a function named Test, Player or, with a shared type,
Project are taken by the client.
What a test shows
Section titled “What a test shows”- A call goes the way a call of a release goes: arguments and results pass through JSON, an
error takes back everything the call did, a query cannot write.
errors.Is(err, ErrLimit)matches a module error. - An operation outside the rules fails the test with its reason: a write in a query, a value over 16 KB, more than 1000 operations, a call of a required module without a stub.
- Counters with a period, catalog windows and timers follow the clock of the test.
Events
Section titled “Events”sent := rudder.TestEmitted(game.Test, purchased) // emitted to the players of callskicks := rudder.TestEmittedTo(game.Test, kicked, "bob") // sent to one player with EmitToAn event is not delivered in a test: call the handler yourself with game.On<Event>.
Required modules
Section titled “Required modules”A required module does not run in a test. Its package has a stub for each exported function:
quests.StubReport(game.Test, func(progress quests.Progress) (quests.Reported, error) { return quests.Reported{Completed: []string{}}, nil})A stub returns a result or a module error (quests.ErrUnknownMetric); it changes no data.
What a test does not show
Section titled “What a test does not show”- Package-level variables keep their values between calls in a test; a release starts each call fresh.
- Arguments are not checked against their schemas; the Go types carry the shape.
- The limits of time and memory, idempotency keys, and the retries of failed handlers.
- Tests of a package run one at a time: no
t.Parallel.