michael/klangkiste
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0da76927ce70bf45bf37039d95797cb5d7c24c4e
klangkiste/docs/acceptance-tests.md
T
michael 0da76927ce Upload
2026-01-12 18:15:51 +00:00

13 KiB
Raw Blame History

Acceptance Tests

Purpose

Comprehensive test catalog derived from the current codebase. Each test is runnable in Simulation and described for Real Box hardware. Behaviors not implemented are explicitly marked.

Prerequisites

  • Repo root
  • Python 3
  • Box API running for Simulation: python3 box/main.py run
  • GUI optional: cd gui && npm run dev

Step-by-step

Use the tests below in order or individually.

Test A: Box-Start & Identitaet (box_id)

  1. Goal
  • Verify box_id is created once and persists.
  1. Preconditions
  • Simulation: box/data/box.json may be missing.
  • Real Box: storage is empty or fresh install.
  1. Procedure – Simulation / Emulation
  • Start Box:
python3 box/main.py run
  • Check box_id in API:
curl http://127.0.0.1:8000/status
  • Inspect file:
cat box/data/box.json
  1. Procedure – Real Box (Hardware)
  • Power on device.
  • Open status UI (if available) or API endpoint.
  1. Expected Result
  • /status contains box_id with format klangkiste-<10 chars a-z0-9>.
  • box/data/box.json contains box_id and is stable across restarts.
  1. Deviations / Troubleshooting
  • box_id missing: check write permissions for box/data/.
  • box_id changes: indicates manual deletion of box/data/box.json.

Test B: WLAN-Ersteinrichtung (Setup WebGUI)

  1. Goal
  • Configure WiFi profile via setup UI and reach WIFI_ONLINE.
  1. Preconditions
  • No WiFi profiles stored.
  1. Procedure – Simulation / Emulation
  • Reset WiFi profiles:
curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"wifi_reset"}'
  • Open Setup UI:
http://127.0.0.1:9000/setup
  • Choose SSID and enter password, click "Verbinden".
  • Check status:
curl http://127.0.0.1:8000/status
  1. Procedure – Real Box (Hardware)
  • Power on device.
  • Connect to device AP SSID (not implemented in code).
  • Open setup page and submit WiFi credentials.
  1. Expected Result
  • wifi_state = WIFI_ONLINE
  • connected_ssid matches selected SSID
  • wifi_profiles_count increments
  1. Deviations / Troubleshooting
  • Setup UI unreachable: port 9000 occupied or Box not running.
  • Not testable with current code: AP SSID and real WiFi connect.

Test C: Persistenz & Neustart

  1. Goal
  • Ensure resume state and WiFi profiles persist across restarts.
  1. Preconditions
  • At least one WiFi profile stored.
  • Playback started once.
  1. Procedure – Simulation / Emulation
  • Add WiFi profile (if needed):
curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"wifi_add_profile","payload":{"ssid":"HomeWiFi","password":"secret","priority":10}}'
  • Start playback:
curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"nfc_on","payload":{"uid":"UID_1"}}'
  • Stop playback:
curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"nfc_off","payload":{"uid":"UID_1"}}'
  • Restart Box process.
  • Check status:
curl http://127.0.0.1:8000/status
  1. Procedure – Real Box (Hardware)
  • Start playback via NFC.
  • Power cycle device.
  • Verify WiFi profile and resume state persist.
  1. Expected Result
  • box/data/state.json contains resume.
  • box/data/secrets.enc exists and contains profiles (encrypted).
  • After restart, wifi_state is not UNCONFIGURED.
  1. Deviations / Troubleshooting
  • Resume missing: check box/data/state.json.
  • WiFi profiles missing: check box/data/secrets.enc creation.

Test D: HTTP API Status & Commands

  1. Goal
  • Verify /status and /command are functional.
  1. Preconditions
  • Box running.
  1. Procedure – Simulation / Emulation
  • Status:
curl http://127.0.0.1:8000/status
  • Command:
curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"play_pause"}'
  1. Procedure – Real Box (Hardware)
  • Same as above once API is reachable in real network.
  1. Expected Result
  • HTTP 200 responses.
  • /status fields updated after commands.
  1. Deviations / Troubleshooting
  • CORS errors: ensure API is running.
  • 400 errors: check payload requirements.

Test E: GUI-Steuerung

  1. Goal
  • Verify GUI can control playback and display status.
  1. Preconditions
  • Box running on 127.0.0.1:8000.
  • GUI running on 127.0.0.1:5174.
  1. Procedure – Simulation / Emulation
  • Open GUI:
http://127.0.0.1:5174
  • Click Play / Pause, Next, Prev, Vol +, Vol -.
  • Click NFC UID_1 ON/OFF.
  • Watch status refresh (polling every 1s).
  1. Procedure – Real Box (Hardware)
  • Use GUI from another device pointing to Box IP.
  1. Expected Result
  • /status changes after each button.
  • GUI shows updated status and last_error if present.
  1. Deviations / Troubleshooting
  • GUI shows "Failed to fetch": verify VITE_BOX_API_URL.

