143 lines
4.8 KiB
Markdown
143 lines
4.8 KiB
Markdown
# 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
|
|
|
|
## 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.
|
|
- `debug_overlay_visible` and `set_debug_overlay_visible` invoke commands work and persist config.
|
|
|
|
## 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:
|