Testing Guide¶
Quick Reference¶
# Server tests
cargo test # All workspace tests
cargo test -p xylolabs-server # Server integration tests only
# Protocol crate tests (encoder + decoder roundtrips)
cargo test -p xylolabs-protocol --all-features
# SDK core tests (client, session, ring buffer, config, health)
cargo test -p xylolabs-sdk --all-features
# Audio pipeline tests (decimation, I2S config, full encode pipeline -- runs on host)
cd tests/audio-pipeline && cargo test
# Frontend tests
cd frontend && pnpm test
Rust SDK Tests¶
Protocol Crate¶
Tests XMBP encoder/decoder roundtrips for all 11 value types, boundary conditions, truncation handling, and performance benchmarks (encode/decode must complete in < 100 µs per 2 kHz batch).
SDK Core¶
Tests client initialization, session lifecycle, ring buffer SPSC correctness, config validation, health statistics, codec encode/decode, and cross-language parity with the C SDK.
Audio Pipeline¶
Runs on host (not cross-compiled). Tests: - FIR decimation (96kHz to 16kHz): coefficient verification, DC passthrough, stereo interleaving, continuity, near-Nyquist attenuation, max-amplitude overflow safety - Full encode pipeline (I2S to decimate to XAP): compression ratio, header format, silence/sine
48 host tests + 7 QEMU tests.
Burn-In Tests¶
# Start test infrastructure + API server
docker compose -f docker-compose.test.yml up -d
cargo run --bin xylolabs-server --release # with test env vars
# Run burn-in scenarios (requires running API server)
./scripts/run-burnin.sh standard # 60s quick validation
./scripts/run-burnin.sh stress # 120s high throughput (4ch @96kHz)
./scripts/run-burnin.sh endurance # 120s+ sustained load
./scripts/run-burnin.sh multi-device # 10 concurrent devices
# QEMU ARM emulation (simulates ~150MHz RP2350)
./scripts/run-burnin.sh standard --qemu
# ESP32-S3 Xtensa QEMU emulation
./scripts/run-qemu-esp32.sh
# Cleanup
docker compose -f docker-compose.test.yml down -v
Pass/fail criteria: < 5% batch failure rate, < 3 reconnects. Performance metrics reported per run.
Legacy C SDK Tests¶
# Run all unit tests natively (requires gcc + libm)
gcc -Wall -Wextra -Werror -O2 -o /tmp/test_xmbp sdk/c/test/test_xmbp.c sdk/c/common/src/xmbp_encoder.c -Isdk/c/common/include -lm && /tmp/test_xmbp
gcc -Wall -Wextra -Werror -O2 -o /tmp/test_xap sdk/c/test/test_xap.c sdk/c/common/src/xap_encoder.c -Isdk/c/common/include -lm && /tmp/test_xap
gcc -Wall -Wextra -Werror -O2 -o /tmp/test_ring_buffer sdk/c/test/test_ring_buffer.c sdk/c/common/src/ring_buffer.c -Isdk/c/common/include && /tmp/test_ring_buffer
gcc -Wall -Wextra -O2 -o /tmp/test_client sdk/c/test/test_client.c sdk/c/common/src/xylolabs_client.c sdk/c/common/src/xmbp_encoder.c sdk/c/common/src/adpcm_encoder.c sdk/c/common/src/xap_encoder.c sdk/c/common/src/ring_buffer.c sdk/c/common/src/http_transport.c sdk/c/common/src/session_manager.c -Isdk/c/common/include -lm && /tmp/test_client
# Run all C tests via Docker (includes ARM cross-compilation syntax check + QEMU)
docker build -t xylolabs-sdk-test -f sdk/c/test/Dockerfile . && docker run --rm xylolabs-sdk-test
# Expected results: XMBP 34/34, XAP 45/45, Ring Buffer 358/358, Client 11/11
# Run E2E test suite (native + ARM cross-compile + QEMU emulation)
./scripts/run-sdk-e2e.sh
# Or manually: build and run E2E Docker image
docker build -f sdk/c/test/Dockerfile.e2e -t xylolabs-sdk-e2e . && docker run --rm xylolabs-sdk-e2e
# E2E covers: 8 native suites, 4 ARM targets (M0+/M3/M4F/M33), 4 QEMU emulation suites
# Run Xtensa (ESP32-S3) tests using Espressif IDF Docker image (~2GB)
./scripts/run-sdk-xtensa.sh
# Or include Xtensa tests in the main E2E suite
RUN_XTENSA=true ./scripts/run-sdk-e2e.sh
E2E Ingest Test¶
Located in tests/e2e-ingest/. Generates 4-channel sine wave audio (1/2/3/4 kHz), encodes with XAP, packages with XMBP, and uploads to the live API.
Tests the full pipeline: PCM → XAP encode → XMBP frame → HTTP POST with X-Api-Key → server ingest.
Remote E2E Pipeline Test¶
Located in tests/remote-e2e/. Comprehensive test against a live API (e.g. api.xylolabs.com) covering the full XMBP/XAP pipeline with metadata verification.
# Create .env in project root with:
# E2E_API_KEY=xk_...
# E2E_HOST=api.xylolabs.com
# E2E_EMAIL=admin@xylolabs.com
# E2E_PASSWORD=...
cd tests/remote-e2e
cargo run
Test rules (constants): - 4-channel audio: 1 kHz / 2 kHz / 3 kHz / 4 kHz sine waves - 16 kHz sample rate, 10 ms frames, 64 kbps, 500 ms duration - 3 metadata streams: temperature (f64), humidity (f64), pressure (f32) at 10 Hz
Steps: Login → Create ingest session (4 streams) → Send XMBP audio batch (50 XAP frames) → Send XMBP metadata batch (15 samples) → Close session → Query all 4 streams and verify sample counts → Upload XAP file → Verify transcode job created.
XAP Upload & Transcode Tests¶
Located in crates/xylolabs-server/tests/api_upload_transcode.rs. Tests XAP file upload and transcode job creation (requires Docker test infrastructure).
XMBP Pipeline Tests¶
Located in crates/xylolabs-server/tests/api_xmbp_pipeline.rs. Full 4-channel XAP + metadata e2e test with ingest session lifecycle.
XAP Decoder Tests¶
Unit tests for the server-side XAP decoder (inverse MDCT + dequantization).
6 tests: silence decode, non-zero coefficients, multichannel, WAV header, sample rate inference.
Browser Validation¶
Headless Playwright script that validates all admin dashboard pages load correctly.
Checks: Login → Dashboard → Uploads → Transcode → Metadata Sessions → Users → API Keys → Settings.
Frontend Tests¶
6 test files:
- authStore.test.ts -- Auth store state management
- client.test.ts -- API client layer
- ProtectedRoute.test.tsx -- Route protection component
- RoleGate.test.tsx -- Role-based UI gating
- Sidebar.test.tsx -- Sidebar navigation component
Test Coverage¶
Audio pipeline (48 host tests + 7 QEMU tests): - FIR decimation (96kHz to 16kHz): coefficient verification, DC passthrough, stereo interleaving, continuity, near-Nyquist attenuation, max-amplitude overflow safety - Full encode pipeline (I2S to decimate to XAP): compression ratio, header format, silence/sine - QEMU ESP32 firmware: decimation + full pipeline verification
Known Test Coverage Gaps¶
Server (Priority 1): - IngestManager: zero unit tests (sequence gap wrapping, backpressure, flush guard, stale eviction) - WebSocket ingest: zero integration tests for WS binary frames, ping/pong, idle timeout - RBAC/JWT middleware: no unit tests for role hierarchy, token expiry, bad signatures
SDK (Priority 2 -- legacy C only):
- xylolabs_client.c: audio_feed, meta_feed, tick paths untested (only init covered)
- session_send_audio: entirely untested
- session_ensure_active reconnect: exponential backoff untested
- ADPCM codec path: not validated in QEMU CI matrix
Security: - No brute-force rate limiting test for API keys - No JWT signature verification test