Struct Driver 

pub struct Driver<D: Document> {
    pub runtime: Runtime<D>,
    /* private fields */
}

Drives a Runtime headless. See the module docs.

Fields

runtime: Runtime<D>

Implementations

impl<D: Document> Driver<D>

pub fn new(runtime: Runtime<D>) -> Self

A 1280×800 point screen at time 0, with grey screenshots.

pub fn with_renderer(runtime: Runtime<D>, renderer: Renderer) -> Self

Driver::new rendering screenshots with renderer (e.g. Renderer::wgpu: real pixels, or grey when there is no GPU).

pub fn renderer(&self) -> &Renderer

What screenshots are rendered with.

pub fn into_runtime(self) -> Runtime<D>

Stop driving; the runtime is handed back (e.g. to Runtime::abandon it).

pub fn ctx(&self) -> &Context

pub fn set_screen(&mut self, width: f32, height: f32)

pub fn pixels_per_point(&mut self, ppp: f32)

Draw as on a display with ppp pixels per point (2 on a Retina display), from the next frame on. Values that are not finite or not positive are ignored; others are clamped to 0.25–8.

pub fn time(&self) -> f64

Virtual seconds since the start.

pub fn frames(&self) -> u64

Frames run so far.

pub fn is_closed(&self) -> bool

The app closed its window.

pub fn push_event(&mut self, e: Event)

Queue raw input for the next frame (it also wakes the loop).

pub fn set_screenshots(&mut self, deliver: bool)

Whether screenshots are delivered (on by default). Off, the loop behaves like a window that is covered or on a locked screen: capture requests are dropped.

pub fn set_hidden(&mut self, hidden: bool)

Minimize the window (or show it again). Hidden, a frame runs Runtime::logic with no egui pass, the way eframe treats a minimized or covered window, then the runtime’s Runtime::hidden_pass for pending debugger work; other input waits for the next shown frame. A raise from the app (Focus, Minimized(false), Visible(true)) shows it again.

pub fn is_hidden(&self) -> bool

Whether the window is hidden (Driver::set_hidden).

pub fn request_close(&mut self)

Ask to close the window, as the window’s close button does.

pub fn native_menu_pick(&mut self, id: &str)

Pick id in the OS menu bar, as the native menu (feature native-menu) reports a click or a key equivalent. It runs in the next frame’s Runtime::logic under the same rules: ignored while a dialog is open, or while a text field has the keyboard and the command’s shortcut belongs to the field.

pub fn drop_files( &mut self, paths: impl IntoIterator<Item = impl Into<PathBuf>>, )

Drop files on the window in the next frame, as the OS reports a drag and drop.

pub fn forward_launch(&mut self, forwarded: Forwarded)

A second launch of the app forwards its arguments, as with App::single_instance. The next frame opens its first file.

pub fn frame(&mut self) -> FullOutput

Run one frame now, whether or not one was asked for.

pub fn record(&mut self, f: impl FnOnce(&mut Self)) -> MotionRecorder

Run f while recording motion for the motion gate: values animated through ashlar_ui::motion and, each frame, the automation elements’ rects and the frames asked for. Check the result with MotionRecorder::check.

let rec = d.record(|d| drop(d.run_ui("click overlays.open\nwait 1")));
let report = rec.check(&MotionRules::default());
assert!(report.is_clean(), "{report}");

pub fn advance(&mut self, secs: f64) -> u64

Let secs of virtual time pass, running every frame that is asked for (at most one per 1/120 s, like a display would). Returns the frames run.

pub fn settle(&mut self, max: u64) -> u64

Run frames until none is asked for (at most max); returns how many ran. Timers further than horizon seconds away do not count as pending.

pub fn replay(&mut self, path: impl AsRef<Path>) -> Result<usize>

Play a recording made with ASHLAR_RECORD or Runtime::record_to into this driver (normally a fresh one for the same app): each recorded frame runs at its time, with its screen, input events and control requests (their replies are dropped). Returns the number of frames run. See crate::record.

pub fn request(&mut self, method: &str, params: Value) -> Reply

Send a control request (as the control port would) and run frames until it is answered: one frame for the request, then only the frames something asks for, on the virtual clock (a request that needs frames nobody asks for is reported, not papered over by polling).

pub fn call(&mut self, method: &str, params: Value) -> Result<Value, String>

Driver::request expecting success.

pub fn run_ui(&mut self, script: &str) -> Result<Report, ScriptError>

Run a .ui script (the ashlar-debug batch language) on this app, in process: no port, no thread. sleep N and wait N let virtual time pass, so a script gives the same steps on every run.

pub fn scene(&mut self, name: &str) -> Result<(), String>

Apply the app’s scene name (crate::App::scene) through the ui.scene control method, then run the frames it asks for.

pub fn assert_snapshot(&mut self, name: &str) -> Result<SnapshotOutcome, String>

Compare a screenshot of the whole window with the golden snapshot name in tests/snapshots (see ashlar_debug::snapshot): exact by default; on a mismatch it writes <name>-new.png and <name>-diff.png and returns the reason. ASHLAR_UPDATE_SNAPSHOTS=1 records the baseline instead. A baseline from another adapter, or a run with no GPU renderer, is skipped with a printed note.

pub fn check_snapshot( &mut self, name: &str, snapshots: &Snapshots, target: Option<Value>, ) -> Result<SnapshotOutcome, String>

Driver::assert_snapshot with explicit settings, of target (a control-protocol target, e.g. json!({"id": "list"})) or the whole window.

Trait Implementations

impl<D: Document> Transport for Driver<D>

Available on non-WebAssembly only.

fn call(&mut self, method: &str, params: Value) -> Result<Value, ControlError>

Call one method and return its result, or the app’s error.

fn pause(&mut self, ms: u64)

Let ms milliseconds pass (sleep, wait <ms>). The default waits on the wall clock.

fn set_timeout(&mut self, _timeout: Duration)

Longest wait for one reply, where that means something (a socket).

fn port(&self) -> Option<u16>

The TCP port, when there is one.