Docs / Testing

Testing a client against Asobi

If you're building or maintaining a client - an SDK, a custom integration, a bot - the asobi-test-harness gives you a fixed, known-good backend to test the wire protocol against, so protocol drift breaks exactly one test in one place.

What it is

A minimal, deterministic Asobi backend for CI: a Docker Compose stack (Postgres plus ghcr.io/widgrensit/asobi_lua:latest) running two tiny Lua fixtures - a smoke match mode and a smoke_world world mode. Every client SDK runs the same canonical scenarios against it, so there is one source of truth for how a correct client behaves.

Run it

git clone https://github.com/widgrensit/asobi-test-harness
cd asobi-test-harness
docker compose up -d               # backend on http://localhost:8080

# point your SDK's smoke test at it, then tear down
ASOBI_URL=http://localhost:8080 ./smoke_tests/run.sh
docker compose down -v

Client smoke tests read the backend URL from ASOBI_URL (default http://localhost:8080), run the scenarios in scenarios/canonical.md in order, and exit non-zero on the first mismatch - the reference implementation is asobi-js/smoke_tests/.

What the scenarios assert

  • Connect + auth: register over REST, open the WS, session.connect {token} -> session.connected, and the connected player_id matches the REST one.
  • Matchmaking: two clients matchmaker.add {mode:"smoke"} both reach match.matched with the same match_id (and it's match.matched, not match.joined).
  • Input -> state: a match.input produces a match.state reflecting the move.
  • World fanout: join a world, send world.input, and every subscribed client sees the world.tick deltas (the add/update/remove ops).

Server-side fanout suite

The repo also ships an Erlang PropEr/Common Test suite (cd multiplayer_ct && rebar3 ct) that drives N concurrent fake clients into one world and asserts every player's move reaches every other subscribed client - catching "applied server-side but never broadcast" regressions. It brings the harness up and down itself.

What's next