Skip to content

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.

Terminal window
rudder module test # generate, then go test ./...
rudder module test -v -run TestDonate # flags go to go test
rudder module test --json # the events of go test -json, for tools and agents

A 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)
}
}
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.

  • 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.
sent := rudder.TestEmitted(game.Test, purchased) // emitted to the players of calls
kicks := rudder.TestEmittedTo(game.Test, kicked, "bob") // sent to one player with EmitTo

An event is not delivered in a test: call the handler yourself with game.On<Event>.

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.

  • 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.