diff --git a/crates/ui/Cargo.toml b/crates/ui/Cargo.toml index e7df43f46..29d7f29f2 100644 --- a/crates/ui/Cargo.toml +++ b/crates/ui/Cargo.toml @@ -51,8 +51,8 @@ color_fonts = ["epaint/color_fonts"] system_fonts = ["dep:fontique", "dep:unicode-script"] # `docking::testing`: a headless driver for application docking tests. testing = [] -# craft_ui::testing: per-language screenshot tests and IME smoke tests with egui_kittest -# (desktop only). +# craft_ui::testing: per-language screenshot tests, IME smoke tests, input steps and review +# screenshots with egui_kittest (desktop only). screen-testing = ["dep:egui_kittest"] [dev-dependencies] diff --git a/crates/ui/README.md b/crates/ui/README.md index f2ae27b0f..a48e49476 100644 --- a/crates/ui/README.md +++ b/crates/ui/README.md @@ -546,6 +546,38 @@ documentation has the recipe for a shortcut smoke test on a non-Latin layout thr letters such as ổ, so an app relying on it fails the `vi` screens until its own face covers them. The per-release manual checks are in [language-testing.md](../../docs/language-testing.md). +### Input steps and review screenshots + +`testing::input` drives any egui_kittest `Harness` with a fixed number of frames per step: +`move_to` (1), `press` and `release` (2 each), `click` (3), `drag` (`steps` + 3, primary button, +1 to `MAX_DRAG_STEPS` moves), `key` (2), `type_text` (2) and `wheel` (2, in points). The modifiers +given to a step are held from its first frame and released in its last; `press` keeps them held +until the matching `release`. A drag with another button is `press`, `move_to` and `release`. The +module documentation lists the events of each frame. The counts hold when no events queued with +`Harness::event` are waiting, so run the harness after queuing events. `docking::testing::DockDriver` runs its own +egui context and keeps its own `window_click` and `window_hold`. + +`testing::snapshot` writes screenshots for review and compares nothing. `snapshot_dir(var)` reads +the folder from the environment variable `var`: `DEFAULT_DIR_VAR` (`CRAFT_UI_SNAPSHOT_DIR`), or an +app's own variable name. With no folder, `with_snapshot_renderer` leaves the builder unchanged and +no GPU is set up; with one, it sets up wgpu and returns `SnapshotError::Render` on a machine that +can't render. `save(harness, dir, name)` renders the last frame to `{dir}/{name}.png`, creating the +folder, and runs no frames, so settle the screen and set the theme first. Names are plain file +names (ASCII letters, digits, `-`, `_`, `.`, `@`). + +```rust,ignore +use craft_ui::testing::{input, snapshot}; +use egui::{Modifiers, PointerButton, pos2}; + +let dir = snapshot::snapshot_dir("CRAFT_EXPORT_SNAPSHOTS"); +let mut harness = snapshot::with_snapshot_renderer(Harness::builder(), dir.as_deref())?.build_ui_state(export_ui, state); +input::click(&mut harness, pos2(40.0, 20.0), PointerButton::Primary, Modifiers::NONE); +harness.run(); +if let Some(dir) = &dir { + snapshot::save(&mut harness, dir, "export-dialog")?; +} +``` + ## Print settings and feedback `printing::State` holds the transient printer selection, copies, duplex and grayscale settings, @@ -678,7 +710,8 @@ verify the actual pixels as well as callback routing. The crate uses egui 0.37 and Rust 1.95 or later. Its production dependency disables egui's default features, so egui's bundled fonts and rendering features remain the application's choice. It has no default features; see [UI fonts](#ui-fonts) for `color_fonts` and `system_fonts`, and -[Testing screens in each language](#testing-screens-in-each-language) for `screen-testing`; +[Testing screens in each language](#testing-screens-in-each-language) for `screen-testing`, which +also adds `testing::input` and `testing::snapshot`; `testing` adds the headless docking driver `docking::testing`. See the [suite audit](../../docs/ui-components-audit.md) for candidates, policies and adoption order. diff --git a/crates/ui/src/testing/input.rs b/crates/ui/src/testing/input.rs new file mode 100644 index 000000000..80309b84f --- /dev/null +++ b/crates/ui/src/testing/input.rs @@ -0,0 +1,115 @@ +//! Pointer, key, text and wheel input for an egui_kittest [`Harness`], with a fixed number of +//! frames per step so a test can count on when the app sees each event. +//! +//! Each function puts its events straight into the harness's input for the frame it belongs to +//! and runs exactly the frames listed below. The counts hold only when no events are waiting in +//! the harness's queue: [`Harness::step`] gives each event queued with [`Harness::event`] (or a +//! kittest node action) a frame of its own, so a step's first frame then runs once per queued +//! event, with the step's own events in the first of them. Run the harness after queuing events +//! and before calling these functions. +//! +//! | Step | Frames | Events, frame by frame | +//! |------|--------|------------------------| +//! | [`move_to`] | 1 | pointer moved | +//! | [`press`] | 2 | modifiers, pointer moved, button down; nothing | +//! | [`release`] | 2 | modifiers, pointer moved, button up; modifiers released | +//! | [`click`] | 3 | modifiers, pointer moved, button down; button up; modifiers released | +//! | [`drag`] | `steps` + 3 | modifiers, pointer moved, primary down; one move per step; primary up; modifiers released | +//! | [`key`] | 2 | modifiers, key down, key up; modifiers released | +//! | [`type_text`] | 2 | text; nothing | +//! | [`wheel`] | 2 | modifiers, wheel; modifiers released | +//! +//! The modifiers are sent as [`Event::ModifiersChanged`] and in each pointer, key and wheel event. +//! [`press`] leaves them held, so moves between a [`press`] and its [`release`] see them too; the +//! other steps release them in their last frame. A drag with another button is a [`press`], some +//! [`move_to`] calls and a [`release`]. +//! +//! ```no_run +//! use craft_ui::testing::input; +//! use egui::{Modifiers, PointerButton, pos2, vec2}; +//! +//! let mut harness = egui_kittest::Harness::new_ui(|ui| _ = ui.button("Open")); +//! input::click(&mut harness, pos2(20.0, 12.0), PointerButton::Primary, Modifiers::NONE); +//! input::drag(&mut harness, pos2(20.0, 40.0), pos2(120.0, 40.0), 4, Modifiers::SHIFT); +//! input::wheel(&mut harness, vec2(0.0, -48.0), Modifiers::COMMAND); +//! ``` + +#[cfg(test)] +mod tests; + +use egui::{Event, Key, Modifiers, MouseWheelSource, MouseWheelUnit, PointerButton, Pos2, TouchPhase, Vec2}; +use egui_kittest::Harness; + +/// The most moves [`drag`] sends; a larger `steps` is reduced to this. +pub const MAX_DRAG_STEPS: usize = 1024; + +/// Run one frame with `events` as its input. +fn frame(harness: &mut Harness<'_, State>, events: impl IntoIterator) { + harness.input_mut().events.extend(events); + harness.step(); +} + +fn button(pos: Pos2, button: PointerButton, pressed: bool, modifiers: Modifiers) -> Event { + Event::PointerButton { pos, button, pressed, modifiers } +} + +/// Move the pointer to `pos`. 1 frame. +pub fn move_to(harness: &mut Harness<'_, State>, pos: Pos2) { + frame(harness, [Event::PointerMoved(pos)]); +} + +/// Press `pointer` at `pos` with `modifiers` held, and keep both held. 2 frames. +pub fn press(harness: &mut Harness<'_, State>, pos: Pos2, pointer: PointerButton, modifiers: Modifiers) { + frame(harness, [Event::ModifiersChanged(modifiers), Event::PointerMoved(pos), button(pos, pointer, true, modifiers)]); + frame(harness, []); +} + +/// Release `pointer` at `pos`, then release the modifiers. 2 frames. +pub fn release(harness: &mut Harness<'_, State>, pos: Pos2, pointer: PointerButton, modifiers: Modifiers) { + frame(harness, [Event::ModifiersChanged(modifiers), Event::PointerMoved(pos), button(pos, pointer, false, modifiers)]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} + +/// Click `pointer` at `pos` with `modifiers` held. 3 frames. +pub fn click(harness: &mut Harness<'_, State>, pos: Pos2, pointer: PointerButton, modifiers: Modifiers) { + frame(harness, [Event::ModifiersChanged(modifiers), Event::PointerMoved(pos), button(pos, pointer, true, modifiers)]); + frame(harness, [button(pos, pointer, false, modifiers)]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} + +/// Drag with the primary button from `from` to `to` in `steps` even moves, the last one at `to`. +/// `steps` is at least 1 and at most [`MAX_DRAG_STEPS`]. `steps` + 3 frames. +pub fn drag(harness: &mut Harness<'_, State>, from: Pos2, to: Pos2, steps: usize, modifiers: Modifiers) { + let steps = steps.clamp(1, MAX_DRAG_STEPS); + let primary = PointerButton::Primary; + frame(harness, [Event::ModifiersChanged(modifiers), Event::PointerMoved(from), button(from, primary, true, modifiers)]); + for step in 1..=steps { + let pos = if step == steps { to } else { from.lerp(to, step as f32 / steps as f32) }; + frame(harness, [Event::PointerMoved(pos)]); + } + frame(harness, [button(to, primary, false, modifiers)]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} + +/// Press and release `key` with `modifiers` held, in one frame, as a platform reports a quick +/// key press. The events carry no physical key and are not repeats. 2 frames. +pub fn key(harness: &mut Harness<'_, State>, key: Key, modifiers: Modifiers) { + let event = |pressed| Event::Key { key, physical_key: None, pressed, repeat: false, modifiers }; + frame(harness, [Event::ModifiersChanged(modifiers), event(true), event(false)]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} + +/// Type `text` into the focused widget as one text event. Empty text sends no event. 2 frames. +pub fn type_text(harness: &mut Harness<'_, State>, text: &str) { + frame(harness, (!text.is_empty()).then(|| Event::Text(text.to_owned()))); + frame(harness, []); +} + +/// Turn the wheel by `delta` points with `modifiers` held. The event's phase is +/// [`TouchPhase::Move`] and its source [`MouseWheelSource::Unknown`]. A positive `y` moves the +/// content down, as egui defines it. 2 frames. +pub fn wheel(harness: &mut Harness<'_, State>, delta: Vec2, modifiers: Modifiers) { + let event = Event::MouseWheel { unit: MouseWheelUnit::Point, delta, phase: TouchPhase::Move, source: MouseWheelSource::Unknown, modifiers }; + frame(harness, [Event::ModifiersChanged(modifiers), event]); + frame(harness, [Event::ModifiersChanged(Modifiers::NONE)]); +} diff --git a/crates/ui/src/testing/input/tests.rs b/crates/ui/src/testing/input/tests.rs new file mode 100644 index 000000000..0dd80f310 --- /dev/null +++ b/crates/ui/src/testing/input/tests.rs @@ -0,0 +1,235 @@ +use egui::{Event, Key, Modifiers, PointerButton, Pos2, Sense, Vec2, pos2, vec2}; +use egui_kittest::Harness; + +use super::{MAX_DRAG_STEPS, click, drag, key, move_to, press, release, type_text, wheel}; + +/// The input events and held modifiers of every frame the app ran. +#[derive(Default)] +struct Frames { + events: Vec>, + modifiers: Vec, +} + +impl Frames { + fn count(&self) -> usize { + self.events.len() + } + + fn pointer_buttons(&self) -> Vec<(Pos2, PointerButton, bool, Modifiers)> { + let events = self.events.iter().flatten(); + events + .filter_map(|event| match event { + Event::PointerButton { pos, button, pressed, modifiers } => Some((*pos, *button, *pressed, *modifiers)), + _ => None, + }) + .collect() + } + + fn moves(&self) -> Vec { + self.events.iter().flatten().filter_map(|event| if let Event::PointerMoved(pos) = event { Some(*pos) } else { None }).collect() + } +} + +/// A harness that records its frames, with the frame `build` runs already cleared. +fn recorder() -> Harness<'static, Frames> { + let mut harness = Harness::builder().with_size([200.0, 100.0]).build_ui_state( + |ui, frames: &mut Frames| { + let (events, modifiers) = ui.input(|i| (i.raw.events.clone(), i.modifiers)); + frames.events.push(events); + frames.modifiers.push(modifiers); + }, + Frames::default(), + ); + *harness.state_mut() = Frames::default(); + harness +} + +type Step = dyn Fn(&mut Harness<'static, Frames>); + +#[test] +fn each_step_runs_its_documented_frames() { + const AT: Pos2 = Pos2::new(40.0, 30.0); + let cases: [(&str, usize, &Step); 9] = [ + ("move_to", 1, &|h| move_to(h, AT)), + ("press", 2, &|h| press(h, AT, PointerButton::Primary, Modifiers::NONE)), + ("release", 2, &|h| release(h, AT, PointerButton::Primary, Modifiers::NONE)), + ("click", 3, &|h| click(h, AT, PointerButton::Primary, Modifiers::NONE)), + ("drag 4", 7, &|h| drag(h, AT, pos2(80.0, 30.0), 4, Modifiers::NONE)), + ("drag 0", 4, &|h| drag(h, AT, pos2(80.0, 30.0), 0, Modifiers::NONE)), + ("key", 2, &|h| key(h, Key::A, Modifiers::NONE)), + ("type_text", 2, &|h| type_text(h, "abc")), + ("wheel", 2, &|h| wheel(h, vec2(0.0, -10.0), Modifiers::NONE)), + ]; + for (name, frames, step) in cases { + let mut harness = recorder(); + step(&mut harness); + assert_eq!(harness.state().count(), frames, "{name}"); + } +} + +#[test] +fn queued_events_add_frames_to_the_first_frame() { + let mut harness = recorder(); + harness.event(Event::Text("a".to_owned())); + harness.event(Event::Text("b".to_owned())); + click(&mut harness, pos2(40.0, 30.0), PointerButton::Primary, Modifiers::NONE); + let frames = harness.state(); + assert_eq!(frames.count(), 4); + assert!(frames.events[0].contains(&Event::Text("a".to_owned()))); + assert!(frames.events[0].contains(&Event::PointerMoved(pos2(40.0, 30.0)))); + assert_eq!(frames.events[1], vec![Event::Text("b".to_owned())]); +} + +#[test] +fn click_moves_presses_and_releases_in_order() { + let at = pos2(40.0, 30.0); + let mut harness = recorder(); + click(&mut harness, at, PointerButton::Primary, Modifiers::CTRL); + let frames = harness.state(); + assert_eq!( + frames.events[0], + vec![ + Event::ModifiersChanged(Modifiers::CTRL), + Event::PointerMoved(at), + Event::PointerButton { pos: at, button: PointerButton::Primary, pressed: true, modifiers: Modifiers::CTRL }, + ] + ); + assert_eq!(frames.events[1], vec![Event::PointerButton { pos: at, button: PointerButton::Primary, pressed: false, modifiers: Modifiers::CTRL }]); + assert_eq!(frames.events[2], vec![Event::ModifiersChanged(Modifiers::NONE)]); + assert_eq!(frames.modifiers, [Modifiers::CTRL, Modifiers::CTRL, Modifiers::NONE]); +} + +#[test] +fn click_reaches_a_button() { + let mut harness = Harness::builder().with_size([200.0, 100.0]).build_ui_state( + |ui, clicks: &mut (u32, u32)| { + let response = ui.add_sized([100.0, 40.0], egui::Button::new("Open")); + clicks.0 += u32::from(response.clicked()); + clicks.1 += u32::from(response.secondary_clicked()); + }, + (0, 0), + ); + click(&mut harness, pos2(50.0, 20.0), PointerButton::Primary, Modifiers::NONE); + click(&mut harness, pos2(50.0, 20.0), PointerButton::Secondary, Modifiers::NONE); + press(&mut harness, pos2(50.0, 20.0), PointerButton::Secondary, Modifiers::NONE); + release(&mut harness, pos2(50.0, 20.0), PointerButton::Secondary, Modifiers::NONE); + assert_eq!(*harness.state(), (1, 2)); +} + +#[test] +fn press_keeps_buttons_and_modifiers_until_release() { + let (from, to) = (pos2(10.0, 10.0), pos2(90.0, 50.0)); + let mut harness = recorder(); + press(&mut harness, from, PointerButton::Secondary, Modifiers::ALT); + move_to(&mut harness, to); + release(&mut harness, to, PointerButton::Secondary, Modifiers::ALT); + let frames = harness.state(); + assert_eq!( + frames.pointer_buttons(), + [(from, PointerButton::Secondary, true, Modifiers::ALT), (to, PointerButton::Secondary, false, Modifiers::ALT)] + ); + assert_eq!(frames.moves(), [from, to, to]); + assert_eq!(frames.modifiers, [Modifiers::ALT, Modifiers::ALT, Modifiers::ALT, Modifiers::ALT, Modifiers::NONE]); +} + +#[test] +fn drag_moves_evenly_and_ends_at_the_target() { + let (from, to) = (pos2(10.0, 20.0), pos2(90.0, 60.0)); + let mut harness = recorder(); + drag(&mut harness, from, to, 4, Modifiers::SHIFT); + let frames = harness.state(); + assert_eq!(frames.moves(), [from, pos2(30.0, 30.0), pos2(50.0, 40.0), pos2(70.0, 50.0), to]); + assert_eq!( + frames.pointer_buttons(), + [(from, PointerButton::Primary, true, Modifiers::SHIFT), (to, PointerButton::Primary, false, Modifiers::SHIFT)] + ); + // Held through the moves and the release, released in the last frame. + assert_eq!(frames.modifiers[..6], [Modifiers::SHIFT; 6]); + assert_eq!(frames.modifiers[6], Modifiers::NONE); +} + +#[test] +fn drag_with_zero_steps_moves_once() { + let (from, to) = (pos2(10.0, 20.0), pos2(90.0, 60.0)); + let mut harness = recorder(); + drag(&mut harness, from, to, 0, Modifiers::NONE); + assert_eq!(harness.state().moves(), [from, to]); +} + +#[test] +fn drag_steps_are_capped() { + let mut harness = recorder(); + drag(&mut harness, pos2(0.0, 0.0), pos2(100.0, 0.0), usize::MAX, Modifiers::NONE); + assert_eq!(harness.state().count(), MAX_DRAG_STEPS + 3); + assert_eq!(harness.state().moves().last(), Some(&pos2(100.0, 0.0))); +} + +#[test] +fn drag_moves_a_draggable_area() { + let mut harness = Harness::builder().with_size([200.0, 100.0]).build_ui_state( + |ui, moved: &mut Vec2| { + let response = ui.allocate_response(vec2(200.0, 100.0), Sense::drag()); + *moved += response.drag_delta(); + }, + Vec2::ZERO, + ); + drag(&mut harness, pos2(20.0, 20.0), pos2(120.0, 60.0), 5, Modifiers::NONE); + let moved = *harness.state(); + assert!((moved - vec2(100.0, 40.0)).length() < 0.01, "{moved:?}"); +} + +#[test] +fn key_sends_down_and_up_with_modifiers() { + let mut harness = recorder(); + key(&mut harness, Key::S, Modifiers::COMMAND); + let frames = harness.state(); + let event = |pressed| Event::Key { key: Key::S, physical_key: None, pressed, repeat: false, modifiers: Modifiers::COMMAND }; + assert_eq!(frames.events[0], vec![Event::ModifiersChanged(Modifiers::COMMAND), event(true), event(false)]); + assert_eq!(frames.modifiers, [Modifiers::COMMAND, Modifiers::NONE]); +} + +#[test] +fn type_text_reaches_the_focused_field() { + let mut harness = Harness::builder().with_size([200.0, 100.0]).build_ui_state( + |ui, text: &mut String| { + let label = ui.label("Name"); + let response = ui.text_edit_singleline(text).labelled_by(label.id); + if ui.memory(|m| m.focused().is_none()) { + response.request_focus(); + } + }, + String::new(), + ); + harness.run(); + type_text(&mut harness, "Craft"); + type_text(&mut harness, ""); + assert_eq!(harness.state(), "Craft"); +} + +#[test] +fn empty_text_sends_no_event() { + let mut harness = recorder(); + type_text(&mut harness, ""); + assert!(harness.state().events.iter().all(Vec::is_empty)); +} + +#[test] +fn wheel_sends_points_with_its_modifiers() { + let mut harness = recorder(); + wheel(&mut harness, vec2(0.0, -24.0), Modifiers::COMMAND); + let frames = harness.state(); + assert_eq!( + frames.events[0], + vec![ + Event::ModifiersChanged(Modifiers::COMMAND), + Event::MouseWheel { + unit: egui::MouseWheelUnit::Point, + delta: vec2(0.0, -24.0), + phase: egui::TouchPhase::Move, + source: egui::MouseWheelSource::Unknown, + modifiers: Modifiers::COMMAND, + }, + ] + ); + assert_eq!(frames.modifiers, [Modifiers::COMMAND, Modifiers::NONE]); +} diff --git a/crates/ui/src/testing/mod.rs b/crates/ui/src/testing/mod.rs index 9cab5bbd6..61d72b17d 100644 --- a/crates/ui/src/testing/mod.rs +++ b/crates/ui/src/testing/mod.rs @@ -55,7 +55,15 @@ //! On Russian, the `с` key reports `C` at physical `C` and must run Ctrl+C. The app's dispatcher //! (`craft_keymap::egui::Dispatcher`) turns the event into a `KeyInput` with //! `KeyInput::from_egui`. +//! +//! # Input steps and review screenshots +//! +//! [`input`] clicks, drags, presses keys, types and turns the wheel in any [`Harness`], each step +//! taking a fixed number of frames. [`snapshot`] writes screenshots for review to a folder named +//! by an environment variable, and nothing when it is unset. +pub mod input; +pub mod snapshot; #[cfg(test)] mod tests; diff --git a/crates/ui/src/testing/snapshot.rs b/crates/ui/src/testing/snapshot.rs new file mode 100644 index 000000000..aec648004 --- /dev/null +++ b/crates/ui/src/testing/snapshot.rs @@ -0,0 +1,137 @@ +//! Screenshots of a test's screens for a person to review, written to a folder named by an +//! environment variable. Nothing is compared: [`Screens::snapshots`](super::Screens::snapshots) +//! is the comparing test. +//! +//! With the variable unset, [`snapshot_dir`] returns `None`, [`with_snapshot_renderer`] leaves the +//! builder alone (no GPU setup), and the test skips its [`save`] calls. With it set, +//! [`with_snapshot_renderer`] sets up wgpu rendering and [`save`] writes `{dir}/{name}.png` from the +//! last frame. [`save`] runs no frames: settle the screen first (for example `harness.run()`, or +//! the two or three steps an app's own test takes), and set the theme on the builder. +//! +//! ```no_run +//! use craft_ui::testing::snapshot; +//! +//! let dir = snapshot::snapshot_dir(snapshot::DEFAULT_DIR_VAR); +//! let builder = snapshot::with_snapshot_renderer(egui_kittest::Harness::builder(), dir.as_deref())?; +//! let mut harness = builder.with_theme(egui::Theme::Light).build_ui(|ui| _ = ui.label("Export")); +//! harness.run(); +//! if let Some(dir) = &dir { +//! snapshot::save(&mut harness, dir, "export-light")?; +//! } +//! # Ok::<(), snapshot::SnapshotError>(()) +//! ``` + +#[cfg(test)] +mod tests; + +use std::any::Any; +use std::ffi::OsString; +use std::fmt; +use std::panic::{AssertUnwindSafe, catch_unwind}; +use std::path::{Path, PathBuf}; + +use egui_kittest::{Harness, HarnessBuilder}; + +/// The variable [`snapshot_dir`] reads when an app has no name of its own for it. +pub const DEFAULT_DIR_VAR: &str = "CRAFT_UI_SNAPSHOT_DIR"; + +/// The longest name [`save`] takes, in bytes. +pub const MAX_NAME_LEN: usize = 120; + +/// Why a screenshot was not written. +#[derive(Debug)] +pub enum SnapshotError { + /// The name is empty, too long, or not a plain file name (see [`save`]). + InvalidName(String), + /// The renderer could not be set up or could not draw the frame, for example on a machine + /// with no GPU adapter and no software renderer. + Render(String), + /// The folder could not be created. + CreateDir { path: PathBuf, source: std::io::Error }, + /// The PNG could not be encoded or written. + Write { path: PathBuf, message: String }, +} + +impl fmt::Display for SnapshotError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::InvalidName(name) => write!(f, "invalid screenshot name {name:?}"), + Self::Render(message) => write!(f, "couldn't render the screenshot: {message}"), + Self::CreateDir { path, source } => write!(f, "couldn't create {}: {source}", path.display()), + Self::Write { path, message } => write!(f, "couldn't write {}: {message}", path.display()), + } + } +} + +impl std::error::Error for SnapshotError { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + match self { + Self::CreateDir { source, .. } => Some(source), + _ => None, + } + } +} + +/// The screenshot folder named by the environment variable `var`, such as [`DEFAULT_DIR_VAR`] or +/// an app's own variable. `None` when the variable is unset or empty, and when `var` is not a +/// usable variable name (empty, or containing `=` or a NUL). +pub fn snapshot_dir(var: &str) -> Option { + if var.is_empty() || var.contains(['=', '\0']) { + return None; + } + dir_from(std::env::var_os(var)) +} + +fn dir_from(value: Option) -> Option { + value.filter(|value| !value.is_empty()).map(PathBuf::from) +} + +/// `builder` with wgpu rendering when `dir` is a screenshot folder, and unchanged when it is +/// `None`. The renderer is created here, so a machine that can't render fails here with +/// [`SnapshotError::Render`] rather than panicking inside the test. +pub fn with_snapshot_renderer(builder: HarnessBuilder, dir: Option<&Path>) -> Result, SnapshotError> { + if dir.is_none() { + return Ok(builder); + } + catch_unwind(AssertUnwindSafe(move || builder.wgpu())).map_err(|payload| SnapshotError::Render(panic_message(payload.as_ref()))) +} + +/// Render the harness's last frame and write it to `{dir}/{name}.png`, creating `dir` when it is +/// missing, and return the file's path. `name` is a plain file name of at most [`MAX_NAME_LEN`] +/// bytes: ASCII letters, digits, `-`, `_`, `.` and `@`, not starting with `.`, and not a Windows +/// device name such as `con` or `nul`. Runs no frames. +pub fn save(harness: &mut Harness<'_, State>, dir: &Path, name: &str) -> Result { + check_name(name)?; + let image = catch_unwind(AssertUnwindSafe(|| harness.render())) + .map_err(|payload| SnapshotError::Render(panic_message(payload.as_ref())))? + .map_err(SnapshotError::Render)?; + std::fs::create_dir_all(dir).map_err(|source| SnapshotError::CreateDir { path: dir.to_owned(), source })?; + let path = dir.join(format!("{name}.png")); + image.save(&path).map_err(|error| SnapshotError::Write { path: path.clone(), message: error.to_string() })?; + Ok(path) +} + +const DEVICE_NAMES: [&str; 24] = [ + "con", "prn", "aux", "nul", "com0", "com1", "com2", "com3", "com4", "com5", "com6", "com7", "com8", "com9", "lpt0", "lpt1", "lpt2", "lpt3", + "lpt4", "lpt5", "lpt6", "lpt7", "lpt8", "lpt9", +]; + +fn check_name(name: &str) -> Result<(), SnapshotError> { + let stem = name.split('.').next().unwrap_or(name); + let valid = !name.is_empty() + && name.len() <= MAX_NAME_LEN + && !name.starts_with('.') + && name.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.' | b'@')) + && !DEVICE_NAMES.iter().any(|device| stem.eq_ignore_ascii_case(device)); + if valid { Ok(()) } else { Err(SnapshotError::InvalidName(name.to_owned())) } +} + +fn panic_message(payload: &(dyn Any + Send)) -> String { + if let Some(message) = payload.downcast_ref::<&str>() { + (*message).to_owned() + } else if let Some(message) = payload.downcast_ref::() { + message.clone() + } else { + "the renderer panicked".to_owned() + } +} diff --git a/crates/ui/src/testing/snapshot/tests.rs b/crates/ui/src/testing/snapshot/tests.rs new file mode 100644 index 000000000..df90f4a85 --- /dev/null +++ b/crates/ui/src/testing/snapshot/tests.rs @@ -0,0 +1,153 @@ +use std::ffi::OsString; +use std::path::{Path, PathBuf}; + +use egui::TexturesDelta; +use egui_kittest::{Harness, HarnessBuilder, TestRenderer}; +use image::{Rgba, RgbaImage}; + +use super::{DEFAULT_DIR_VAR, MAX_NAME_LEN, SnapshotError, dir_from, save, snapshot_dir, with_snapshot_renderer}; + +/// Draws a fixed 3 × 2 image, fails, or panics, without a GPU. +enum Fake { + Image, + Fails, + Panics, +} + +impl TestRenderer for Fake { + fn handle_delta(&mut self, delta: &mut TexturesDelta) { + delta.clear(); + } + + fn render(&mut self, _ctx: &egui::Context, _output: &egui::FullOutput) -> Result { + match self { + Self::Image => Ok(RgbaImage::from_pixel(3, 2, Rgba([10, 20, 30, 255]))), + Self::Fails => Err("no adapter".to_owned()), + Self::Panics => panic!("Failed to create render state"), + } + } +} + +/// A folder of this test's own under the system temp folder, removed first. +fn temp_dir(test: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!("craft-ui-snapshot-{}-{test}", std::process::id())); + _ = std::fs::remove_dir_all(&dir); + dir +} + +fn harness(builder: HarnessBuilder<()>) -> Harness<'static> { + builder.with_size([60.0, 30.0]).build_ui(|ui| _ = ui.label("Export")) +} + +fn assert_png(path: &Path, width: u32, height: u32) { + let bytes = std::fs::read(path).unwrap(); + assert!(bytes.starts_with(b"\x89PNG\r\n\x1a\n"), "{}", path.display()); + let image = image::load_from_memory_with_format(&bytes, image::ImageFormat::Png).unwrap(); + assert_eq!((image.width(), image.height()), (width, height)); +} + +#[test] +fn an_unset_or_empty_variable_is_no_folder() { + assert_eq!(dir_from(None), None); + assert_eq!(dir_from(Some(OsString::new())), None); + assert_eq!(dir_from(Some("shots".into())), Some(PathBuf::from("shots"))); + assert_eq!(snapshot_dir("CRAFT_UI_SNAPSHOT_DIR_TEST_UNSET_8F3A"), None); + assert_eq!(DEFAULT_DIR_VAR, "CRAFT_UI_SNAPSHOT_DIR"); +} + +#[test] +fn an_unusable_variable_name_is_no_folder() { + for var in ["", "A=B", "A\0B", "="] { + assert_eq!(snapshot_dir(var), None, "{var:?}"); + } +} + +#[test] +fn the_caller_names_the_variable() { + // Cargo sets this one for every test run. + assert_eq!(snapshot_dir("CARGO_MANIFEST_DIR"), Some(PathBuf::from(env!("CARGO_MANIFEST_DIR")))); +} + +#[test] +fn no_folder_leaves_the_renderer_alone() { + let builder = with_snapshot_renderer(Harness::builder().renderer(Fake::Image), None).unwrap(); + let mut harness = harness(builder); + // The fake renderer is still the one drawing: no wgpu renderer replaced it. + assert_eq!(harness.render().unwrap().dimensions(), (3, 2)); +} + +#[test] +fn save_writes_one_png_named_after_the_screen() { + let dir = temp_dir("save").join("nested"); + let mut harness = harness(Harness::builder().renderer(Fake::Image)); + let path = save(&mut harness, &dir, "export-light@2x").unwrap(); + assert_eq!(path, dir.join("export-light@2x.png")); + assert_png(&path, 3, 2); + assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 1); + _ = std::fs::remove_dir_all(dir.parent().unwrap()); +} + +#[test] +fn save_runs_no_frames() { + let dir = temp_dir("frames"); + let mut harness = Harness::builder().renderer(Fake::Image).build_ui_state(|_, frames: &mut u32| *frames += 1, 0); + let before = *harness.state(); + save(&mut harness, &dir, "frames").unwrap(); + assert_eq!(*harness.state(), before); + _ = std::fs::remove_dir_all(dir); +} + +#[test] +fn save_refuses_names_that_leave_the_folder() { + let dir = temp_dir("names"); + let mut harness = harness(Harness::builder().renderer(Fake::Image)); + let long = "a".repeat(MAX_NAME_LEN + 1); + for name in [ + "", ".", "..", "../up", "a/b", "a\\b", "/abs", "C:x", ".hidden", "con", "NUL", "com1.x", "lpt9", "COM0", "lpt0.png", "a b", "é", "a\0", &long, + ] { + assert!(matches!(save(&mut harness, &dir, name), Err(SnapshotError::InvalidName(_))), "{name:?}"); + } + assert!(!dir.exists()); + assert!(save(&mut harness, &dir, &"a".repeat(MAX_NAME_LEN)).is_ok()); + _ = std::fs::remove_dir_all(dir); +} + +#[test] +fn a_render_failure_is_an_error_and_writes_nothing() { + let dir = temp_dir("render"); + for fake in [Fake::Fails, Fake::Panics] { + let mut harness = harness(Harness::builder().renderer(fake)); + assert!(matches!(save(&mut harness, &dir, "screen"), Err(SnapshotError::Render(_)))); + } + assert!(!dir.exists()); +} + +#[test] +fn a_folder_that_cannot_be_made_is_an_error() { + let dir = temp_dir("blocked"); + std::fs::create_dir_all(&dir).unwrap(); + let file = dir.join("file"); + std::fs::write(&file, b"").unwrap(); + let mut harness = harness(Harness::builder().renderer(Fake::Image)); + let error = save(&mut harness, &file.join("sub"), "screen").unwrap_err(); + assert!(matches!(error, SnapshotError::CreateDir { .. }), "{error}"); + _ = std::fs::remove_dir_all(dir); +} + +#[test] +fn a_folder_sets_up_wgpu_and_saves_the_frame() { + let dir = temp_dir("wgpu"); + let builder = match with_snapshot_renderer(Harness::builder(), Some(&dir)) { + Ok(builder) => builder, + Err(SnapshotError::Render(message)) => { + eprintln!("skipped: this machine can't render with wgpu ({message})"); + return; + } + Err(error) => panic!("{error}"), + }; + let mut harness = harness(builder); + harness.run(); + let path = save(&mut harness, &dir, "label").unwrap(); + assert_png(&path, 60, 30); + _ = std::fs::remove_dir_all(dir); +}