From 7bffc4c6709d08424a56f88a7098325a5d837a67 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sun, 25 Oct 2026 15:25:52 +0100 Subject: [PATCH 1/2] cargo horizon-mod test: run a mod's TOML test scripts headless A mod's tests/.toml scripts run in the sandbox the game uses, with no game and no window. The runner plays the game's part (the player and clock the mod reads, ticks, frames, chat lines, commands, a reload) and each step checks what the mod did: its commands, chat lines, command feedback and errors, HUD panel and corner, or that it was turned off. A failing step names itself and prints expected against got. Each script runs on a scratch copy, so storage starts empty and is removed afterwards. horizon_mods::testing (feature runtime) holds TestGame and Script; the cargo subcommand builds the mod (or takes --hmod), filters scripts by name, and fails when one does. The template gains tests/hello.toml, coords-hud gains panel and where scripts, and the sandbox tests run the example's scripts and check the runner's failures, reload and expected stops. Scripts don't care what language the mod is written in, so script mods (Lua) get the same runner. Co-Authored-By: Claude Opus 5.5 --- crates/cargo-horizon-mod/src/main.rs | 69 ++- .../template/tests/hello.toml | 14 + .../examples/coords-hud/tests/panel.toml | 36 ++ .../examples/coords-hud/tests/where.toml | 17 + crates/horizon-mods/src/lib.rs | 2 + crates/horizon-mods/src/testing.rs | 413 ++++++++++++++++++ crates/horizon-mods/tests/sandbox.rs | 81 +++- docs/api/mods.md | 12 +- docs/mods.md | 67 ++- website/docs/mods.md | 2 +- 10 files changed, 703 insertions(+), 10 deletions(-) create mode 100644 crates/cargo-horizon-mod/template/tests/hello.toml create mode 100644 crates/horizon-mod-sdk/examples/coords-hud/tests/panel.toml create mode 100644 crates/horizon-mod-sdk/examples/coords-hud/tests/where.toml create mode 100644 crates/horizon-mods/src/testing.rs diff --git a/crates/cargo-horizon-mod/src/main.rs b/crates/cargo-horizon-mod/src/main.rs index 925633930..2117c849a 100644 --- a/crates/cargo-horizon-mod/src/main.rs +++ b/crates/cargo-horizon-mod/src/main.rs @@ -4,12 +4,15 @@ //! - `build [--debug]`: the `.hmod` in `target/horizon-mod/`. //! - `run [--game ] [-- ]`: build, then play with //! the mod; run `build` again and the game reloads it. +//! - `test [--debug] [--hmod ] []`: build, then run the mod's +//! `tests/*.toml` scripts in the sandbox, with no game. //! - `check [--json]`: what the registry checks of a submission //! (`.hmod`, `.hpack`, resource pack `.zip`), with a trial run for a mod. //! - `registry build|review|check|list`: the registry repository's CI. use horizon_mods::{ Manifest, Package, manifest::{MANIFEST, component_imports, componentize}, + testing::{Script, TestGame}, }; mod check; mod registry; @@ -34,9 +37,10 @@ fn main() -> ExitCode { println!("Built {}", p.display()); }), Some("run") => run(&args[1..]), + Some("test") => test(&args[1..]), Some("check") => check(&args[1..]), Some("registry") => registry::main(&args[1..]), - _ => Err("usage: cargo horizon-mod new | build [--debug] | run [--game ] [-- ] | check [--kind ] [--key --signature ] [--json] | registry build|review|check|list".into()), + _ => Err("usage: cargo horizon-mod new | build [--debug] | run [--game ] [-- ] | test [--debug] [--hmod ] [] | check [--kind ] [--key --signature ] [--json] | registry build|review|check|list".into()), }; match result { Ok(()) => ExitCode::SUCCESS, @@ -95,6 +99,10 @@ fn new(args: &[String]) -> Result<(), String> { (MANIFEST, include_str!("../template/horizon-mod.toml")), ("src/lib.rs", include_str!("../template/src/lib.rs")), (".gitignore", include_str!("../template/gitignore")), + ( + "tests/hello.toml", + include_str!("../template/tests/hello.toml"), + ), ]; for (file, text) in files { let to = dir.join(file); @@ -189,6 +197,63 @@ fn check(args: &[String]) -> Result<(), String> { Ok(()) } +/// `test`: every `tests/*.toml` script (those whose name holds ``) +/// against the built mod, or the `.hmod` given with `--hmod`. +fn test(args: &[String]) -> Result<(), String> { + let hmod = match flag(args, "--hmod") { + Some(p) => PathBuf::from(p), + None => build(!args.iter().any(|a| a == "--debug"))?, + }; + let filter = args + .iter() + .enumerate() + .find(|(i, a)| !a.starts_with("--") && (*i == 0 || args[i - 1] != "--hmod")) + .map(|(_, a)| a.as_str()); + let mut scripts: Vec = std::fs::read_dir("tests") + .map_err(|e| { + format!( + "tests/: {e} (a mod's tests are tests/.toml: docs/mods.md, \"Testing a mod\")" + ) + })? + .filter_map(|e| Some(e.ok()?.path())) + .filter(|p| p.extension().is_some_and(|e| e == "toml")) + .filter(|p| filter.is_none_or(|f| p.to_string_lossy().contains(f))) + .collect(); + scripts.sort(); + if scripts.is_empty() { + return Err("no tests/*.toml to run".into()); + } + println!( + "running {} scripts against {}", + scripts.len(), + hmod.display() + ); + let mut failed = 0; + for path in &scripts { + let result = std::fs::read_to_string(path) + .map_err(|e| e.to_string()) + .and_then(|text| Script::parse(&text)) + .and_then(|script| { + let mut game = TestGame::load(&hmod)?; + script.run(&mut game)?; + Ok(script.steps.len()) + }); + match result { + Ok(steps) => println!("test {} ... ok ({steps} steps)", path.display()), + Err(e) => { + failed += 1; + println!("test {} ... FAILED\n {e}", path.display()); + } + } + } + let passed = scripts.len() - failed; + if failed > 0 { + return Err(format!("{failed} failed, {passed} passed")); + } + println!("test result: ok. {passed} passed"); + Ok(()) +} + fn run(args: &[String]) -> Result<(), String> { let path = build(true)?; let game = flag(args, "--game") @@ -231,6 +296,8 @@ mod tests { ); let cargo = std::fs::read_to_string(path.join("Cargo.toml")).unwrap(); assert!(cargo.contains("name = \"my-mod\"") && cargo.contains(SDK_GIT)); + let script = std::fs::read_to_string(path.join("tests/hello.toml")).unwrap(); + assert_eq!(Script::parse(&script).unwrap().steps.len(), 3); assert!( new(&[path.display().to_string()]).is_err(), "never overwrites" diff --git a/crates/cargo-horizon-mod/template/tests/hello.toml b/crates/cargo-horizon-mod/template/tests/hello.toml new file mode 100644 index 000000000..17afd7e65 --- /dev/null +++ b/crates/cargo-horizon-mod/template/tests/hello.toml @@ -0,0 +1,14 @@ +# `cargo horizon-mod test` runs every tests/*.toml against the built mod, with no game: +# steps happen in order, and `expect` checks what the mod showed during the step. +# Every key: docs/mods.md, "Testing a mod". + +[[step]] +expect.commands = ["hello"] + +[[step]] +command = "hello world" +expect.chat = ["Hello world! (1 so far)"] + +[[step]] +command = "hello again" +expect.chat = ["Hello again! (2 so far)"] diff --git a/crates/horizon-mod-sdk/examples/coords-hud/tests/panel.toml b/crates/horizon-mod-sdk/examples/coords-hud/tests/panel.toml new file mode 100644 index 000000000..eed41a461 --- /dev/null +++ b/crates/horizon-mod-sdk/examples/coords-hud/tests/panel.toml @@ -0,0 +1,36 @@ +# The panel follows the player and the clock; /coords hides and shows it. + +[player] +x = 12.5 +z = -3.25 +yaw = 180.0 + +[clock] +day-time = 29999 + +[[step]] +ticks = 1 +expect.panel = ["XYZ 12.5 / 64.0 / -3.2", "Facing North (-Z)", "Day 2, 12:00"] +expect.corner = "top-left" + +[[step]] +player = { x = -100.0, yaw = 90.0 } +ticks = 1 +expect.panel = ["XYZ -100.0 / 64.0 / -3.2", "Facing West (-X)", "Day 2, 12:00"] + +[[step]] +command = "coords" +expect.feedback = "Coordinates panel hidden" + +# A step's ticks come before its command: the panel goes at the next tick. +[[step]] +ticks = 1 +expect.panel = [] + +[[step]] +command = "coords" +expect.feedback = "Coordinates panel shown" + +[[step]] +ticks = 1 +expect.panel = ["XYZ -100.0 / 64.0 / -3.2", "Facing West (-X)", "Day 2, 12:00"] diff --git a/crates/horizon-mod-sdk/examples/coords-hud/tests/where.toml b/crates/horizon-mod-sdk/examples/coords-hud/tests/where.toml new file mode 100644 index 000000000..99a4aecdf --- /dev/null +++ b/crates/horizon-mod-sdk/examples/coords-hud/tests/where.toml @@ -0,0 +1,17 @@ +# /where puts the position in chat; on the title screen it answers with an error. + +[player] +x = 12.5 +y = 70.2 +z = -3.25 +dimension = "minecraft:the_nether" + +[[step]] +command = "where" +expect.chat = ["12, 70, -4 in minecraft:the_nether"] + +[[step]] +title-screen = true +command = "where" +expect.chat = [] +expect.error = "Not in a world" diff --git a/crates/horizon-mods/src/lib.rs b/crates/horizon-mods/src/lib.rs index 17a6c5aa0..3c5fe74f6 100644 --- a/crates/horizon-mods/src/lib.rs +++ b/crates/horizon-mods/src/lib.rs @@ -12,6 +12,8 @@ pub mod manifest; pub mod modpack; #[cfg(feature = "runtime")] mod runtime; +#[cfg(feature = "runtime")] +pub mod testing; pub use content::Content; pub use manifest::{Capability, Manifest, Package, Side, find}; diff --git a/crates/horizon-mods/src/testing.rs b/crates/horizon-mods/src/testing.rs new file mode 100644 index 000000000..4a62b3838 --- /dev/null +++ b/crates/horizon-mods/src/testing.rs @@ -0,0 +1,413 @@ +//! A mod run with no game: `cargo horizon-mod test` (docs/mods.md, "Testing a mod"). +//! +//! [`TestGame`] loads one `.hmod` from a scratch copy (its `storage` lives and +//! dies with the run) into the same sandbox the game uses, and plays the game's +//! part: the snapshot, ticks, frames, chat lines and commands. [`Script`] is a +//! test written in TOML, `tests/.toml` in the mod's folder: steps, each +//! saying what happens and what the mod must have shown by then. +use crate::{Clock, Corner, Mods, Output, Panel, Player, Snapshot, Status}; +use serde::Deserialize; +use std::{ + path::{Path, PathBuf}, + sync::atomic::{AtomicUsize, Ordering}, +}; + +/// One mod in the sandbox, driven by a test. +pub struct TestGame { + mods: Mods, + dir: PathBuf, + hmod: PathBuf, + /// What the mod reads with `game-read`; ticks move the clock as the game does. + pub player: Option, + pub clock: Option, + tick: u64, +} + +/// Where a script starts: standing at 0.5 64 0.5 in the Overworld, facing +/// south, full health and food, at the first tick of a new world's first morning. +pub fn default_player() -> Player { + Player { + x: 0.5, + y: 64.0, + z: 0.5, + yaw: 0.0, + pitch: 0.0, + health: 20.0, + food: 20, + dimension: "minecraft:overworld".into(), + } +} + +impl TestGame { + /// Starts the mod at `hmod`, as the game would with it turned on. Errs + /// when it doesn't start, with the game's reason. + pub fn load(hmod: &Path) -> Result { + static RUN: AtomicUsize = AtomicUsize::new(0); + let dir = std::env::temp_dir().join(format!( + "horizon-mod-test-{}-{}", + std::process::id(), + RUN.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).map_err(|e| format!("{}: {e}", dir.display()))?; + let copy = dir.join(hmod.file_name().unwrap_or("mod.hmod".as_ref())); + let mut game = TestGame { + mods: Mods::default(), + hmod: copy.clone(), + dir, + player: Some(default_player()), + clock: Some(Clock { + game_time: 0, + day_time: 0, + }), + tick: 0, + }; + copy_mod(hmod, ©)?; + game.start()?; + Ok(game) + } + + fn start(&mut self) -> Result<(), String> { + self.mods = Mods::load(std::slice::from_ref(&self.hmod), |_| true, |_| false); + match &self.mods.entries()[0].status { + Status::Failed(reason) => Err(format!("the mod didn't start: {reason}")), + _ if !self.mods.is_running() => Err("the mod has no code to run".into()), + _ => Ok(()), + } + } + + /// Stops the mod and starts it again, as a rebuild does in the game: its + /// memory starts over, its `storage` stays. + pub fn reload(&mut self) -> Result<(), String> { + self.mods = Mods::default(); + self.start() + } + + fn snapshot(&mut self) { + self.mods.set_snapshot(Snapshot { + player: self.player.clone(), + clock: self.clock, + }); + } + + /// `n` game ticks; each moves the clock one tick on, as the game does. + pub fn tick(&mut self, n: u64) { + for _ in 0..n { + self.tick += 1; + if let Some(clock) = &mut self.clock { + clock.game_time += 1; + clock.day_time += 1; + } + self.snapshot(); + self.mods.tick(self.tick); + } + } + /// `n` frames, 1/60 s apart. + pub fn frames(&mut self, n: u64) { + self.snapshot(); + for _ in 0..n { + self.mods.frame(1.0 / 60.0); + } + } + /// A chat line the player receives. + pub fn chat(&mut self, line: &str) { + self.snapshot(); + self.mods.chat(line); + } + /// `/line` typed by the player (without the slash); false when the mod + /// owns no such command. + pub fn command(&mut self, line: &str) -> bool { + self.snapshot(); + self.mods.command(line) + } + + /// The scratch copy the mod runs from; its `storage` is beside it. + pub fn hmod(&self) -> &Path { + &self.hmod + } + /// The commands the mod registered. + pub fn commands(&self) -> Vec { + self.mods.commands().map(str::to_owned).collect() + } + pub fn panel(&self) -> Option<&Panel> { + self.mods.panels().next() + } + pub fn status(&self) -> &Status { + &self.mods.entries()[0].status + } + /// What the mod showed since the last call. + pub fn drain(&mut self) -> Vec { + self.mods.drain() + } +} + +impl Drop for TestGame { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.dir); + } +} + +/// A `.hmod` file, or a mod folder (`horizon-mod.toml` + `mod.wasm`). +fn copy_mod(from: &Path, to: &Path) -> Result<(), String> { + let err = |e: std::io::Error| format!("{}: {e}", from.display()); + if !from.is_dir() { + return std::fs::copy(from, to).map(drop).map_err(err); + } + std::fs::create_dir_all(to).map_err(err)?; + for entry in std::fs::read_dir(from).map_err(err)? { + let entry = entry.map_err(err)?; + if entry.file_type().map_err(err)?.is_file() { + std::fs::copy(entry.path(), to.join(entry.file_name())).map_err(err)?; + } + } + Ok(()) +} + +/// A test in TOML: where the player starts, then steps run in order. +#[derive(Debug, Default, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "kebab-case")] +pub struct Script { + #[serde(default)] + pub player: PlayerSet, + #[serde(default)] + pub clock: ClockSet, + #[serde(default, rename = "step")] + pub steps: Vec, +} + +/// Fields of the player to change; the others keep their values. +#[derive(Debug, Default, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct PlayerSet { + x: Option, + y: Option, + z: Option, + yaw: Option, + pitch: Option, + health: Option, + food: Option, + dimension: Option, +} + +#[derive(Debug, Default, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "kebab-case")] +pub struct ClockSet { + game_time: Option, + day_time: Option, +} + +/// One step. Its parts happen in this order: `reload`, `title-screen`, +/// `player`, `clock`, `ticks`, `frames`, `chat`, `command`; then `expect` is +/// checked against what the mod showed during the step. +#[derive(Debug, Default, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "kebab-case")] +pub struct Step { + #[serde(default)] + reload: bool, + /// Leave the world: the mod reads no player and no clock until a step sets them. + #[serde(default)] + title_screen: bool, + player: Option, + clock: Option, + #[serde(default)] + ticks: u64, + #[serde(default)] + frames: u64, + chat: Option, + command: Option, + #[serde(default)] + expect: Expect, +} + +/// What a step checks; a part left out is not checked. +#[derive(Debug, Default, Deserialize)] +#[serde(deny_unknown_fields, rename_all = "kebab-case")] +pub struct Expect { + /// The commands the mod owns. + commands: Option>, + /// Every chat line shown during the step, in order. + chat: Option>, + /// The command's feedback, and its red error. + feedback: Option, + error: Option, + /// The panel's lines (`[]`: no panel) and its corner. + panel: Option>, + corner: Option, + /// The mod is turned off during this step, for a reason holding this text. + /// Without it, a mod that stops fails the test. + stopped: Option, +} + +impl Script { + pub fn parse(text: &str) -> Result { + toml::from_str(text).map_err(|e| e.to_string()) + } + + /// Runs every step on `game`; the error names the first step that failed. + pub fn run(&self, game: &mut TestGame) -> Result<(), String> { + if let Some(p) = &mut game.player { + self.player.apply(p); + } + if let Some(c) = &mut game.clock { + self.clock.apply(c); + } + for (i, step) in self.steps.iter().enumerate() { + step.run(game) + .map_err(|e| format!("step {} ({}): {e}", i + 1, step.describe()))?; + } + Ok(()) + } +} + +impl PlayerSet { + fn apply(&self, p: &mut Player) { + let set = |to: &mut f64, v: Option| *to = v.unwrap_or(*to); + set(&mut p.x, self.x); + set(&mut p.y, self.y); + set(&mut p.z, self.z); + p.yaw = self.yaw.unwrap_or(p.yaw); + p.pitch = self.pitch.unwrap_or(p.pitch); + p.health = self.health.unwrap_or(p.health); + p.food = self.food.unwrap_or(p.food); + if let Some(d) = &self.dimension { + p.dimension.clone_from(d); + } + } +} + +impl ClockSet { + fn apply(&self, c: &mut Clock) { + c.game_time = self.game_time.unwrap_or(c.game_time); + c.day_time = self.day_time.unwrap_or(c.day_time); + } +} + +impl Step { + fn describe(&self) -> String { + let mut parts = Vec::new(); + if self.reload { + parts.push("reload".to_string()); + } + let count = |n: u64, what: &str| format!("{n} {what}{}", if n == 1 { "" } else { "s" }); + if self.ticks > 0 { + parts.push(count(self.ticks, "tick")); + } + if self.frames > 0 { + parts.push(count(self.frames, "frame")); + } + if let Some(line) = &self.chat { + parts.push(format!("chat {line:?}")); + } + if let Some(line) = &self.command { + parts.push(format!("/{line}")); + } + if parts.is_empty() { + parts.push("checks".into()); + } + parts.join(", ") + } + + fn run(&self, game: &mut TestGame) -> Result<(), String> { + if self.reload { + game.reload()?; + } + if self.title_screen { + game.player = None; + game.clock = None; + } + if let Some(set) = &self.player { + set.apply(game.player.get_or_insert_with(default_player)); + } + if let Some(set) = &self.clock { + set.apply(game.clock.get_or_insert(Clock { + game_time: 0, + day_time: 0, + })); + } + game.tick(self.ticks); + game.frames(self.frames); + if let Some(line) = &self.chat { + game.chat(line); + } + let owned = self.command.as_ref().map(|line| game.command(line)); + let out = game.drain(); + let stopped = out.iter().find_map(|o| match o { + Output::Stopped { reason, .. } => Some(reason.as_str()), + _ => None, + }); + let e = &self.expect; + match (stopped, &e.stopped) { + (Some(reason), Some(want)) if !reason.contains(want.as_str()) => { + return Err(format!("the mod stopped ({reason}), expected {want:?}")); + } + (Some(_), Some(_)) => return Ok(()), + (Some(reason), None) => return Err(format!("the mod stopped: {reason}")), + (None, Some(want)) => { + return Err(format!( + "the mod kept running, expected it to stop ({want:?})" + )); + } + (None, None) => {} + } + if owned == Some(false) { + let line = self.command.as_deref().unwrap_or_default(); + let name = line.split(' ').next().unwrap_or_default(); + return Err(format!("the mod owns no command /{name}")); + } + if let Some(want) = &e.commands { + same("commands", want, &game.commands())?; + } + if let Some(want) = &e.chat { + let got: Vec = out + .iter() + .filter_map(|o| match o { + Output::Chat { text, .. } => Some(text.clone()), + _ => None, + }) + .collect(); + same("chat", want, &got)?; + } + let feedback = |error: bool| { + out.iter().rev().find_map(|o| match o { + Output::Feedback { text, error: e } if *e == error => Some(text.clone()), + _ => None, + }) + }; + if let Some(want) = &e.feedback { + same("feedback", &Some(want.clone()), &feedback(false))?; + } + if let Some(want) = &e.error { + same("error", &Some(want.clone()), &feedback(true))?; + } + if let Some(want) = &e.panel { + let got: Vec = game + .panel() + .map(|p| p.lines.iter().map(|l| l.text.clone()).collect()) + .unwrap_or_default(); + same("panel", want, &got)?; + } + if let Some(want) = &e.corner { + let got = game.panel().map(|p| corner_name(p.corner).to_string()); + same("corner", &Some(want.clone()), &got)?; + } + Ok(()) + } +} + +fn corner_name(c: Corner) -> &'static str { + match c { + Corner::TopLeft => "top-left", + Corner::TopRight => "top-right", + Corner::BottomLeft => "bottom-left", + Corner::BottomRight => "bottom-right", + } +} + +fn same(what: &str, want: &T, got: &T) -> Result<(), String> { + if want == got { + return Ok(()); + } + Err(format!( + "{what}\n expected: {want:?}\n got: {got:?}" + )) +} diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs index a246c07b0..48f77aaef 100644 --- a/crates/horizon-mods/tests/sandbox.rs +++ b/crates/horizon-mods/tests/sandbox.rs @@ -1,7 +1,9 @@ //! Loads real mods built with the SDK: the coords-hud example and a guest //! that misbehaves on command. Needs `rustup target add wasm32-unknown-unknown`. use horizon_mods::{ - Clock, Corner, Mods, Output, Package, Player, Snapshot, Status, manifest::componentize, + Clock, Corner, Mods, Output, Package, Player, Snapshot, Status, + manifest::componentize, + testing::{Script, TestGame}, }; use std::{ path::{Path, PathBuf}, @@ -396,3 +398,80 @@ capabilities = ["registries"] // Content has no hooks: the game's per-tick mod work stays skipped. assert!(!mods.is_running()); } + +/// `cargo horizon-mod test` on the example: its own `tests/*.toml` pass. +#[test] +fn the_examples_test_scripts_pass() { + let tests = + Path::new(env!("CARGO_MANIFEST_DIR")).join("../horizon-mod-sdk/examples/coords-hud/tests"); + let mut ran = 0; + for entry in std::fs::read_dir(tests).unwrap() { + let path = entry.unwrap().path(); + let script = Script::parse(&std::fs::read_to_string(&path).unwrap()).unwrap(); + let mut game = TestGame::load(&mods_dir().join("coords_hud.hmod")).unwrap(); + script + .run(&mut game) + .unwrap_or_else(|e| panic!("{}: {e}", path.display())); + ran += 1; + } + assert_eq!(ran, 2); +} + +#[test] +fn a_test_script_says_which_step_failed_and_why() { + let script = Script::parse( + r#" + [[step]] + ticks = 3 + command = "hello there" + expect.chat = ["hello there after 2 ticks"] + "#, + ) + .unwrap(); + let mut game = TestGame::load(&mods_dir().join("horizon_mods_test_guest.hmod")).unwrap(); + assert_eq!( + script.run(&mut game).unwrap_err(), + "step 1 (3 ticks, /hello there): chat\n expected: [\"hello there after 2 ticks\"]\n \ + got: [\"hello there after 3 ticks\"]" + ); + assert!( + Script::parse("[[step]]\ntick = 1").is_err(), + "a typo is an error" + ); +} + +#[test] +fn a_test_script_reloads_and_expects_a_stop() { + let script = Script::parse( + r#" + [[step]] + command = "save kept" + expect.feedback = "saved" + + [[step]] + reload = true + command = "load" + expect.chat = ["kept"] + + [[step]] + command = "panic" + expect.stopped = "panic" + + [[step]] + reload = true + command = "nope" + "#, + ) + .unwrap(); + let mut game = TestGame::load(&mods_dir().join("horizon_mods_test_guest.hmod")).unwrap(); + let dir = game.hmod().parent().unwrap().to_path_buf(); + assert_eq!( + script.run(&mut game).unwrap_err(), + "step 4 (reload, /nope): the mod owns no command /nope" + ); + drop(game); + assert!( + !dir.exists(), + "the scratch copy and its storage are removed" + ); +} diff --git a/docs/api/mods.md b/docs/api/mods.md index bec03e84e..b382744e9 100644 --- a/docs/api/mods.md +++ b/docs/api/mods.md @@ -19,7 +19,7 @@ the player before the mod is turned on, and checked against the component's real | Capabilities | 5: `game-read`, `chat`, `hud`, `storage`, `registries` | | Manifest `api` lines served | 2: `0.1` (code), `0.2` (content) | | SDK | the `Mod` trait (5 methods), `Registration` (4 builders), `export_mod!`, log helpers | -| `cargo horizon-mod` | `new`, `build`, `run` | +| `cargo horizon-mod` | `new`, `build`, `run`, `test`, `check` | | Example mods | `coords-hud` (code), `ruby-content` (content) | ## Guide @@ -30,7 +30,10 @@ the player before the mod is turned on, and checked against the component's real ([The manifest](../mods.md#the-manifest)). 3. `cargo horizon-mod run` builds the `.hmod` and starts the game with it as a dev mod; after an edit, `cargo horizon-mod build` and the running game reloads it. -4. Content mods: [Content mods (API 0.2)](../mods.md#content-mods-api-02). +4. `cargo horizon-mod test` runs the mod's `tests/*.toml` scripts in the sandbox, with no game: ticks, commands, + chat lines and the player's position in, chat, feedback and the HUD panel checked + ([Testing a mod](../mods.md#testing-a-mod)). +5. Content mods: [Content mods (API 0.2)](../mods.md#content-mods-api-02). ## Reference @@ -90,10 +93,11 @@ What real mods need next, in the order modpacks and servers need it: - **Config**: typed settings the game shows and stores for the mod, on the server too. - **Keys and the crosshair target**: keybinds in Controls; what the player is looking at. - **Script mods and other languages**: see [Ways in](#ways-in). -- **SDK**: a headless test runner (load a mod, feed it ticks and events, assert on its output, no window), templates - per kind of mod, typed wrappers in the SDK for every interface. Dev mods already reload when rebuilt. +- **SDK**: templates per kind of mod, typed wrappers in the SDK for every interface. Dev mods already reload when + rebuilt, and `cargo horizon-mod test` runs a mod headless. ## Changelog +- SDK: `cargo horizon-mod test` and `horizon_mods::testing`, test scripts in TOML; the template has one. - API 0.2 (content): data-driven blocks and items, tags, `horizon:add_to`, terrain adaptation. - API 0.1.0: `log`, `game`, `chat`, `hud`, `storage`; `init`, `tick`, `frame`, `command`, `chat`. diff --git a/docs/mods.md b/docs/mods.md index 5fa6a290d..326007e20 100644 --- a/docs/mods.md +++ b/docs/mods.md @@ -16,7 +16,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3. | SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 | | Example mod | `crates/horizon-mod-sdk/examples/coords-hud` | coordinates, facing and time HUD, `/where`, `/coords` | | Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model | -| Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new / build / run / check`, and the registry's CI (`registry build / review / list`) | +| Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new / build / run / test / check`, and the registry's CI (`registry build / review / list`) | | In the game | `crates/horizon-client/src/game/mods.rs`, Options > Mods | client mods | | Launcher mod browser (Modrinth, CurseForge with a key) | [mod-browser.md](mod-browser.md) | resource packs, modpacks | | Registry index (`index.json`, `.hpack`), signatures | `horizon_mods::index`, [api/mod-index.md](api/mod-index.md) | schema 1; launcher and website next | @@ -214,10 +214,11 @@ Benchmarks (`--benchmark`) never load mods. ```sh rustup target add wasm32-unknown-unknown cargo install --git https://github.com/ludovic111/horizon cargo-horizon-mod -cargo horizon-mod new my-mod # Cargo.toml, horizon-mod.toml, src/lib.rs +cargo horizon-mod new my-mod # Cargo.toml, horizon-mod.toml, src/lib.rs, tests/hello.toml cd my-mod cargo horizon-mod run # build, then start the game with it cargo horizon-mod build # again after an edit: the running game reloads it +cargo horizon-mod test # build, then run tests/*.toml with no game ``` `run` starts `horizon-client` (on `PATH`, or `--game PATH`, or @@ -238,13 +239,73 @@ and each of its commands: it must start and never trap or overrun. It checks a `.hpack` and a resource pack `.zip` too, and a signature with `--key --signature .minisig`. +### Testing a mod + +`cargo horizon-mod test` builds the mod, then runs each `tests/.toml` in +the sandbox the game uses, with no game and no window: the test plays the +game's part (the player and the clock the mod reads, ticks, frames, chat lines, +commands) and checks what the mod showed. A script fails at its first wrong +step, with what it expected and what it got; the command fails if any script +does. `--debug` builds without optimizing, `--hmod ` tests a `.hmod` +already built, and a name runs only the scripts whose path holds it. Each +script gets a scratch copy of the mod, so its `storage` starts empty and is +removed afterwards. + +```toml +# tests/panel.toml (examples/coords-hud) +[player] # where the script starts; unset fields keep the defaults +x = 12.5 # (0.5 64 0.5, yaw 0, 20 health and food, the Overworld) +z = -3.25 +yaw = 180.0 + +[clock] # day-time 0 is 6:00 on day 1; each tick adds one +day-time = 29999 + +[[step]] +ticks = 1 +expect.panel = ["XYZ 12.5 / 64.0 / -3.2", "Facing North (-Z)", "Day 2, 12:00"] +expect.corner = "top-left" + +[[step]] +command = "coords" +expect.feedback = "Coordinates panel hidden" +``` + +A step's parts happen in this order: + +| Key | Does | +| --- | --- | +| `reload = true` | stops the mod and starts it again, as a rebuild does in the game: its memory starts over, its `storage` stays | +| `title-screen = true` | no player and no clock until a step sets them | +| `player = { x = 3.0, ... }`, `clock = { day-time = 0 }` | changes those fields (`x y z yaw pitch health food dimension`, `game-time day-time`) | +| `ticks = n`, `frames = n` | that many ticks (the game's tick counter and the clock move on), then frames 1/60 s apart | +| `chat = " hi"` | a chat line the player receives | +| `command = "where north"` | the player types `/where north`; a command the mod doesn't own fails the step | + +Then `expect` checks what the mod did during the step; a key left out is not +checked: + +| `expect.` | Checks | +| --- | --- | +| `commands = ["where"]` | the commands the mod owns | +| `chat = ["..."]` | every chat line it showed, in order (`[]`: none) | +| `feedback = "..."`, `error = "..."` | the command's answer, shown plain or in red | +| `panel = ["..."]`, `corner = "top-left"` | its HUD panel's lines (`[]`: no panel) and corner | +| `stopped = "panic"` | the mod was turned off, for a reason holding this text; without it, a mod that traps, panics or overruns fails the test | + +Unknown keys are errors, so a typo never passes silently. The same runner is +`horizon_mods::testing` for Rust code that drives a mod (`TestGame`, +`Script`): Horizon's own tests run the examples' scripts with it. Scripts test +any mod, whatever it was written in. + ### Template layout ``` my-mod/ ├── Cargo.toml # cdylib, horizon-mod-sdk, release: opt-level "s", LTO ├── horizon-mod.toml # the manifest -└── src/lib.rs # impl Mod, export_mod! +├── src/lib.rs # impl Mod, export_mod! +└── tests/hello.toml # cargo horizon-mod test ``` A mod is a type implementing `horizon_mod_sdk::Mod`; its state lives in the diff --git a/website/docs/mods.md b/website/docs/mods.md index 0c125cf73..08f3492a0 100644 --- a/website/docs/mods.md +++ b/website/docs/mods.md @@ -30,7 +30,7 @@ cd my-mod cargo horizon-mod run ``` -`run` builds the mod and starts the game with it. After an edit, `cargo horizon-mod build` rebuilds it and the running game reloads it. The full guide, with the API, the manifest and the roadmap, is [docs/mods.md](https://github.com/ludovic111/horizon/blob/main/docs/mods.md). Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](https://github.com/ludovic111/horizon/blob/main/docs/modpacks.md)). +`run` builds the mod and starts the game with it. After an edit, `cargo horizon-mod build` rebuilds it and the running game reloads it. `cargo horizon-mod test` runs the mod's test scripts (`tests/*.toml`: ticks, commands and the player's position in, chat and HUD lines checked) with no game open. The full guide, with the API, the manifest and the roadmap, is [docs/mods.md](https://github.com/ludovic111/horizon/blob/main/docs/mods.md). Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](https://github.com/ludovic111/horizon/blob/main/docs/modpacks.md)). ## Finding resource packs and modpacks From 8e71cb4754c17fbc083ef212fdd21806c7900309 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Mon, 26 Oct 2026 07:57:49 +0100 Subject: [PATCH 2/2] Test runner: fill the snapshot's new fields, with the trial run's screen size Co-Authored-By: Claude Opus 5.5 --- crates/horizon-mods/src/testing.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/crates/horizon-mods/src/testing.rs b/crates/horizon-mods/src/testing.rs index 4a62b3838..d8c8076b4 100644 --- a/crates/horizon-mods/src/testing.rs +++ b/crates/horizon-mods/src/testing.rs @@ -87,6 +87,9 @@ impl TestGame { self.mods.set_snapshot(Snapshot { player: self.player.clone(), clock: self.clock, + // The GUI of a 1280 x 720 window at scale 3, as the trial run's. + gui_size: (427.0, 240.0), + ..Snapshot::default() }); }