Struct ScreenshotTest 

pub struct ScreenshotTest<P: PluginExport> { /* private fields */ }

Builder for a screenshot regression test.

Construct via the screenshot! macro: screenshot!(Plugin, "screenshots/main.png"). The path is the committed reference PNG location - relative to the calling crate’s Cargo.toml directory, or absolute. There’s no implicit directory and no auto-derived filename; every test names its own reference.

Lifecycle: P::create() -> init() -> optional state_file load -> optional set_param shortcuts -> optional setup closure -> render. Matches PluginDriver’s ordering so the same builder vocabulary works for both audio and GUI tests.

Examples

#[test]
fn screenshot() {
    truce_test::screenshot!(Plugin, "screenshots/default.png").run();
}

// State-dependent: tweak params before rendering.
#[test]
fn screenshot_max_gain() {
    truce_test::screenshot!(Plugin, "screenshots/max_gain.png")
        .set_param(MyParamId::Gain, 1.0)
        .run();
}

// Pre-saved state from the standalone host's Cmd+S.
#[test]
fn screenshot_evening() {
    truce_test::screenshot!(Plugin, "screenshots/evening.png")
        .state_file("test_states/evening.pluginstate")
        .run();
}

Implementations

impl<P: PluginExport> ScreenshotTest<P>

pub fn setup<F: FnOnce(&mut P) + 'static>(self, f: F) -> Self

Mutate the plugin between P::create() / init() and the render. Use this to set custom (non-param) state, drive a process() block to populate meters, etc.

Composes with Self::state_file (state loads first) and Self::set_param (shortcuts apply first); the closure runs last.

pub fn set_param(self, id: impl Into<u32>, normalized: f64) -> Self

Set a parameter to a normalized [0, 1] value before the render. Equivalent to a setup(|p| p.params().set_normalized(id, v)) closure but written as one builder call. Multiple .set_param calls compose; they apply after .state_file (if any) and before .setup.

pub fn state_file<S: Into<PathBuf>>(self, path: S) -> Self

Read a .pluginstate file (the standalone host’s Cmd+S save format) and apply it via plugin.load_state(&bytes) after init and before any set_param overrides / setup closure. Path is resolved relative to the crate’s manifest dir, or used as-is if absolute.

Panics

Panics if the file cannot be read (missing path, permission error, etc.) - the test failure points at the resolved path so it’s easy to fix the call site.

pub fn tolerance(self, t: usize) -> Self

Max allowed differing-pixel count. 0 is strict equality; bump for cross-machine antialiasing tolerance.

Composes with Self::pixel_threshold: a pixel only counts toward this budget if its max channel delta exceeds the threshold, so sub-perceptual AA wobble doesn’t have to inflate tolerance to numbers that would also hide real regressions.

pub fn pixel_threshold(self, d: u8) -> Self

Per-pixel “different enough to count” threshold. A pixel only adds to the Self::tolerance budget if at least one of its R/G/B/A channels differs from the reference by more than this. 0 = strict (any byte difference counts).

Practical values: 1–3 ignore tiny rasterizer / filter drift between machines without masking real visual changes; 8+ starts to hide things a human would notice.

pub fn scale(self, scale: f64) -> Self

Override the render scale used for the screenshot. Without this, truce_core::screenshot::DEFAULT_SCREENSHOT_SCALE is used so the reference PNG renders at the same physical dimensions on every host. Set this when you specifically want to bake a 1× / 3× / fractional reference; the same value must be passed to cargo truce screenshot --scale when (re)generating the baseline.

pub fn run(self)

Build the plugin (with state_file/set_param/setup applied if present, in that order), render, and compare against the reference at the supplied path:

• No reference → panic, pointing at cargo truce screenshot --out <ref_path> to create one.
• Match within tolerance → pass silently.
• Mismatch → panic with both PNG paths and the cp command to accept the new render as the baseline.