# Test Matrix

This project needs both no-hardware tests and carefully gated hardware tests.

## No-Hardware Tests

- CMake configure/build smoke.
- Version/build metadata smoke test.
- Device lifecycle model tests.
- Format descriptor tests.
- Playback config serialization tests.
- Logger JSONL/CSV serialization tests.
- Diagnostic bundle fixture tests.
- PCM 1 kHz signal generation tests.
- DoP marker packing tests.
- Native DSD idle/test-pattern fixture tests.
- `NullBackend` run tests.
- Automated diagnostic dry-run planner tests.
- UI state consistency tests for active-backend interlocks, stale accepted
  format rejection, explicit fallback-format selection, and exact `--smoke`
  argument parsing.

## Manual GUI Smoke Tests

Visible GUI inspection is tracked in `docs/GUI_SMOKE_CHECKLIST.md`. It covers
1280x760, 1366x768, 1920x1080, and Windows display scaling at 100% and 125%.
This check must verify that the Japanese light theme is the default, the single
device-first flow feels calm and support-utility-like, no essential controls are
clipped, disabled controls explain why they are disabled, changing the target
API clears incompatible device/format state, refresh/scan/run actions stay
scoped to the selected target API, and API-specific scheduling controls appear
only with values meaningful for the selected API.
The MMCSS control must be shown as an audio-thread scheduling setting, not as a
WASAPI-only setting, and ASIO driver-owned callback limitations must be visible
where applicable.

## Manual Hardware Smoke Tests

### WASAPI Endpoint Enumeration

- Trigger a single user-visible WASAPI endpoint refresh.
- Verify endpoint ID, friendly name, endpoint state, and property snapshot logs.
- Verify no `IAudioClient` activation, stream initialization, render client, or
  playback event appears in the log.
- Verify failures are reported once without an automatic retry loop.

### WASAPI Selected Endpoint Format Probe

- Probe only an explicit endpoint ID.
- Verify GUI-requested format support is checked before mix-format fallback,
  and verify mix format, default/min device period, explicit fallback row
  selection, and closest-match logging where available.
- Verify no `IAudioClient::Initialize`, playback, or repeated probe loop occurs.

### WASAPI Shared PCM

- 48 kHz, 32-bit float, stereo, 1 kHz PCM.
- Verify mix format, accepted format, buffer size, stream latency, padding, and
  callback timing logs.
- Verify signal end transitions to valid PCM keep-warm silence by default.
- Verify `Release after drain` logs drain, release, and cooldown exactly once.
- Verify normal stop does not use `Reset`.

### WASAPI Exclusive

- 44.1 kHz, 16-bit integer, stereo, 1 kHz PCM.
- Verify unsupported format logging when the endpoint rejects a format.
- Verify exact-format support is checked before stream initialization.
- Verify event-driven exclusive mode logs stream flags, device default/minimum
  period, requested/effective buffer and periodicity, event wait timeout, and
  any single buffer-alignment retry.
- Verify timer/poll-driven exclusive mode can be selected for comparison and
  logs render polling instead of event callbacks.
- Verify no sample-rate sweep, silent shared-mode fallback, or repeated
  exclusive initialize loop occurs.

### Known-Problem USB DAC / XMOS Profile

- Mark the device as a known-problem profile before playback.
- Start with enumeration and selected-endpoint probe only.
- For first playback, use WASAPI shared PCM with keep-warm after stop.
- Verify the device is not fully released at signal end while the session stays
  active.
- Verify invalidation produces a cooldown-gated fault/recovery state instead of
  repeated reacquire attempts.

### MME

- Conservative buffer count and size.
- Verify `WOM_DONE` timing and error-code logging.

### DirectSound

- Conservative secondary buffer size.
- Verify play/write cursor and lost-buffer logging.

### Kernel Streaming

- Verify explicit filter and render/sink pin selection before pin creation.
- Verify bounded data-range/format checks and no automatic pin recreate loop.
- Verify selectable PCM rows require selected-pin evidence, and unsupported
  rows remain visible but non-selectable.
- Verify stream state transitions, packet framing, `IOCTL_KS_WRITE_STREAM`
  results, Win32/NTSTATUS error codes, and audio-thread scheduling state are
  logged.
- Verify normal stop uses valid PCM silence or held-open state, and full
  release remains explicit and cooldown-gated.
- For KS DoP, verify exact 24-in-32 carrier evidence, DSD multiplier/marker
  logging, and valid DoP silence after signal stop.

### ASIO PCM

- `ENABLE_ASIO=ON` only when SDK path and license gate are explicit.
- Current owner-approved ASIO smoke device: Lynx.
- Current owner-approved ASIO smoke signal level: -24 dBFS.
- Verify driver enumeration, channel/sample type, buffer size, sample rate, and
  callback logs.

### DoP

- WASAPI exclusive, Kernel Streaming, or ASIO PCM carrier paths only where the
  exact DoP carrier is accepted.
- For ASIO DoP smoke, use the owner-approved Lynx ASIO device at -24 dBFS unless
  a later approval overrides it.
- Verify DoP marker phase and warning behavior.

### ASIO Native DSD

- Only when driver exposes native DSD sample type.
- For native DSD smoke, use the owner-approved Lynx ASIO device at -24 dBFS
  equivalent signal generation unless a later approval overrides it.
- Verify disabled reason when unsupported.

## Automated Real-Device Tests

Automated real-device tests must follow `docs/AUTOMATED_DEVICE_DIAGNOSTICS.md`
and `docs/DEVICE_STABILITY_POLICY.md`.
