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:

```powershell
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: