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

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.
• runtime:snapshot event received on runtime command changes.

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: