]>
Commit | Line | Data |
---|---|---|
a738a50e EH |
1 | ======================================== |
2 | QTest Device Emulation Testing Framework | |
3 | ======================================== | |
4 | ||
222455ef | 5 | .. toctree:: |
222455ef EGE |
6 | |
7 | qgraph | |
8 | ||
a738a50e EH |
9 | QTest is a device emulation testing framework. It can be very useful to test |
10 | device models; it could also control certain aspects of QEMU (such as virtual | |
f59c6de7 EH |
11 | clock stepping), with a special purpose "qtest" protocol. Refer to |
12 | :ref:`qtest-protocol` for more details of the protocol. | |
a738a50e EH |
13 | |
14 | QTest cases can be executed with | |
15 | ||
16 | .. code:: | |
17 | ||
18 | make check-qtest | |
19 | ||
20 | The QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is | |
21 | defined in ``tests/qtest/libqtest.h``. | |
22 | ||
23 | Consider adding a new QTest case when you are introducing a new virtual | |
24 | hardware, or extending one if you are adding functionalities to an existing | |
25 | virtual device. | |
26 | ||
27 | On top of libqtest, a higher level library, ``libqos``, was created to | |
28 | encapsulate common tasks of device drivers, such as memory management and | |
29 | communicating with system buses or devices. Many virtual device tests use | |
30 | libqos instead of directly calling into libqtest. | |
222455ef EGE |
31 | Libqos also offers the Qgraph API to increase each test coverage and |
32 | automate QEMU command line arguments and devices setup. | |
33 | Refer to :ref:`qgraph` for Qgraph explanation and API. | |
a738a50e EH |
34 | |
35 | Steps to add a new QTest case are: | |
36 | ||
37 | 1. Create a new source file for the test. (More than one file can be added as | |
38 | necessary.) For example, ``tests/qtest/foo-test.c``. | |
39 | ||
40 | 2. Write the test code with the glib and libqtest/libqos API. See also existing | |
41 | tests and the library headers for reference. | |
42 | ||
bab88ead PB |
43 | 3. Register the new test in ``tests/qtest/meson.build``. Add the test |
44 | executable name to an appropriate ``qtests_*`` variable. There is | |
45 | one variable per architecture, plus ``qtests_generic`` for tests | |
46 | that can be run for all architectures. For example:: | |
47 | ||
48 | qtests_generic = [ | |
49 | ... | |
50 | 'foo-test', | |
51 | ... | |
52 | ] | |
53 | ||
54 | 4. If the test has more than one source file or needs to be linked with any | |
55 | dependency other than ``qemuutil`` and ``qos``, list them in the ``qtests`` | |
56 | dictionary. For example a test that needs to use the ``QIO`` library | |
57 | will have an entry like:: | |
58 | ||
59 | { | |
60 | ... | |
61 | 'foo-test': [io], | |
62 | ... | |
63 | } | |
a738a50e EH |
64 | |
65 | Debugging a QTest failure is slightly harder than the unit test because the | |
66 | tests look up QEMU program names in the environment variables, such as | |
67 | ``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy | |
68 | to attach gdb to the QEMU process spawned from the test. But manual invoking | |
69 | and using gdb on the test is still simple to do: find out the actual command | |
70 | from the output of | |
71 | ||
72 | .. code:: | |
73 | ||
74 | make check-qtest V=1 | |
75 | ||
76 | which you can run manually. | |
77 | ||
f59c6de7 EH |
78 | |
79 | .. _qtest-protocol: | |
80 | ||
81 | QTest Protocol | |
82 | -------------- | |
83 | ||
84 | .. kernel-doc:: softmmu/qtest.c | |
85 | :doc: QTest Protocol | |
51c778ed EH |
86 | |
87 | ||
88 | libqtest API reference | |
89 | ---------------------- | |
90 | ||
907b5105 | 91 | .. kernel-doc:: tests/qtest/libqtest.h |