Sprimo/docs/TAURI_RUNTIME_TESTING.md

Tauri Runtime Behavior Testing Workflow

Date: 2026-02-13

Purpose and Scope

This document defines strict testing and evidence requirements for sprimo-tauri runtime behaviors. It complements docs/QA_WORKFLOW.md and applies to all Tauri runtime behavior issues.

Prerequisites

• Windows environment for primary runtime validation.
• Workspace up to date.
• UI dependencies installed:
  • just install-tauri-ui

Execution Modes

1. Workspace Mode (Required Now)

Run and validate from the repository workspace:

just build-tauri-ui
just check-tauri
just check-runtime-core
just run-tauri

2. Packaged Mode (Required Once Packaging Exists)

When sprimo-tauri packaging automation is implemented, repeat the runtime checklist against the packaged artifact and attach equivalent evidence in the issue.

Strict Verification Gate

An issue touching Tauri runtime behaviors must satisfy all requirements before Closed:

1. Command evidence recorded:

• cargo check -p sprimo-tauri
• cargo check -p sprimo-runtime-core
• just build-tauri-ui
• just run-tauri smoke result
• just qa-validate

2. Visual evidence recorded:

• before screenshot(s)
• after screenshot(s)

3. Runtime contract evidence recorded:

• current_state invoke command returns valid structured payload.
• load_active_sprite_pack invoke command returns manifest/atlas payload.
• runtime:snapshot event is observed after command application.

4. API behavior evidence recorded:

• /v1/health and /v1/state behavior validated against tauri runtime.
• /v1/command and /v1/commands validated with auth behavior.

5. Docs synchronized:

• issue lifecycle updated
• relevant docs updated when behavior or expectations changed

Runtime Behavior Checklist

1. Launch tauri runtime via just run-tauri.
2. Verify sprite renders in the tauri window.
3. Verify animation advances over time.
4. Send PlayAnimation command and verify clip switch is reflected.
5. Send SetTransform.scale and verify rendered sprite scale changes without clipping:

• at scale >= 1.0, full sprite remains visible (no missing upper region)
• runtime auto-fits window size to sprite frame size and keeps bottom-center visually stable

6. Verify missing animation fallback:

• unknown animation name falls back to idle or first available clip.

7. Verify sprite-pack loading:

• valid selected pack loads correctly
• invalid pack path failure is surfaced and runtime remains alive

8. Verify frameless window drag behavior:

• left-mouse drag moves the window
• window remains non-resizable
• moved position is reflected in runtime snapshot state (x, y) and persists after restart

9. Verify debug-overlay visibility control:

• default startup behavior follows frontend.debug_overlay_visible config
• debug_overlay_visible/set_debug_overlay_visible invoke commands toggle panel at runtime
• toggle state persists after restart

10. Verify Windows tray/menu controls:

• tray left-click opens menu without directly toggling visibility
• Show/Hide toggles window visibility and persists state
• Always on top toggles top-most behavior and persists state
• Debug overlay toggles panel visibility and persists state
• Quit exits cleanly and preserves current persisted visibility/top-most/debug settings

API + Runtime Contract Checklist

1. Validate health endpoint:

• GET /v1/health returns version/build/capabilities.

2. Validate authenticated state endpoint:

• GET /v1/state requires bearer token.

3. Validate command endpoint:

• POST /v1/command accepts valid command envelope.

4. Validate batch endpoint:

• POST /v1/commands applies commands in order.

5. Validate malformed request resilience:

• malformed JSON returns 400 without process crash.

6. Validate Tauri invoke/event behavior:

• current_state output parsed successfully.
• load_active_sprite_pack returns expected fields.
• settings_snapshot returns valid persisted settings payload.
• list_sprite_packs returns valid manifest-backed pack options.
• set_sprite_pack changes active pack and persists.
• set_scale updates scale and persists.
• set_visibility updates main window visibility and persists.
• set_always_on_top updates top-most behavior and persists.
• runtime:snapshot event received on runtime command changes.
• debug_overlay_visible and set_debug_overlay_visible invoke commands work and persist config.

7. Stress runtime reload stability:

• perform at least 10 cycles of character switch (default <-> ferris) with scale adjustments
• no frontend runtime exception (including TypeError) is allowed
• scaling behavior remains responsive after each pack switch

8. Chroma-key quality check:

• verify no visible magenta background/fringe remains around sprite edges in normal runtime view, including non-exact gradient magenta atlas backgrounds (for example ferris/demogorgon)

9. Animation tempo check for 8-frame rows:

• looping row animations should feel very slow/readable (1 fps profile)
• one-shot celebrate/success should run slightly faster than loops (2 fps profile)
• tauri renderer applies an additional global slowdown factor (x2) over clip fps; verify perceived playback matches this expectation

10. Scale anchor and bounds check:

• repeated scale changes should keep window centered without directional drift
• window must remain within current monitor bounds during scale adjustments
• no runtime error is allowed from monitor lookup during scale operations (e.g. currentMonitor API mismatch)
• verify window resize uses consistent coordinate units (no accumulated drift over 20 scale changes)
• no runtime command/type error from position updates (e.g. set_position expects integer coords)
• at the same slider scale value, main window size is consistent across packs (default, ferris, demogorgon) within 1px rounding tolerance
• no white strip/background bleed is visible along any overlay window edge on dark desktop background

Settings Window Checklist

1. Open settings from tray Settings item.
2. Confirm repeated tray clicks focus existing settings window instead of creating duplicates.
3. Change character in settings and verify:

• active pack changes immediately in main overlay
• selection persists after restart

4. Change scale via slider and verify:

• runtime scale changes immediately
• main overlay auto-fits without clipping
• persisted/runtime scale value reflects the effective fitted scale after monitor/window bounds
• value persists after restart

5. Change animation speed factor slider and verify:

• runtime animation pace updates immediately in main overlay
• value is clamped to 1..200
• value persists after restart via frontend.tauri_animation_slowdown_factor

6. Toggle Visible and verify:

• main overlay hide/show behavior
• persisted value survives restart

7. Toggle Always on top and verify:

• main window z-order behavior updates
• persisted value survives restart

Evidence Requirements

For each Tauri runtime issue, include:

• command output summaries for all strict gate commands
• screenshot references:
  • before: issues/screenshots/issueN-before-YYYYMMDD-HHMMSS.png
  • after: issues/screenshots/issueN-after-YYYYMMDD-HHMMSS.png
• invoke/event verification notes
• API verification notes

Issue Lifecycle Integration

Use standard lifecycle in issues/issueN.md:

1. Reported
2. Triaged
3. In Progress
4. Fix Implemented
5. Verification Passed
6. Closed

Tauri runtime issues must remain at Fix Implemented if any strict-gate evidence is missing.

Failure Classification and Triage

• P0: crash on startup, renderer not visible, auth bypass, or command pipeline broken.
• P1: animation/state mismatch, event/invoke contract failure, major UX regression.
• P2: non-blocking rendering/perf issues, minor UI mismatch, cosmetic defects.

Test Log Template (Tauri Runtime)

• Date:
• Issue:
• Frontend: sprimo-tauri
• Execution mode: workspace or packaged
• Commands run:
• API checks summary:
• Invoke/event checks summary:
• Before screenshots:
• After screenshots:
• Result:
• Notes: