Index of every page on this site: llms.txt
All skills
domesticmouse avatar

/egui-testing-infrastructure

@606a5d5
Run it yourself

Use this skill when running, writing, debugging, or auditing tests, mutation coverage (cargo-mutants), benchmarks, corpora, fuzzers, or CI gates in an engine-first Rust and egui application: fast nextest loops, cargo-mutants configuration (.cargo/mutants.toml), GPU test serialization (gpu_lock), real-file corpus oracles and floor ratchets, panic_hunt adversarial command fuzzing, offscreen UI snapshots (egui_kittest), MCP acceptance tests, performance budgets (xtask perf), and scorecard generation (xtask scorecard).

  • 2 files
  • 20.7 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/domesticmouse/skills/egui-testing-infrastructure

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈137 tokens for metadata: the name and description. ≈3.3k when used: this file. ≈1.9k more on demand in 1 file.

Description uses 6.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈550 characters, or 6.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Testing, Corpus, Performance & Scorecard Infrastructure (egui & Rust)

An engine-first multi-crate egui application enforces quality through a 7-tier verification architecture. Use this skill whenever you write tests, run verification gates, update corpus/parity floors, benchmark hot paths, or update docs/scorecard.md.

Related skills:

  • egui-app-architecture — L0–L7 crate layering, Testkit rules, and lint/profile configuration.
  • egui-app-runner — Running the desktop app, CLI, offscreen snapshots, and live MCP/TCP control servers.
  • egui-command-engine — Authoring CommandSpecs validated by panic_hunt and parity checks.
  • egui-cow-document-model — Copy-on-write chunks, snapshot undo/redo history, and exhaustive format conversion.

1. The 7 Verification Tiers

