docs: add manual test instructions

docs/contributing/contributing.md

@@ -17,27 +17,7 @@ of the changes respects the coding style of the project
 
 ## Tests
 
-WirePlumber has automated tests that you can easily run with:
-
-```
-$ meson test -C build
-```
-
-This will automatically compile all test dependencies, so you can be sure
-that this always tests your latest changes.
-
-If you wish to run a specific test instead of all of them, you can run:
-```
-$ meson test -C build test-name
-```
-
-When debugging a single test, you can additionally enable verbose test output
-by appending `-v` and you can also run the test in gdb by appending `--gdb`.
-
-For more information on how to use `meson test`, please refer to
-[meson's manual](https://mesonbuild.com/Unit-tests.html)
-
-> When submitting changes for review, always ensure that all tests pass
+See [Testing](testing.md)
 
 ## Running in gdb / valgrind / etc...
 

docs/contributing/testing.md

@@ -0,0 +1,206 @@
+# Testing
+
+## Automated unit tests
+
+WirePlumber has automated tests that you can easily run with:
+
+```
+$ meson test -C build
+```
+
+This will automatically compile all test dependencies, so you can be sure
+that this always tests your latest changes.
+
+If you wish to run a specific test instead of all of them, you can run:
+```
+$ meson test -C build test-name
+```
+
+When debugging a single test, you can additionally enable verbose test output
+by appending `-v` and you can also run the test in gdb by appending `--gdb`.
+
+For more information on how to use `meson test`, please refer to
+[meson's manual](https://mesonbuild.com/Unit-tests.html)
+
+> When submitting changes for review, always ensure that all tests pass
+
+## WirePlumber examples
+
+WirePlumber ships examples in `test/examples`.
+Execute them from the top-level directory like this:
+
+```
+$ WIREPLUMBER_MODULE_DIR=build/modules ./build/tests/examples/audiotestsrc-play
+```
+
+Assuming there is no other process actively using `hw:0,0` from alsa, the above
+example should play a test tone on `hw:0,0` without errors.
+
+## Native API clients
+
+### pw-cat
+
+Using the default endpoint:
+```
+$ wpctl status  # verify the default endpoints
+$ pw-record test.wav
+$ pw-play test.wav
+```
+
+Using a non-default endpoint:
+```
+$ pw-record --list-targets  # find the node id
+$ pw-record --target <node_id> test.wav
+$ pw-play --list-targets  # find the node id
+$ pw-play --target <node_id> test.wav
+```
+or
+```
+$ wpctl status  # find the capture & playback endpoint ids
+$ pw-record --target <endpoint_id> test.wav
+$ pw-play --target <endpoint_id> test.wav
+```
+
+> Note: node ids and endpoint ids can be used interchangeably when specifying
+targets in all use cases.
+
+### video-play
+
+Using the default endpoint:
+```
+$ cd path/to/pipewire-source-dir
+$ ./build/src/examples/video-play
+```
+
+Using a non-default endpoint:
+```
+$ wpctl status  # find the endpoint id from the list
+$ cd path/to/pipewire-source-dir
+$ ./build/src/examples/video-play <endpoint_id>
+```
+
+> Tip: enable videotestsrc in wireplumber's configuration to have more video
+sources available (see `videotestsrc.node.disabled` in the configuration directory)
+
+## PulseAudio compat API clients
+
+### pacat
+
+Using the default endpoint:
+```
+$ wpctl status  # verify the default endpoints
+$ pw-pulse parecord test.wav
+$ pw-pulse paplay test.wav
+```
+
+Using a non-default endpoint:
+```
+$ wpctl status  # find the capture & playback endpoint ids
+$ PIPEWIRE_NODE=<endpoint_id> pw-pulse parecord test.wav
+$ PIPEWIRE_NODE=<endpoint_id> pw-pulse paplay test.wav
+```
+
+### pavucontrol
+
+```
+$ pw-pulse pavucontrol
+```
+* Volume level meters should work
+* Changing the volume should work
+
+## ALSA compat API clients
+
+### aplay / arecord
+
+> Note: unless you have installed PipeWire in the default system prefix
+(`/usr`), the ALSA compat API will not work, unless you copy
+`libasound_module_pcm_pipewire.so` in the alsa plugins directory
+(usually `/usr/<libdir>/alsa-lib/`) and that you add the contents of
+`pipewire-alsa/conf/50-pipewire.conf` in your `~/.asoundrc`
+(or anywhere else, system-wide, where libasound can read it)
+
+Using the default endpoint:
+```
+$ wpctl status  # verify the default endpoints
+$ arecord -D pipewire -f S16_LE -r 48000 test.wav
+$ aplay -D pipewire test.wav
+```
+
+Using a non-default endpoint:
+```
+$ wpctl status  # find the capture & playback endpoint ids
+$ PIPEWIRE_NODE=<endpoint_id> arecord -D pipewire -f S16_LE -r 48000 test.wav
+$ PIPEWIRE_NODE=<endpoint_id> aplay -D pipewire test.wav
+```
+or
+```
+$ wpctl status  # find the capture & playback endpoint ids
+$ arecord -D pipewire:NODE=<endpoint_id> -f S16_LE -r 48000 test.wav
+$ aplay -D pipewire:NODE=<endpoint_id> test.wav
+```
+
+## JACK compat API clients
+
+### qjackctl
+
+```
+pw-jack qjackctl
+```
+* This should correctly connect.
+* The "Graph" window should show the PipeWire graph.
+
+### jack_simple_client
+
+```
+$ wpctl status  # find the target endpoint id
+$ wpctl inspect <endpoint_id>  # find the node.id
+$ PIPEWIRE_NODE=<node_id> pw-jack jack_simple_client
+```
+
+> The JACK layer is not controlled by the session manager, it creates its own
+links; which is why it is required to specify a node id (endpoint id will not
+work)
+
+## Device Reservation
+
+### with PulseAudio
+
+1. With PulseAudio running, start a pulseaudio client:
+```
+gst-launch-1.0 audiotestsrc ! pulsesink
+```
+2. Start PipeWire & WirePlumber
+   - The device in use by PA will not be available in PW
+3. Stop the PA client
+   - A few seconds later, WirePlumber should assume control of the device
+4. `wpctl status` should be able to confirm that the device is available
+5. Start a PA client again
+   - It should not be able to play; it will just freeze
+6. Stop WirePlumber
+   - The PA client should immediately start playing
+
+### with JACK
+
+1. Start PipeWire & WirePlumber
+   - All devices should be available
+2. Start `jackdbus`
+   - through `qjackctl`:
+     - Enable `Setup` -> `Misc` -> `Enable JACK D-Bus interface`
+     - Click `Start` on the main window
+   - or manually:
+     - Run `jackdbus auto`
+     - Run `qdbus org.jackaudio.service /org/jackaudio/Controller org.jackaudio.JackControl.StartServer`
+3. Wait a few seconds and run `wpctl status` to inspect
+   - The devices taken by JACK should no longer be available
+   - There should be two `JACK System` endpoints (sink & source)
+4. Run an audio client on PipeWire (ex `pw-play test.wav`)
+   - Notice how audio now goes through JACK
+5. Stop JACK
+   - through `qjackctl`, click `Stop`
+   - or manually: `qdbus org.jackaudio.service /org/jackaudio/Controller org.jackaudio.JackControl.StopServer`
+6. Wait a few seconds and run `wpctl status` to inspect
+   - The devices that were release by JACK should again be available
+   - There should be no `JACK System` endpoint
+
+> You may also start WirePlumber *after* starting JACK. It should immediately
+go to the state described in step 3

docs/index.md

@@ -28,5 +28,5 @@ and to write custom session managers for embedded devices.
 
 ## Resources
 
- * [Contribute to WirePlumber](contributing.md)
+ * [Contribute to WirePlumber](contributing/contributing.md)
  * [Reach out to the community](community.md)

docs/sitemap.txt

@@ -4,5 +4,6 @@ index.md
 		daemon/configuration.md
 		daemon/log.md
 	gi-index
-	contributing.md
+	contributing/contributing.md
+		contributing/testing.md
 	community.md