Test F: Playback & NFC

  1. Goal
  • Verify NFC starts playback from tags.
  1. Preconditions
  • Tags exist in box/data/box.json.
  • Media exists under box/data/media.
  1. Procedure – Simulation / Emulation
  • Start playback:
curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"nfc_on","payload":{"uid":"UID_1"}}'
  • Observe /status:
curl http://127.0.0.1:8000/status
  1. Procedure – Real Box (Hardware)
  • Place NFC tag mapped to UID_1.
  1. Expected Result
  • playback_state.state = PLAYING
  • active_uid = UID_1
  1. Deviations / Troubleshooting
  • No playback: check tags in box/data/box.json and files in box/data/media.

Test G: Resume-Logik

  1. Goal
  • Resume picks up last file index and position per UID.
  1. Preconditions
  • Playback started at least once for UID_1.
  1. Procedure – Simulation / Emulation
  • Start playback, wait ~5s.
  • Stop with nfc_off.
  • Start again with nfc_on.
  1. Procedure – Real Box (Hardware)
  • Place NFC tag, remove, place again.
  1. Expected Result
  • Resume uses stored file_index and position.
  • box/data/state.json contains resume for UID_1.
  1. Deviations / Troubleshooting
  • Resume resets to 0: check state.json and path changes.

Test H: Ordner- & Rekursionslogik

  1. Goal
  • Verify recursive ordering (DFS, folders first, lexicographic).
  1. Preconditions
  • Nested media structure in box/data/media.
  1. Procedure – Simulation / Emulation
  • Create nested structure in box/data/media/book_6/CD1/....
  • Point a tag to media/book_6 in box/data/box.json.
  • Start playback with nfc_on.
  1. Procedure – Real Box (Hardware)
  • Copy nested folders to the device media path.
  • Start playback via NFC.
  1. Expected Result
  • Files play in DFS order: subfolders sorted, then files.
  1. Deviations / Troubleshooting
  • Ordering unexpected: check folder names and lexicographic sort.

Test I: Offline-Szenarien (Box intern)

  1. Goal
  • Verify WiFi and Spotify states in offline/online flows.
  1. Preconditions
  • Box running.
  1. Procedure – Simulation / Emulation
  • WiFi reset:
curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"wifi_reset"}'
  • Spotify clear:
curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"spotify_clear"}'
  1. Procedure – Real Box (Hardware)
  • Not testable with current code: real network loss and Spotify connectivity.
  1. Expected Result
  • wifi_state = WIFI_UNCONFIGURED
  • spotify_status = NOT_CONFIGURED
  1. Deviations / Troubleshooting
  • Status unchanged: ensure you read /status after command.

Test J: Fehlerfaelle (Box intern)

  1. Goal
  • Verify error sound and error reporting.
  1. Preconditions
  • Box running.
  1. Procedure – Simulation / Emulation
  • Trigger error:
curl -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command":"trigger_error","payload":{"type":"uid_unmapped"}}'
  • Check /status for last_error.
  1. Procedure – Real Box (Hardware)
  • Not testable with current code: actual error sound output.
  1. Expected Result
  • playback_state.last_error equals error type.
  • Box returns to IDLE after error.
  1. Deviations / Troubleshooting
  • No error shown: verify /status and that errors are not cleared automatically.

Test K: Announce -> neue Box erscheint im Server

  1. Ziel
  • Box meldet sich beim Server und erscheint als UNPAIRED / neue Box.
  1. Voraussetzungen
  • Simulation: Server-Komponente vorhanden und laeuft.
  • Real Box: Server erreichbar im Netzwerk.
  1. Durchfuehrung – Simulation / Emulation
  • Nicht testbar mit aktuellem Code: Box sendet keine Announce-Requests.
  1. Durchfuehrung – Reale Box (Hardware)
  • Nicht testbar mit aktuellem Code: Announce-Logik ist nicht implementiert.
  1. Erwartetes Ergebnis
  • Nicht testbar mit aktuellem Code.
  1. Abweichungen / Fehlersuche
  • Wenn implementiert: Pruefe Server-Logs, API-Endpunkte und Box-Statusfelder.

Test L: Mehrere Boxen gleichzeitig

  1. Ziel
  • Mehrere Boxen werden als separate, unbekannte Boxen erkannt.
  1. Voraussetzungen
  • Simulation: Mehrere Box-Prozesse mit unterschiedlichen box_id.
  1. Durchfuehrung – Simulation / Emulation
  • Nicht testbar mit aktuellem Code: Announce/Server-Erkennung fehlt.
  1. Durchfuehrung – Reale Box (Hardware)
  • Nicht testbar mit aktuellem Code.
  1. Erwartetes Ergebnis
  • Nicht testbar mit aktuellem Code.
  1. Abweichungen / Fehlersuche
  • Wenn implementiert: Pruefe Duplikate anhand box_id und fingerprint.

