Debian Codegraph @

docs/rst/resources/testing.rst

raw
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