Sprimo/docs/RANDOM_BACKEND_TESTING.md

Random Backend API Testing

Date: 2026-02-13

Purpose

This workflow provides randomized backend-like API traffic against a running Sprimo frontend. It focuses on command endpoints and mixes valid and invalid requests to verify transport and runtime resilience.

Primary targets:

• POST /v1/command
• POST /v1/commands

Supporting checks:

• GET /v1/health
• GET /v1/state (periodic sampling)

Animation traffic now targets row-based sprite names plus compatibility aliases:

• semantic names: idle, happy, love, excited, celebrate, sleepy, snoring, working, angry, surprised, shy, dragging
• compatibility aliases: active, success, error
• one intentional unknown name is still included to keep invalid animation-path coverage

Prerequisites

• Frontend runtime is already running (sprimo-app or sprimo-tauri).
• Python is available.
• Auth token and port are available from config or passed via CLI flags.

By default, the tester discovers config at:

• Windows: %APPDATA%/sprimo/config/config.toml (legacy fallback: %APPDATA%/sprimo/config.toml)
• macOS: ~/Library/Application Support/sprimo/config/config.toml
• Linux: ~/.config/sprimo/config/config.toml

Quick Start

just random-backend-test

Strict mode (non-zero exit if unexpected outcomes appear):

just random-backend-test-strict

CLI Examples

Run against explicit host/port/token:

python scripts/random_backend_tester.py --host 127.0.0.1 --port 32145 --token "<token>"

Deterministic run with higher invalid traffic:

python scripts/random_backend_tester.py --seed 42 --invalid-probability 0.35 --duration-seconds 45

Write machine-readable summary:

python scripts/random_backend_tester.py --json-summary dist/random-backend-summary.json

Important Flags

• --duration-seconds: total run time
• --interval-ms: delay between random requests
• --batch-probability: ratio of /v1/commands usage
• --max-batch-size: max commands per batch request
• --invalid-probability: inject malformed/invalid payloads
• --unauthorized-probability: inject auth failures
• --state-sample-every: periodic authenticated /v1/state checks
• --strict: fail run on unexpected outcomes
• --health-check: verify API liveness before random traffic

Expected Result Pattern

In mixed mode, typical status distribution includes:

• 202 for valid command requests
• 400 for malformed/invalid payloads
• 401 for missing/invalid auth

Unexpected outcomes that should be investigated:

• 5xx responses
• repeated transport failures/timeouts
• strict mode failures (unexpected_outcomes > 0)

Evidence Guidance

When used for issue verification, record:

• command used (including seed/probabilities)
• summary output (status buckets, unexpected outcomes, transport errors)
• linked issue file under issues/issueN.md

This test complements cargo check --workspace, cargo test --workspace, and just qa-validate; it does not replace them.