Documentation
¶
Overview ¶
Package testkit provides a testing framework for autoebiten games.
testkit offers two testing modes:
Black-Box Testing (Game): Launches the game in a separate process and controls it via JSON-RPC over Unix sockets. This mode tests the game as a black box, identical to how real users interact with it.
White-Box Testing (Mock): Tests game logic in the same process with mocked inputs. This mode provides fine-grained control over game state and is ideal for unit testing specific behaviors.
Both modes use a similar API for input injection (key presses, mouse movements) and state observation, allowing tests to be written in a mode-agnostic way.
Example black-box test:
func TestPlayerMovement(t *testing.T) {
game := testkit.Launch(t, "./mygame", testkit.WithTimeout(30*time.Second))
defer game.Shutdown()
// Wait for game to be ready
game.WaitFor(func() bool {
err := game.Ping()
return err == nil
}, 5*time.Second)
// Press movement key for 10 ticks
game.HoldKey(ebiten.KeyArrowRight, 10)
// Verify player moved
x, err := game.StateQuery("gamestate", "Player.X")
require.NoError(t, err)
assert.Greater(t, x.(float64), 0.0)
}
Example white-box test:
func TestPlayerMovement(t *testing.T) {
myGame := NewMyGame()
mock := testkit.NewMock(t, myGame)
// Inject key press
mock.InjectKeyPress(ebiten.KeyRight)
// Advance 10 ticks
mock.Ticks(10)
// Verify player moved
assert.Greater(t, myGame.Player.X, 0)
}
State Export:
Games can export internal state using autoebiten.RegisterStateExporter, which enables reflection-based state queries via dot-notation paths like "Player.X" or "Inventory.0.Name":
func init() {
autoebiten.RegisterStateExporter("gamestate", &gameInstance)
}
Index ¶
- Variables
- type Game
- func (g *Game) HoldKey(key ebiten.Key, ticks int64) error
- func (g *Game) MoveMouse(x, y int) error
- func (g *Game) Ping() error
- func (g *Game) PressKey(key ebiten.Key) error
- func (g *Game) PressMouseButton(button ebiten.MouseButton) error
- func (g *Game) ReleaseKey(key ebiten.Key) error
- func (g *Game) ReleaseMouseButton(button ebiten.MouseButton) error
- func (g *Game) RunCustom(name, request string) (string, error)
- func (g *Game) Screenshot() (*image.RGBA, error)
- func (g *Game) ScreenshotBase64() (string, error)
- func (g *Game) ScreenshotToFile(path string) error
- func (g *Game) ScrollWheel(x, y float64) error
- func (g *Game) Shutdown() error
- func (g *Game) StateQuery(name string, path string) (any, error)
- func (g *Game) WaitFor(fn func() bool, timeout time.Duration) bool
- type GameUpdate
- type Mock
- func (m *Mock) Game() GameUpdate
- func (m *Mock) InjectKeyPress(key ebiten.Key)
- func (m *Mock) InjectKeyRelease(key ebiten.Key)
- func (m *Mock) InjectMouseButtonPress(button ebiten.MouseButton)
- func (m *Mock) InjectMouseButtonRelease(button ebiten.MouseButton)
- func (m *Mock) InjectMousePosition(x, y int)
- func (m *Mock) InjectWheel(x, y float64)
- func (m *Mock) Tick()
- func (m *Mock) Ticks(n int)
- type Option
Constants ¶
This section is empty.
Variables ¶
var ErrGameNotRunning = errors.New("game is not running")
ErrGameNotRunning is returned when an operation is attempted on a game that has not been launched or has already shut down.
var ErrInvalidState = errors.New("invalid game state")
ErrInvalidState is returned when the game is in an invalid state for the requested operation.
var ErrTimeout = errors.New("operation timed out")
ErrTimeout is returned when an operation times out.
Functions ¶
This section is empty.
Types ¶
type Game ¶
type Game struct {
// contains filtered or unexported fields
}
Game provides black-box testing control over a game running in a separate process. It communicates with the game via JSON-RPC over Unix sockets.
func Launch ¶
Launch starts a game binary in a separate process and returns a Game controller. The game must be an autoebiten-enabled game that listens on the Unix socket.
The Game is automatically cleaned up when the test ends via t.Cleanup(). Callers can also manually call Shutdown() for early cleanup.
Options:
- WithTimeout: sets timeout for operations (default 30s)
- WithArgs: adds command-line arguments
- WithEnv: sets environment variables
func (*Game) Ping ¶
Ping checks if the game is responsive. Returns an error if the game is not running or not responding.
func (*Game) PressMouseButton ¶
func (g *Game) PressMouseButton(button ebiten.MouseButton) error
PressMouseButton sends a mouse button press event.
func (*Game) ReleaseKey ¶
ReleaseKey sends a key release event to the game.
func (*Game) ReleaseMouseButton ¶
func (g *Game) ReleaseMouseButton(button ebiten.MouseButton) error
ReleaseMouseButton sends a mouse button release event.
func (*Game) Screenshot ¶
Screenshot captures the current game screen and returns it as an image.
func (*Game) ScreenshotBase64 ¶
ScreenshotBase64 captures the current game screen and returns it as a base64 string.
func (*Game) ScreenshotToFile ¶
ScreenshotToFile captures the current game screen and saves it to a file.
func (*Game) ScrollWheel ¶
ScrollWheel sends a wheel scroll event.
func (*Game) Shutdown ¶
Shutdown gracefully terminates the game process. It first attempts SIGTERM, then falls back to SIGKILL if needed.
func (*Game) StateQuery ¶
StateQuery queries game state via reflection-based path. The path uses dot notation, e.g., "Player.X", "Inventory.0.Name".
type GameUpdate ¶
type GameUpdate interface {
Update() error
}
GameUpdate is the interface required for Mock white-box testing. Games must implement at least an Update method.
type Mock ¶
type Mock struct {
// contains filtered or unexported fields
}
Mock provides white-box testing control over a game running in the same process. It injects inputs directly into the game's update loop without requiring RPC.
func NewMock ¶
func NewMock(t *testing.T, game GameUpdate) *Mock
NewMock creates a new Mock controller for white-box testing. The provided game must implement at least Update() error.
The Mock is automatically cleaned up when the test ends via t.Cleanup().
func (*Mock) Game ¶
func (m *Mock) Game() GameUpdate
Game returns the underlying game instance. This allows direct access to game state for assertions.
func (*Mock) InjectKeyPress ¶
InjectKeyPress buffers a key press event to be applied on the next Tick.
func (*Mock) InjectKeyRelease ¶
InjectKeyRelease buffers a key release event to be applied on the next Tick.
func (*Mock) InjectMouseButtonPress ¶
func (m *Mock) InjectMouseButtonPress(button ebiten.MouseButton)
InjectMouseButtonPress buffers a mouse button press event.
func (*Mock) InjectMouseButtonRelease ¶
func (m *Mock) InjectMouseButtonRelease(button ebiten.MouseButton)
InjectMouseButtonRelease buffers a mouse button release event.
func (*Mock) InjectMousePosition ¶
InjectMousePosition sets the mouse cursor position.
func (*Mock) InjectWheel ¶
InjectWheel sets the wheel scroll delta.
type Option ¶
type Option func(*config)
Option configures Launch behavior.
func WithEnv ¶
WithEnv sets environment variables for the game process. These are added to the current environment, not replacing it.
func WithTimeout ¶
WithTimeout sets the timeout for game operations. Default is 30 seconds.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
testgames/custom
command
|
|
|
testgames/simple
command
|
|
|
testgames/stateful
command
|