diff --git a/crates/cargo-horizon-mod/src/main.rs b/crates/cargo-horizon-mod/src/main.rs index a4585f680..b82c6d07f 100644 --- a/crates/cargo-horizon-mod/src/main.rs +++ b/crates/cargo-horizon-mod/src/main.rs @@ -6,12 +6,15 @@ //! `assets/` and `data/`; a folder without `Cargo.toml` is content only. //! - `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::{ Capability, Content, Manifest, Package, manifest::{MANIFEST, component_imports, componentize}, + testing::{Script, TestGame}, }; mod check; mod registry; @@ -36,9 +39,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 [--template code|content] | build [--debug] | run [--game ] [-- ] | check [--kind ] [--key --signature ] [--json] | registry build|review|check|list".into()), + _ => Err("usage: cargo horizon-mod new [--template code|content] | build [--debug] | run [--game ] [-- ] | test [--debug] [--hmod ] [] | check [--kind ] [--key --signature ] [--json] | registry build|review|check|list".into()), }; match result { Ok(()) => ExitCode::SUCCESS, @@ -97,6 +101,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"), + ), ]; // A block copying a vanilla one, with its model, name, loot, recipe and tag. let content = [ @@ -270,6 +278,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") @@ -312,6 +377,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..d8c8076b4 --- /dev/null +++ b/crates/horizon-mods/src/testing.rs @@ -0,0 +1,416 @@ +//! 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, + // The GUI of a 1280 x 720 window at scale 3, as the trial run's. + gui_size: (427.0, 240.0), + ..Snapshot::default() + }); + } + + /// `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 3b33ab4b2..8c6c9d451 100644 --- a/crates/horizon-mods/tests/sandbox.rs +++ b/crates/horizon-mods/tests/sandbox.rs @@ -4,6 +4,7 @@ use horizon_mods::{ Clock, Corner, HeldItem, Mods, Output, Package, Player, Shape, Snapshot, Status, manifest::componentize, + testing::{Script, TestGame}, }; use std::{ path::{Path, PathBuf}, @@ -703,3 +704,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 7b8c5a464..211a06f8b 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` (templates `code` and `content`), `build`, `run`, `check` | +| `cargo horizon-mod` | `new` (templates `code` and `content`), `build`, `run`, `test`, `check` | | Example mods | `coords-hud` (code), `ruby-content` (content) | ## Guide @@ -33,7 +33,10 @@ The step-by-step guide, from installing the tools to publishing on the registry, ([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 @@ -94,11 +97,12 @@ 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. - Experimental: `ui` button widget; `render.set-corner`, `text-width`, `frame-stats`; `input.mapping`, `clicks-per-second` (what the official FPS, keystrokes and zoom mods need). - Experimental `input` (`experimental = ["input"]`): `claim-items`, `register-key`, `held`, `poll` (use-start, diff --git a/docs/mods.md b/docs/mods.md index 9fad50f57..556a77187 100644 --- a/docs/mods.md +++ b/docs/mods.md @@ -17,7 +17,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3. | Example mods | `crates/horizon-mod-sdk/examples/coords-hud`, `examples/predator-missile` | coordinates, facing and time HUD, `/where`, `/coords`; `/missile`, a guided missile from vanilla commands | | Horizon's official mods | `mods/official/` | the extras moving to the registry: FPS Counter (`fps-overlay`), Keystrokes, Zoom | | Runtime | `crates/horizon-mods` | wasmtime 48 LTS, component model | -| Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new [--template code\|content] / build / run / check`, and the registry's CI (`registry build / review / list`) | +| Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new [--template code\|content] / 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 | @@ -220,11 +220,12 @@ 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 # (--template content: a content mod, no code) 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 @@ -245,13 +246,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 405c62976..34330835d 100644 --- a/website/docs/mods.md +++ b/website/docs/mods.md @@ -32,7 +32,7 @@ cd my-mod cargo horizon-mod build ``` -The [Mod API](/docs/api/mods) lists what a mod can do today and what comes next, and its [reference](/docs/api/mods-reference) every function. 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](/docs/modpacks)). +`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 [Mod API](/docs/api/mods) lists what a mod can do today and what comes next, and its [reference](/docs/api/mods-reference) every function. 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](/docs/modpacks)). ## Finding resource packs and modpacks