Tier Scope & Mechanism Primary Files & Commands
1. Compile-Time & Static Gates L0–L7 acyclic layering (cargo xtask layers), wasm32 check (cargo xtask wasm), unsafe_code = "forbid", #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, ...)] across all workspace crates (relaxed in tests via clippy.toml), and exhaustive struct destructuring in crates/format/src/convert.rs. xtask/src/layers.rs, clippy.toml, crates/format/src/convert.rs
2. Unit, Property, Mutation & Format Fuzz Tests Domain unit tests across supported data representations, cargo-mutants mutation coverage (0 missed mutants), proptest! suites (COW chunks/tiles, spatial regions, codecs, file formats), deterministic synthetic document generators (testgen), truncation/corruption sweeps, and cargo-fuzz targets (crates/*/fuzz/). crates/*/src/, .cargo/mutants.toml, crates/*/fuzz/
3. CPU vs. GPU Rendering Parity CPU reference renderer vs. wgpu WGSL shader output parity within a bounded tolerance. Every test using a wgpu device or egui_kittest GPU harness must hold let _gpu = testkit::gpu_lock(); on its first line. crates/testkit/src/gpu.rs, .config/nextest.toml
4. Pinned Real-File Oracles (corpus) Gitignored real-world files in corpus/ fetched at pinned commits and verified against xtask/*.sha256 manifests. Asserts monotonically increasing oracle pass and export round-trip floors, strict structural validation, and mutation safety. xtask/src/corpus_pins.rs, crates/io/tests/corpus.rs
5. Command Registry & panic_hunt crates/engine/tests/panic_hunt.rs fuzzes every registered CommandSpec against adversarial JSON params on its own thread with a per-command deadline (e.g., 4 s) and a custom std::panic::set_hook counter that catches even panics swallowed by Session::execute's catch_unwind. crates/engine/tests/panic_hunt.rs
6. Headless UI (egui_kittest) & MCP Acceptance Widget/canvas tests in crates/ui-egui, offscreen wgpu PNG snapshots (examples/snapshot.rs), menu parity ratchet (parity::FLOOR), and end-to-end agent workflows driven over in-memory rmcp transport (crates/automation/tests/agent_tasks.rs). crates/ui-egui/src/parity.rs, crates/ui-egui/examples/snapshot.rs, crates/automation/tests/agent_tasks.rs
7. Performance Budgets & Scorecard Release benches report p50/p95/max ms, in-process peak RSS (testkit::perf::RssSampler + Linux VmHWM), and GPU bytes against perf/budgets.toml and perf/baseline.json. cargo xtask scorecard compiles budgets, corpus floors, checklists (scorecard/*.toml), and unread-preference audits into docs/scorecard.md. crates/testkit/src/perf.rs, xtask/src/perf.rs, xtask/src/scorecard.rs, perf/budgets.toml

2. Fast Local Iteration vs. Pre-Finish Gate

Fast Iteration Loops

Avoid compiling all workspace test binaries and examples while iterating:

# 1. Run unit + integration tests for a single crate (skips compiling examples and doctests)
cargo test -p <crate> --lib --tests

# 2. Run a single integration test binary
cargo test -p <crate> --test <test_file_stem>

# 3. Run parallel process-per-test execution via nextest (caps concurrent GPU tests)
cargo nextest run -p <crate> --lib --tests

# 4. If working alongside parallel agents, isolate your build directory
CARGO_TARGET_DIR=target/agent-<name> cargo test -p <crate> --lib --tests

Mandatory Pre-Finish Verification Gate

Before finishing a task, run the checks corresponding to the crates you touched:

# Always run on touched crates:
cargo test -p <crates>
cargo clippy -p <crates> --all-targets -- -D warnings
cargo xtask layers

# If you touched L0–L6:
cargo xtask wasm

# If you added or modified engine commands:
cargo test -p <app>-engine --test panic_hunt -- --ignored
cargo xtask parity

# If you touched format parsers, io, rendering, or persistence crates:
CARGO_PROFILE_RELEASE_LTO=false CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 \
  cargo xtask test-corpus --changed

# If you touched a hot path, fixed a scorecard item, raised a floor, or wired a preference:
cargo xtask perf --quick
cargo xtask scorecard
cargo xtask scorecard --check

3. Critical Rules When Writing Tests

  1. Always Hold gpu_lock() in GPU Tests: Multiple concurrent wgpu devices in one process crash Windows WARP (STATUS_ACCESS_VIOLATION), Mesa llvmpipe/RADV, and multi-ICD Vulkan. Under cargo test (multi-threaded within one process), every test creating a wgpu device or egui_kittest GPU harness must acquire testkit::gpu_lock() on its first line:
    #[test]
    fn my_gpu_test() {
        let _gpu = testkit::gpu_lock();
        // build wgpu device or egui_kittest harness...
    }
    If you add a new GPU test module in ui-egui, ensure its name matches the gpu test-group filter in .config/nextest.toml.
  2. Isolate OS Side Effects in Tests & Fuzzers: Commands that trigger external OS side effects (such as physical printing, system dialogs, or network/external process spawns) must be stubbed or disabled in dry-run/fuzz mode (e.g., calling a disable_*() hook or setting a NO_*=1 environment guard) before running panic_hunt.
  3. Test Full Domain Representations & Edge Cases: Domain algorithms and commands should be tested across all supported precision modes, coordinate spaces, and entity variants where applicable.
  4. Every Crash Fix Requires a Synthetic Regression Test: Never commit large external corpus files into the repository. Reproduce any corpus or fuzz crash with a small, deterministic synthetic test in the crate (e.g., crates/io/tests/corpus_regressions.rs) that failed or panicked before the fix.
  5. Ratchets Only Move Up: Never lower parity::FLOOR in crates/ui-egui/src/parity.rs or any pass_floor / roundtrip_floor in crates/io/tests/corpus.rs. When your change improves pass counts, raise the floor and regenerate docs/scorecard.md via cargo xtask scorecard.
  6. Mutation Testing (cargo-mutants) & Headless egui_kittest Idioms:
    • Prerequisite Installation: Ensure cargo-mutants is installed (cargo install --locked cargo-mutants) and documented whenever onboarding or writing verification instructions.
    • Sequential cargo mutants Runs & --timeout 120: On a warm target/ cache, the unmutated baseline test finishes in < 2s, causing cargo-mutants to auto-set a 20s test timeout. Running multiple cargo test or cargo mutants jobs concurrently causes linker/lock contention that triggers false TIMEOUT results. Always run cargo mutants --in-place sequentially (one crate at a time after all cargo test builds finish) with --timeout 120.
    • Sandboxed Offline Execution on macOS (Optional Agent Workaround): In restricted agent sandboxes where /tmp (/private/tmp) or ~/.cargo cannot be canonicalized (Operation not permitted), seed ~/.cargo/registry once via APFS copy-on-write (cp -cR) into a writable scratch directory and point CARGO_HOME and TMPDIR there:
      CARGO_HOME=<scratch>/cargo-home TMPDIR=<scratch>/tmp \
        cargo mutants --in-place --timeout 120 -d <crate_dir> -o <scratch>/mutants-<name> -C --offline
      (Note: Cargo hashes the CARGO_HOME path into target/debug/.fingerprint/, so if you seed target/ directories across isolated builds using cp -cR, keep CARGO_HOME identical across them.)
    • Headless eframe::App Verification via egui_kittest::Harness::new_eframe: Add egui_kittest = { version = "0.37", features = ["eframe"] } to [dev-dependencies] and boot the full app headlessly via Harness::new_eframe(|_cc| MyApp::default()). Once Harness::new_eframe tests query rendered labels (harness.get_by_label(...)), simulate clicks (.click()), and press keys (harness.key_press(egui::Key::...)), remove "<impl eframe::App for MyApp>::ui" from .cargo/mutants.toml exclude_re so cargo-mutants verifies ui() and panel UI methods directly, leaving only pure pixel-coordinate Painter helpers (e.g., render_canvas, paint_viewport) excluded until offscreen GPU snapshot tests come online.
    • egui::Scene::show Closure Borrow Split (E0500 Prevention): Passing &mut self.view.scene_rect directly to egui::Scene::new().show(ui, &mut self.view.scene_rect, |ui| { ... }) borrows self.view.scene_rect for the entire .show(...) call, preventing the inner closure from calling methods on self. Because egui::Rect is Copy, copy let mut scene_rect = self.view.scene_rect; before Scene::show, pass &mut scene_rect, and assign self.view.scene_rect = scene_rect; afterward.
    • Configure .cargo/mutants.toml with Exact --list Mutant Names: exclude_re matches the generated mutant description from cargo mutants --list, not raw Rust syntax:
      • To exclude fn main(), match "replace main" (not "fn main").
      • To exclude a trait method like eframe::App::ui (before egui_kittest is introduced), match "<impl eframe::App for MyApp>::ui" (not "impl eframe::App for MyApp::ui").
      • Set copy_target = true in .cargo/mutants.toml and gitignore mutants.out/ and mutants.out.old/.
    • Avoid ..Default::default() Inside Untested Entrypoints (fn main): cargo-mutants (v27.1+) generates StructField (delete field <field> from struct <Struct> expression) mutants on struct literals using ..Default::default(), and StructField mutants bypass exclude_re filtering. In fn main(), initialize eframe::NativeOptions via let mut options = eframe::NativeOptions::default(); options.viewport = ...; rather than struct update syntax so main() does not produce an un-excludable missed mutant.
    • Delegate impl Default / fn new Logic to Named Methods: cargo-mutants skips impl Default (fn default) and fn new completely to avoid infinite recursion with Default::default(). Put non-trivial initialization or state-reset logic in a named method (e.g., pub fn reset_view(&mut self)) called by Default::default() so cargo-mutants can mutate and verify it.
    • Designing Arithmetic, Boolean & Match-Arm Tests for Zero Missed Mutants:
      • Arithmetic (Pos2, Vec2, Rect, TSTransform, hypot): Never test at 0.0 or 1.0 coordinates/factors (where 0.0 - x == 0.0 / x or x * 1.0 == x / 1.0). Use non-zero, asymmetric values (e.g., pos2(100.0, 60.0), vec2(16.0, 10.0), zoom_factor = 2.0, and 3-4-5 right triangles at non-zero offsets) so every +/-/*///% mutant produces a distinct float caught by assert_eq!.
      • Compound Booleans (&& vs. || and !): For && predicates like self.is_item_visible(item) && item.contains_point(pt), include negative tests for both (true, false) and (false, true). For multi-branch || search filters (e.g., matches_query checking name || category || tag), include one query that matches exclusively via each branch plus a non-matching query so every || -> && and ! negation mutant is caught.
      • Exhaustive match Arms: Assert each enum variant's behavior in isolation so no match branch (e.g., in z_order(), color(), label(), or visibility predicates) can be deleted or collapsed.
    • Rust 1.97+ float_literal_f32_fallback Warning with egui::Stroke::new: Because Stroke::new takes generic impl Into<f32>, untyped float literals like Stroke::new(2.0, color) trigger #[warn(float_literal_f32_fallback)] on rustc 1.97+. Use explicit _f32 suffixes (Stroke::new(2.0_f32, color)) or typed f32 variables.

4. Deep-Dive Reference

For detailed workflows on:

  • Fetching, authoring, and debugging real-file corpora (oracle_diff, local corpus testing, pin bumps)
  • Adding performance scenarios (testkit::perf, perf/budgets.toml, perf/baseline.json)
  • Updating scorecard/*.toml and understanding CI matrix optimizations (ci.yml, perf-nightly.yml)

Read corpus-perf-and-ci-reference.md.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 606a5d5. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago

README badge

README badge for domesticmouse/skills/egui-testing-infrastructure