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.

Mode	Use when	Speed
Rust tests (`cargo test`)	Engine / DSP / sync dispatch / state — the default for backend changes	seconds
WebSocket tap	Sync engine cross-boundary behaviour, asserting on events without a browser	hundreds of ms
Vitest	Pure React component or hook logic	milliseconds
agent-browser e2e	Layout, drag-and-drop, full multi-panel UI flows	tens 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.

Testing & Validation

Workflows

Specs

Work in Progress

Testing

Testing

Quick commands

Rust audio engine tests

React UI tests (Vitest)

agent-browser is opt-in

​Testing

​Quick commands

​Rust audio engine tests

​React UI tests (Vitest)

​agent-browser is opt-in

Testing

Quick commands

Rust audio engine tests

React UI tests (Vitest)

agent-browser is opt-in