Crate rightkit_qa 

rightkit-qa: the Rust QA harness for Right Suite apps (macOS and Windows).

This crate and the Node packages @rightkit/qa / @rightkit/qa-chrome are two runners that coexist; neither replaces the other. This one drives native Rust, Tauri and engine targets (the real macOS app, the Windows WebView2 app through its in-app control server, the engine) with no Node or Python runtime. The Node packages own browser-page QA (Chrome for Testing plus a CDP page driver, evidence, pane/frame/paint checks). See the ownership table in this crate’s README.

Targets:

• engine: engine::EngineTarget drives the app engine over CLI words and the framed stdio sidecar.
• app UI: control::Control launches the real Tauri app hidden/backgrounded and drives it through the in-app server (embedded, feature control).
• Chrome: browser feature, through rightkit-browser.
• Android: android::AndroidSession (feature android) installs and launches the dev APK on an emulator or USB device through adb, records logcat by pid, and forwards the in-app control server to a loopback port.

Scenarios are declarative TOML (scenario) run by the CLI, or plain Rust integration tests wrapped by harness::Harness::scenario (tier gating, requires-skip, per-scenario evidence, orphan check). Knobs reach managed (rightkit cargo) test runs through cargo features plus a settings::Settings file, never the caller’s environment.

Run kinds and evidence: a run is functional (the default: clicks, state and text, no screenshots, no recordings) or visual (the audit-visual run that captures screens), see storage::RunKind. Each run writes into its own directory under the managed runs root and retention prunes only directories that carry the run marker.

Validators: media (WAV stats, PNG/frame non-uniformity) and loudness (BS.1770 integrated loudness, range, true peak), pure Rust except where a compressed container needs a caller-supplied ffmpeg. mock::MockServer stands in for paid providers.

Re-exports

pub use util::Error;

pub use util::Result;

Modules

a11y

Accessibility evidence for UI scenarios: contrast, focus indicator, role/name assertions. Accessibility evidence for UI scenarios: text contrast (WCAG 2.x), the keyboard-focus indicator, and role/name assertions over the control server’s ax nodes.

audio

Audio is always muted during QA. Apps are told through RIGHTKIT_QA_MUTE=1 and Chrome gets --mute-audio; on macOS the system output can additionally be muted for the run and restored afterwards (opt-in, restored on drop). Playback is asserted from DOM/engine state, never from sound.

binary

Find the dev build of the app under test, wherever the build put it.

check

Assertions over a step’s JSON result: a small path syntax (a.b[0].c, list[*].name) plus value predicates, and ${...} interpolation of saved results into later steps.

config

Per-app config: rightkit-qa.toml, the TOML replacement for right-qa.config.mjs.

control

Drive the real Tauri app through the in-app control server (embedded, feature control).

engine

Black-box driving of an app’s engine binary: one-shot CLI words and the framed stdio sidecar protocol (newline-delimited JSON through rightkit-sidecar). Nothing mocks the engine.

evidence

A receipt that names a file without hashing it is a claim, not evidence. Every artifact is hashed when recorded, a check may only reference hashed artifacts, and the bundle can be re-verified against the filesystem.

frametrace

Owned PresentMon frame-timing sessions (#433): start a trace for one process, confirm it is recording, stop it and summarise the frame times. PresentMon is an external Windows tool; the caller supplies its path. The stats come from its CSV output (MsBetweenPresents and, when present, Dropped). A trace that is dropped unstopped kills its PresentMon child.

guard

The guard that keeps the in-app QA control surface out of builds that must not carry it.

harness

Scenario wrapper for plain Rust integration tests (#[test] fn x() { h.scenario(...) }).

http

Minimal blocking HTTP/1.1 client over loopback TcpStream. Every call has an explicit deadline: a request that never answers is a failed step, not a hang.

inplace

Install in place at ONE fixed path, with a persistent <name>.previous beside it.

installed

QA never launches an installed app. refuse_installed refuses any app bundle or executable under an installed-apps location unless installed-QA mode is on.

interactive

Run a journey in the logged-on user’s interactive session from a session-0 (SSH) process. Run a journey in the logged-on user’s interactive desktop session from a session-0 process (an SSH logon or a service on Windows), through a ONE-SHOT Task Scheduler task.

lock

Run lock: one QA run per lock directory. A lock is reclaimed only when its owner is provably gone (pid dead, or the pid now belongs to a different process); a live owner is never displaced however long its run takes. Age applies only to a lock directory that never received an owner record (a crash between mkdir and the owner write).

loudness

Loudness in pure Rust: ITU-R BS.1770-4 integrated loudness (K-weighting, 400 ms blocks with 75 % overlap, -70 LUFS absolute and -10 LU relative gates), EBU Tech 3342 loudness range, sample peak and 4x-oversampled true peak.

media

Content validators for generated artifacts: a file existing is not a result. Pure Rust for WAV/PNG/loudness; ffmpeg (a caller-supplied binary path) only where a compressed container must be decoded. See also crate::loudness.

mock

Local HTTP mock for PAID providers: paid-tier scenarios assert the exact requests the product would send, and never make a billed call.

page

Page-side QA primitives that run through Control::eval (or any evaluator): frame-scoped selectors, painted-not-acknowledged timing, and active-pane geometry. These port the frames, paint, and panes modules of the TS package; the scripts are plain function bodies (return ...).

process

Owned processes: every child is spawned through rightkit-child-process (process group / Job Object), registered with a Tracker, and killed by recorded pid only. Nothing here ever matches processes by name for killing.

retention

Evidence retention for finished QA runs.

scenario

Declarative scenarios (*.scenario.toml) and the step executor.

settings

Test settings that survive rightkit cargo test.

storage

Managed QA run storage: shared marker, retention, and cross-language lock protocol.

suite

A QA run: select scenarios by tier, take the run lock, create the isolated workspace, run scenarios sequentially, sweep orphans, and write hashed evidence.

tart

Tart clean-machine VM lifecycle for macOS QA (#442): clone a base image, run it (headless or with a window), reach it over ssh, copy files in and out, and destroy it. Wraps the tart, ssh and scp command lines; the caller supplies the tart binary path. Bounded commands run through run_owned, so they are tracked and killed on timeout. A VM that is dropped without CleanVm::destroy is stopped and deleted on a best-effort basis.

userdata

QA runs never touch real user data.

util

Shared error type and small helpers.

workspace

An isolated, reliably removable home for one QA run: own data dir (so the app takes its own single-instance lock), own evidence dir, retrying disposal that reports what it could not remove, and a sweep for crashed runs.