Merge pull request #1816 from ludovic111/feat/mod-test-runner
🤖 Agent: cargo horizon-mod test runs a mod's test scripts with no game. Main is merged in, and the runner fills the new snapshot fields (input, render, frame stats) with the trial run's screen size. Verified: clippy, the cargo-horizon-mod, coords-hud and horizon-mods tests (57), launcher, and cargo horizon-mod test on coords-hud (2 scripts).
This commit is contained in:
@@ -6,12 +6,15 @@
|
||||
//! `assets/` and `data/`; a folder without `Cargo.toml` is content only.
|
||||
//! - `run [--game <horizon-client>] [-- <game args>]`: build, then play with
|
||||
//! the mod; run `build` again and the game reloads it.
|
||||
//! - `test [--debug] [--hmod <file>] [<name>]`: build, then run the mod's
|
||||
//! `tests/*.toml` scripts in the sandbox, with no game.
|
||||
//! - `check <file> [--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 <path> [--template code|content] | build [--debug] | run [--game <horizon-client>] [-- <game args>] | check <file> [--kind <kind>] [--key <public key> --signature <file.minisig>] [--json] | registry build|review|check|list".into()),
|
||||
_ => Err("usage: cargo horizon-mod new <path> [--template code|content] | build [--debug] | run [--game <horizon-client>] [-- <game args>] | test [--debug] [--hmod <file>] [<name>] | check <file> [--kind <kind>] [--key <public key> --signature <file.minisig>] [--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 `<name>`)
|
||||
/// 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<PathBuf> = std::fs::read_dir("tests")
|
||||
.map_err(|e| {
|
||||
format!(
|
||||
"tests/: {e} (a mod's tests are tests/<name>.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"
|
||||
|
||||
@@ -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)"]
|
||||
@@ -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"]
|
||||
@@ -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"
|
||||
@@ -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};
|
||||
|
||||
@@ -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/<name>.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<Player>,
|
||||
pub clock: Option<Clock>,
|
||||
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<TestGame, String> {
|
||||
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<String> {
|
||||
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<Output> {
|
||||
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<Step>,
|
||||
}
|
||||
|
||||
/// Fields of the player to change; the others keep their values.
|
||||
#[derive(Debug, Default, Deserialize)]
|
||||
#[serde(deny_unknown_fields)]
|
||||
pub struct PlayerSet {
|
||||
x: Option<f64>,
|
||||
y: Option<f64>,
|
||||
z: Option<f64>,
|
||||
yaw: Option<f32>,
|
||||
pitch: Option<f32>,
|
||||
health: Option<f32>,
|
||||
food: Option<u32>,
|
||||
dimension: Option<String>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Default, Deserialize)]
|
||||
#[serde(deny_unknown_fields, rename_all = "kebab-case")]
|
||||
pub struct ClockSet {
|
||||
game_time: Option<u64>,
|
||||
day_time: Option<u64>,
|
||||
}
|
||||
|
||||
/// 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<PlayerSet>,
|
||||
clock: Option<ClockSet>,
|
||||
#[serde(default)]
|
||||
ticks: u64,
|
||||
#[serde(default)]
|
||||
frames: u64,
|
||||
chat: Option<String>,
|
||||
command: Option<String>,
|
||||
#[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<Vec<String>>,
|
||||
/// Every chat line shown during the step, in order.
|
||||
chat: Option<Vec<String>>,
|
||||
/// The command's feedback, and its red error.
|
||||
feedback: Option<String>,
|
||||
error: Option<String>,
|
||||
/// The panel's lines (`[]`: no panel) and its corner.
|
||||
panel: Option<Vec<String>>,
|
||||
corner: Option<String>,
|
||||
/// 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<String>,
|
||||
}
|
||||
|
||||
impl Script {
|
||||
pub fn parse(text: &str) -> Result<Script, String> {
|
||||
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<f64>| *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<String> = 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<String> = 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<T: PartialEq + std::fmt::Debug>(what: &str, want: &T, got: &T) -> Result<(), String> {
|
||||
if want == got {
|
||||
return Ok(());
|
||||
}
|
||||
Err(format!(
|
||||
"{what}\n expected: {want:?}\n got: {got:?}"
|
||||
))
|
||||
}
|
||||
@@ -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"
|
||||
);
|
||||
}
|
||||
|
||||
+8
-4
@@ -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,
|
||||
|
||||
+64
-3
@@ -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 <public
|
||||
key> --signature <file>.minisig`.
|
||||
|
||||
### Testing a mod
|
||||
|
||||
`cargo horizon-mod test` builds the mod, then runs each `tests/<name>.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 <file>` 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 = "<Steve> 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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user