Test M: Pairing-Freigabe ueber Server-GUI

  1. Ziel
  • Box wird nach Freigabe gepairt und erhaelt API-Token.
  1. Voraussetzungen
  • Simulation: Server-GUI und Pairing-Endpunkte implementiert.
  1. Durchfuehrung – Simulation / Emulation
  • Nicht testbar mit aktuellem Code: Pairing-Flow fehlt.
  1. Durchfuehrung – Reale Box (Hardware)
  • Nicht testbar mit aktuellem Code.
  1. Erwartetes Ergebnis
  • Nicht testbar mit aktuellem Code.
  1. Abweichungen / Fehlersuche
  • Wenn implementiert: Pruefe Token-Speicherung in box/data/secrets.enc.

Test N: Verhalten vor Pairing (keine Steuerung erlaubt)

  1. Ziel
  • Vor Pairing sind Steuerbefehle blockiert.
  1. Voraussetzungen
  • Server-Integration und Auth-Checks vorhanden.
  1. Durchfuehrung – Simulation / Emulation
  • Nicht testbar mit aktuellem Code: kein Auth/Pairing implementiert.
  1. Durchfuehrung – Reale Box (Hardware)
  • Nicht testbar mit aktuellem Code.
  1. Erwartetes Ergebnis
  • Nicht testbar mit aktuellem Code.
  1. Abweichungen / Fehlersuche
  • Wenn implementiert: Pruefe API-Responses (401/403) und Server-Logs.

Test O: Verhalten nach Pairing

  1. Ziel
  • Nach Pairing sind Steuerbefehle erlaubt und Box reagiert.
  1. Voraussetzungen
  • Pairing-Flow implementiert.
  1. Durchfuehrung – Simulation / Emulation
  • Nicht testbar mit aktuellem Code.
  1. Durchfuehrung – Reale Box (Hardware)
  • Nicht testbar mit aktuellem Code.
  1. Erwartetes Ergebnis
  • Nicht testbar mit aktuellem Code.
  1. Abweichungen / Fehlersuche
  • Wenn implementiert: Pruefe Token in secrets.enc und Server-GUI Status.

Test P: Neustart vor/nach Pairing

  1. Ziel
  • Box behaelt Pairing-Status und Token ueber Neustarts.
  1. Voraussetzungen
  • Pairing implementiert.
  1. Durchfuehrung – Simulation / Emulation
  • Nicht testbar mit aktuellem Code.
  1. Durchfuehrung – Reale Box (Hardware)
  • Nicht testbar mit aktuellem Code.
  1. Erwartetes Ergebnis
  • Nicht testbar mit aktuellem Code.
  1. Abweichungen / Fehlersuche
  • Wenn implementiert: Pruefe secrets.enc vor/nach Neustart.

Test Q: Factory Reset -> neue Identitaet

  1. Ziel
  • Factory Reset loescht box_id und erzeugt neue Identitaet beim naechsten Start.
  1. Voraussetzungen
  • Box laeuft einmalig und box/data/ existiert.
  1. Durchfuehrung – Simulation / Emulation
  • Stoppe Box.
  • Loesche folgende Dateien:
rm -f box/data/box.json box/data/state.json box/data/secrets.enc
  • Starte Box neu:
python3 box/main.py run
  • Pruefe /status.
  1. Durchfuehrung – Reale Box (Hardware)
  • Nicht testbar mit aktuellem Code: kein Factory-Reset-Mechanismus implementiert.
  1. Erwartetes Ergebnis
  • Neue box_id erscheint in /status.
  1. Abweichungen / Fehlersuche
  • box_id bleibt gleich: Dateien wurden nicht geloescht.

Test R: Offline / Server nicht erreichbar

  1. Ziel
  • Box laeuft weiter, wenn Server nicht erreichbar ist.
  1. Voraussetzungen
  • Server-Integration implementiert.
  1. Durchfuehrung – Simulation / Emulation
  • Nicht testbar mit aktuellem Code: keine Server-Kommunikation.
  1. Durchfuehrung – Reale Box (Hardware)
  • Nicht testbar mit aktuellem Code.
  1. Erwartetes Ergebnis
  • Nicht testbar mit aktuellem Code.
  1. Abweichungen / Fehlersuche
  • Wenn implementiert: pruefe lokale Funktionen (Playback, NFC) laufen weiter.

Test S: Simulation vs. Hardware – Unterschiede

  1. Ziel
  • Dokumentiere, was real vs. mock ist.
  1. Voraussetzungen
  • Box laeuft in Simulation.
  1. Durchfuehrung – Simulation / Emulation
  • Beachte: WiFi/IP/Spotify/Audio sind Mock.
  • Setup UI und API funktionieren lokal.
  1. Durchfuehrung – Reale Box (Hardware)
  • Nicht testbar mit aktuellem Code: Hardware-Backends fehlen.
  1. Erwartetes Ergebnis
  • Simulation laeuft ohne Hardware.
  • Hardware-Backends koennen spaeter ersetzt werden.
  1. Abweichungen / Fehlersuche
  • Wenn Hardware genutzt wird, fehlen Implementierungen.
Reference in New Issue View Git Blame Copy Permalink