fader_master/docs/pulse-daemon-fixture.md

53 lines
2.2 KiB
Markdown

# Real Pulse daemon fixture
The M4.4 fixture is opt-in because it connects to the current user's real audio
session. Its normal phase creates a uniquely named, silent stereo stream with
`paplay`, changes only that stream, and always terminates the child process.
It never parses shell output in the production adapter.
## Prerequisites
- A reachable PulseAudio-compatible server. This can be PulseAudio itself or
PipeWire's `pipewire-pulse` service.
- The `paplay` executable and libpulse development/runtime files. On Arch these
are supplied by `libpulse`.
- Permission to access the user audio socket. Sandboxed test runners must expose
that socket deliberately.
Run the non-disruptive phase with:
```sh
cargo test --locked -p volume_lib --test pulse_daemon --all-features \
real_stream_commands_external_edits_and_churn_converge -- \
--ignored --exact --nocapture
```
It verifies discovery of the isolated stream, worker volume and mute commands,
readback, changes made by an independent Pulse client, removal, and a replacement
stream with a fresh handle. Existing desktop streams are observed but never
selected for writes. The fixture fails rather than silently passing when the
daemon, `paplay`, expected notifications, or cleanup behavior is unavailable.
Set `PULSE_SERVER` before the command to target an explicitly isolated daemon.
This is the intended way to run the same fixture against a standalone PulseAudio
CI instance without touching the desktop session.
## Disruptive PipeWire restart phase
This phase intentionally restarts the current user's PipeWire, pipewire-pulse,
and WirePlumber services. It interrupts all desktop audio and must not run in the
ordinary test suite. Close or pause important audio applications first, then
acknowledge the interruption explicitly:
```sh
FADER_MASTER_RESTART_PIPEWIRE=1 \
cargo test --locked -p volume_lib --test pulse_daemon --all-features \
pipewire_restart_disconnects_and_a_new_epoch_resnapshots -- \
--ignored --exact --nocapture
```
The fixture requires a visible disconnect diagnostic, retries with bounded
backoff, reconnects under a new backend epoch, and waits for a complete fresh
snapshot. Without the acknowledgement variable it fails before restarting
anything.