Skip to main content

​
Testing

Songbird’s testing story is documented in detail in Automated Testing. This page is a quick orientation. The codebase has four automated-testing surfaces. Pick the cheapest one that can fail in a way you’d care about.
ModeUse whenSpeed
Rust tests (cargo test)Engine / DSP / sync dispatch / state — the default for backend changesseconds
WebSocket tapSync engine cross-boundary behaviour, asserting on events without a browserhundreds of ms
VitestPure React component or hook logicmilliseconds
agent-browser e2eLayout, drag-and-drop, full multi-panel UI flowstens of seconds

​
Quick commands

# Default bar before committing
./utils/validate                       # rust + ts + lint + vitest

# Just one layer
./utils/validate rust                  # cargo test + clippy across the workspace
./utils/validate vitest                # React unit tests
cd rust && cargo test -p songbird-sync # one crate

# Headless harness for browser-driven E2E
./utils/build/agent-headless.sh

​
Rust audio engine tests

The engine is verified with deterministic output checks — RMS, peak amplitude, zero-crossing frequency estimation, spectral energy ratios, golden-output fingerprints — not real audio hardware. For new audio features, prefer adding deterministic tests in the relevant songbird-engine test module over manual ear-tests. The dsp-golden-testing skill documents the golden-file pattern used by songbird-dsp atoms and molecules. Tests live in sibling tests.rs files, never inline #[cfg(test)] mod tests { … } blocks. The parent file declares #[cfg(test)] mod tests;.

​
React UI tests (Vitest)

Tests live alongside the code they test (Foo.test.ts next to Foo.tsx). 
cd react_ui
npx vitest run        # Run all tests once
npx vitest            # Watch mode

​
agent-browser is opt-in

Browser verification is opt-in. The default expectation for a UI or sync-engine PR is ./utils/validate. Only spin up the headless harness when explicitly asked for end-to-end verification, or when the change is one that can only be caught visually (a layout regression, a drag-and-drop gesture, a focus trap). See the e2e-headless and agent-browser skills for the full reference.