mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-17 15:55:14 +00:00
craft-ui: testing gains shared input steps and a review screenshot folder (#1385)
This commit is contained in:
1 parent
d55f0505c9
commit
05d5350511
7 files changed
+684
-3
No files matched your search
@@ -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]
|
||||
|
||||
+34
-1
@@ -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<State>` 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.
|
||||
|
||||
|
||||
@@ -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<State>(harness: &mut Harness<'_, State>, events: impl IntoIterator<Item = Event>) {
|
||||
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<State>(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<State>(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<State>(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<State>(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<State>(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<State>(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<State>(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<State>(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)]);
|
||||
}
|
||||
@@ -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<Vec<Event>>,
|
||||
modifiers: Vec<Modifiers>,
|
||||
}
|
||||
|
||||
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<Pos2> {
|
||||
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]);
|
||||
}
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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<PathBuf> {
|
||||
if var.is_empty() || var.contains(['=', '\0']) {
|
||||
return None;
|
||||
}
|
||||
dir_from(std::env::var_os(var))
|
||||
}
|
||||
|
||||
fn dir_from(value: Option<OsString>) -> Option<PathBuf> {
|
||||
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<State>(builder: HarnessBuilder<State>, dir: Option<&Path>) -> Result<HarnessBuilder<State>, 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<State>(harness: &mut Harness<'_, State>, dir: &Path, name: &str) -> Result<PathBuf, SnapshotError> {
|
||||
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::<String>() {
|
||||
message.clone()
|
||||
} else {
|
||||
"the renderer panicked".to_owned()
|
||||
}
|
||||
}
|
||||
@@ -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<RgbaImage, String> {
|
||||
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);
|
||||
}
|
||||
Reference in new issue
Block a user