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-targetsandcargo clippy --workspace --all-targets, withRUSTFLAGS=-D warnings, so any warning fails the buildcargo test --workspace- a check that no
.rsfile undercrates/containstodo!(),unimplemented!(),STUBorPLACEHOLDER
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).
WelkinCompanionBotstays online, answers chat and instant messages, accepts friend requests and wanders. Use it to give a second viewer someone to talk to.WelkinPuppetBotis steered by hand. It reads commands from the file named inWELKIN_CMD_FILE(defaultpuppet.cmd) and understandssay,shout,whisper,im,goto,follow,turn,face,walk,back,stop,sit,stand,fly,up,jump,anim,accept,decline,whereandquit. 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.