Testing

← Back to docs · Crate structure · Viewer compatibility

Welkin has four layers of testing. Cheap tests run on every change; the heavier ones need a running server.

Cargo tests

cargo test --workspace

At commit 749d9ed the workspace has 2,688 passing tests, 0 failures and 2 ignored. Most are unit tests next to the code. Several are end-to-end tests that start real services on a local port and drive them over HTTP or UDP, for example the groups tests, which run against the grid groups router, and the terraforming test, which sends a ModifyLand packet and decodes the LayerData another viewer receives. Prefer this kind of test when you change a handler: a test that only calls a function does not catch a handler that nothing calls.

Some databases in tests use a file, not sqlite::memory:, because each connection to an in-memory SQLite URL is a separate database.

CI

.github/workflows/ci.yml runs on pushes to dev and on pull requests to main or dev:

  • cargo check --workspace --all-targets and cargo clippy --workspace --all-targets, with RUSTFLAGS=-D warnings, so any warning fails the build
  • cargo test --workspace
  • a check that no .rs file under crates/ contains todo!(), unimplemented!(), STUB or PLACEHOLDER

Run the same commands before you push.

Golden vectors

crates/welkin-scene/tests/golden/terrain/ holds terrain LayerData byte streams generated by OpenSimulator 0.9.3.0's own encoder. The Rust encoder is compared against them: 17 match byte for byte and 2 are checked by decoding. Use this pattern when you port a wire format: generate the reference output once from the C# source, store it with a manifest that records how it was made, and compare.

Conformance and bot tools

The welkin-conformance crate builds the osim-conform tool. Its subcommands cover recording and replaying protocol traffic (record, replay, lludp-record, lludp-replay), running bots (bot, bot-script), checking a ROBUST server against recorded responses (service-conformance), and a physics spike (physics-spike). Its integration tests in crates/welkin-conformance/tests/ replay recorded traffic against the grid services and check LLUDP round trips.

welkin-realmwalker is a Rust bot SDK for scripted viewers.

LibreMetaverse harness

tests/libremetaverse-harness/ is a C# program (.NET 9, LibreMetaverse 3.3.0) that logs in to a running Welkin grid as a real client and checks the first steps a viewer takes: login, region info, spawn position, default animation, and movement echo. It returns an exit code and gives up after 30 seconds. Start welkin-robust and welkin-region first, create an account, and run it with dotnet run from that directory. tests/bot-tests/libremetaverse/ holds a further bot test project.

Interactive bots

Two more C# programs in tests/bot-tests/libremetaverse/ log in as a real LibreMetaverse client so you can try a running grid by hand. Both read the same environment variables: WELKIN_LOGIN_URI (default http://127.0.0.1:8002/), WELKIN_BOT_FIRST, WELKIN_BOT_LAST and WELKIN_BOT_PASSWORD. Create the account first (see Regions, estate and users).

  • WelkinCompanionBot stays online, answers chat and instant messages, accepts friend requests and wanders. Use it to give a second viewer someone to talk to.
  • WelkinPuppetBot is steered by hand. It reads commands from the file named in WELKIN_CMD_FILE (default puppet.cmd) and understands say, shout, whisper, im, goto, follow, turn, face, walk, back, stop, sit, stand, fly, up, jump, anim, accept, decline, where and quit. It prints the chat, instant messages and friend requests it receives.

These are developer tools, not automated tests: nothing checks their output.

LSL script corpus

tests/script-testing/ measures how many real-world LSL scripts the compiler handles. corpus/ and scripts/ hold the scripts, runner/ is a Rust tool (lsl-test-runner), and results/matrix.md records, for each script, whether lexing, parsing, analysis and code generation pass and which builtins are missing. Add a script that fails and fix the compiler until it passes.

Live viewer sessions

Some things only a viewer shows: whether a prim looks right, whether a jump feels right. Run a viewer (Aurora Viewer is the primary target, Firestorm the secondary) against a local grid and record the result on the viewer compatibility page, saying which behaviours were checked live and which only in code.