| 1 |
.. _resources_testing: |
| 2 |
|
| 3 |
Testing |
| 4 |
======= |
| 5 |
|
| 6 |
Automated unit tests |
| 7 |
-------------------- |
| 8 |
|
| 9 |
WirePlumber has automated tests that you can easily run with: |
| 10 |
|
| 11 |
.. code:: console |
| 12 |
|
| 13 |
$ meson test -C build |
| 14 |
|
| 15 |
This will automatically compile all test dependencies, so you can be sure |
| 16 |
that this always tests your latest changes. |
| 17 |
|
| 18 |
If you wish to run a specific test instead of all of them, you can run: |
| 19 |
|
| 20 |
.. code:: console |
| 21 |
|
| 22 |
$ meson test -C build test-name |
| 23 |
|
| 24 |
When debugging a single test, you can additionally enable verbose test output |
| 25 |
by appending ``-v`` and you can also run the test in gdb by appending ``--gdb``. |
| 26 |
|
| 27 |
For more information on how to use ``meson test``, please refer to |
| 28 |
`meson's manual <https://mesonbuild.com/Unit-tests.html>`_ |
| 29 |
|
| 30 |
.. important:: |
| 31 |
|
| 32 |
When submitting changes for review, always ensure that all tests pass |
| 33 |
|
| 34 |
Please note that many WirePlumber tests require specific SPA test plugins |
| 35 |
to be available in your PipeWire installation. More specifically, PipeWire |
| 36 |
needs to be configured with the following options enabled: |
| 37 |
|
| 38 |
.. code:: console |
| 39 |
|
| 40 |
-Dvideotestsrc=true -Daudiotestsrc=true -Dtest=true |
| 41 |
|
| 42 |
If these SPA plugins are not found in the system, some tests will fail. |
| 43 |
This is expected. |
| 44 |
|
| 45 |
WirePlumber examples |
| 46 |
-------------------- |
| 47 |
|
| 48 |
WirePlumber ships examples in ``test/examples``. |
| 49 |
Execute them from the top-level directory with ``wp-uninstalled.sh``: |
| 50 |
|
| 51 |
.. code:: console |
| 52 |
|
| 53 |
$ ./wp-uninstalled.sh ./build/tests/examples/audiotestsrc-play |
| 54 |
|
| 55 |
|
| 56 |
Assuming there is no other process actively using ``hw:0,0`` from alsa, |
| 57 |
the above example should play a test tone on ``hw:0,0`` without errors. |
| 58 |
|
| 59 |
Native API clients |
| 60 |
------------------ |
| 61 |
|
| 62 |
pw-cat |
| 63 |
^^^^^^ |
| 64 |
|
| 65 |
Using the default device: |
| 66 |
|
| 67 |
.. code:: console |
| 68 |
|
| 69 |
$ wpctl status # verify the default device |
| 70 |
$ pw-record test.wav |
| 71 |
$ pw-play test.wav |
| 72 |
|
| 73 |
|
| 74 |
Using a non-default device: |
| 75 |
|
| 76 |
.. code:: console |
| 77 |
|
| 78 |
$ pw-record --list-targets # find the node id |
| 79 |
$ pw-record --target <node_id> test.wav |
| 80 |
$ pw-play --list-targets # find the node id |
| 81 |
$ pw-play --target <node_id> test.wav |
| 82 |
|
| 83 |
or |
| 84 |
|
| 85 |
.. code:: console |
| 86 |
|
| 87 |
$ wpctl status # find the capture & playback node ids |
| 88 |
$ pw-record --target <node_id> test.wav |
| 89 |
$ pw-play --target <node_id> test.wav |
| 90 |
|
| 91 |
.. note:: |
| 92 |
|
| 93 |
node ids can be used interchangeably when specifying targets in all use cases |
| 94 |
|
| 95 |
video-play |
| 96 |
^^^^^^^^^^ |
| 97 |
|
| 98 |
Using the default device: |
| 99 |
|
| 100 |
.. code:: console |
| 101 |
|
| 102 |
$ cd path/to/pipewire-source-dir |
| 103 |
$ ./build/src/examples/video-play |
| 104 |
|
| 105 |
|
| 106 |
Using a non-default device: |
| 107 |
|
| 108 |
.. code:: console |
| 109 |
|
| 110 |
$ wpctl status # find the device node id from the list |
| 111 |
$ cd path/to/pipewire-source-dir |
| 112 |
$ ./build/src/examples/video-play <node_id> |
| 113 |
|
| 114 |
.. tip:: |
| 115 |
|
| 116 |
enable videotestsrc in wireplumber's configuration to have more video |
| 117 |
sources available |
| 118 |
|
| 119 |
PulseAudio compat API clients |
| 120 |
----------------------------- |
| 121 |
|
| 122 |
pacat |
| 123 |
^^^^^ |
| 124 |
|
| 125 |
Using the default device: |
| 126 |
|
| 127 |
.. code:: console |
| 128 |
|
| 129 |
$ wpctl status # verify the default device |
| 130 |
$ parecord test.wav |
| 131 |
$ paplay test.wav |
| 132 |
|
| 133 |
pavucontrol |
| 134 |
^^^^^^^^^^^ |
| 135 |
|
| 136 |
Use the command: |
| 137 |
|
| 138 |
.. code:: console |
| 139 |
|
| 140 |
$ pavucontrol |
| 141 |
|
| 142 |
* Volume level meters should work |
| 143 |
* Changing the volume should work |
| 144 |
|
| 145 |
ALSA compat API clients |
| 146 |
----------------------- |
| 147 |
|
| 148 |
aplay / arecord |
| 149 |
^^^^^^^^^^^^^^^ |
| 150 |
|
| 151 |
.. note:: |
| 152 |
|
| 153 |
unless you have installed PipeWire in the default system prefix |
| 154 |
(``/usr``), the ALSA compat API will not work, unless you copy |
| 155 |
``libasound_module_pcm_pipewire.so`` in the alsa plugins directory |
| 156 |
(usually ``/usr/<libdir>/alsa-lib/``) and that you add the contents of |
| 157 |
``pipewire-alsa/conf/50-pipewire.conf`` in your ``~/.asoundrc`` |
| 158 |
(or anywhere else, system-wide, where libasound can read it) |
| 159 |
|
| 160 |
Using the default device: |
| 161 |
|
| 162 |
.. code:: console |
| 163 |
|
| 164 |
$ wpctl status # verify the default devices |
| 165 |
$ arecord -D pipewire -f S16_LE -r 48000 test.wav |
| 166 |
$ aplay -D pipewire test.wav |
| 167 |
|
| 168 |
Using a non-default device: |
| 169 |
|
| 170 |
.. code:: console |
| 171 |
|
| 172 |
$ wpctl status # find the capture & playback node ids |
| 173 |
$ PIPEWIRE_NODE=<node_id> arecord -D pipewire -f S16_LE -r 48000 test.wav |
| 174 |
$ PIPEWIRE_NODE=<node_id> aplay -D pipewire test.wav |
| 175 |
|
| 176 |
or |
| 177 |
|
| 178 |
.. code:: console |
| 179 |
|
| 180 |
$ wpctl status # find the capture & playback device node ids |
| 181 |
$ arecord -D pipewire:NODE=<node_id> -f S16_LE -r 48000 test.wav |
| 182 |
$ aplay -D pipewire:NODE=<node_id> test.wav |
| 183 |
|
| 184 |
|
| 185 |
JACK compat API clients |
| 186 |
----------------------- |
| 187 |
|
| 188 |
qjackctl |
| 189 |
^^^^^^^^ |
| 190 |
|
| 191 |
.. code:: console |
| 192 |
|
| 193 |
$ pw-jack qjackctl |
| 194 |
|
| 195 |
* This should correctly connect. |
| 196 |
* The "Graph" window should show the PipeWire graph. |
| 197 |
|
| 198 |
jack_simple_client |
| 199 |
^^^^^^^^^^^^^^^^^^ |
| 200 |
|
| 201 |
.. code:: console |
| 202 |
|
| 203 |
$ wpctl status # find the target device node id |
| 204 |
$ wpctl inspect <node_id> # find the node.id |
| 205 |
$ PIPEWIRE_NODE=<node_id> pw-jack jack_simple_client |
| 206 |
|
| 207 |
.. note:: |
| 208 |
|
| 209 |
The JACK layer is not controlled by the session manager, it creates its own |
| 210 |
links; which is why it is required to specify a node id. |
| 211 |
|
| 212 |
Device Reservation |
| 213 |
------------------ |
| 214 |
|
| 215 |
with PulseAudio |
| 216 |
^^^^^^^^^^^^^^^ |
| 217 |
|
| 218 |
1. With PulseAudio running, start a pulseaudio client. |
| 219 |
|
| 220 |
.. code:: console |
| 221 |
|
| 222 |
$ gst-launch-1.0 audiotestsrc ! pulsesink |
| 223 |
|
| 224 |
2. Start PipeWire & WirePlumber |
| 225 |
|
| 226 |
- The device in use by PA will not be available in PW |
| 227 |
|
| 228 |
3. Stop the PA client |
| 229 |
|
| 230 |
- A few seconds later, WirePlumber should assume control of the device |
| 231 |
|
| 232 |
4. ``wpctl status`` should be able to confirm that the device is available |
| 233 |
|
| 234 |
5. Start a PA client again |
| 235 |
|
| 236 |
- It should not be able to play; it will just freeze |
| 237 |
|
| 238 |
6. Stop WirePlumber |
| 239 |
|
| 240 |
- The PA client should immediately start playing |
| 241 |
|
| 242 |
with JACK |
| 243 |
^^^^^^^^^ |
| 244 |
|
| 245 |
1. Start PipeWire & WirePlumber |
| 246 |
|
| 247 |
- All devices should be available |
| 248 |
|
| 249 |
2. Start ``jackdbus`` |
| 250 |
|
| 251 |
1. through ``qjackctl``: |
| 252 |
|
| 253 |
- Enable *Setup* -> *Misc* -> *Enable JACK D-Bus interface* |
| 254 |
- Click *Start* on the main window |
| 255 |
|
| 256 |
2. or manually: |
| 257 |
|
| 258 |
- Run ``jackdbus auto`` |
| 259 |
- Run ``qdbus org.jackaudio.service /org/jackaudio/Controller org.jackaudio.JackControl.StartServer`` |
| 260 |
|
| 261 |
3. Wait a few seconds and run ``wpctl status`` to inspect |
| 262 |
|
| 263 |
- The devices taken by JACK should no longer be available |
| 264 |
- There should be two *JACK System* nodes (sink & source) |
| 265 |
|
| 266 |
4. Run an audio client on PipeWire (ex ``pw-play test.wav``) |
| 267 |
|
| 268 |
- Notice how audio now goes through JACK |
| 269 |
|
| 270 |
5. Stop JACK |
| 271 |
|
| 272 |
- through ``qjackctl``, click *Stop* |
| 273 |
- or manually: ``qdbus org.jackaudio.service /org/jackaudio/Controller org.jackaudio.JackControl.StopServer`` |
| 274 |
|
| 275 |
6. Wait a few seconds and run ``wpctl status`` to inspect |
| 276 |
|
| 277 |
- The devices that were release by JACK should again be available |
| 278 |
- There should be no *JACK System* nodes |
| 279 |
|
| 280 |
.. note:: |
| 281 |
|
| 282 |
You may also start WirePlumber *after* starting JACK. It should immediately |
| 283 |
go to the state described in step 3 |