> ## Documentation Index
> Fetch the complete documentation index at: https://songbird.studiocollective.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing

# Testing

Songbird's testing story is documented in detail in
[Automated Testing](./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

```bash theme={null}
# 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`).

```bash theme={null}
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.