@samitouri / QOSamiQemu
Code Commits Issues Pulls Sessions CI/CD
master
master
rst 137 lines 4.11 KB
Raw
1 .. _qtest:
2
3 ========================================
4 QTest Device Emulation Testing Framework
5 ========================================
6
7 .. toctree::
8
9 qgraph
10
11 QTest is a device emulation testing framework. It can be very useful to test
12 device models; it could also control certain aspects of QEMU (such as virtual
13 clock stepping), with a special purpose "qtest" protocol. Refer to
14 :ref:`qtest-protocol` for more details of the protocol.
15
16 QTest cases can be executed with
17
18 .. code::
19
20 make check-qtest
21
22 The QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is
23 defined in ``tests/qtest/libqtest.h``.
24
25 Consider adding a new QTest case when you are introducing a new virtual
26 hardware, or extending one if you are adding functionalities to an existing
27 virtual device.
28
29 On top of libqtest, a higher level library, ``libqos``, was created to
30 encapsulate common tasks of device drivers, such as memory management and
31 communicating with system buses or devices. Many virtual device tests use
32 libqos instead of directly calling into libqtest.
33 Libqos also offers the Qgraph API to increase each test coverage and
34 automate QEMU command line arguments and devices setup.
35 Refer to :ref:`qgraph` for Qgraph explanation and API.
36
37 Steps to add a new QTest case are:
38
39 1. Create a new source file for the test. (More than one file can be added as
40 necessary.) For example, ``tests/qtest/foo-test.c``.
41
42 2. Write the test code with the glib and libqtest/libqos API. See also existing
43 tests and the library headers for reference.
44
45 3. Register the new test in ``tests/qtest/meson.build``. Add the test
46 executable name to an appropriate ``qtests_*`` variable. There is
47 one variable per architecture, plus ``qtests_generic`` for tests
48 that can be run for all architectures. For example::
49
50 qtests_generic = [
51 ...
52 'foo-test',
53 ...
54 ]
55
56 4. If the test has more than one source file or needs to be linked with any
57 dependency other than ``qemuutil`` and ``qos``, list them in the ``qtests``
58 dictionary. For example a test that needs to use the ``QIO`` library
59 will have an entry like::
60
61 {
62 ...
63 'foo-test': [io],
64 ...
65 }
66
67 Debugging a QTest failure is slightly harder than the unit test because the
68 tests look up QEMU program names in the environment variables, such as
69 ``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy
70 to attach gdb to the QEMU process spawned from the test. But manual invoking
71 and using gdb on the test is still simple to do: find out the actual command
72 from the output of
73
74 .. code::
75
76 make check-qtest V=1
77
78 which you can run manually.
79
80
81 .. _qtest-protocol:
82
83 QTest Protocol
84 --------------
85
86 .. kernel-doc:: system/qtest.c
87 :doc: QTest Protocol
88
89
90 libqtest API reference
91 ----------------------
92
93 .. kernel-doc:: tests/qtest/libqtest.h
94
95
96 QTest valid environment variables
97 ---------------------------------
98
99 A few environment variables are used to point QTest at artifacts to be
100 used in the tests, mostly QEMU binaries or to control the behavior of
101 the tests. Environment variables are set automatically by the build
102 system, but it can be useful to alter them when running tests
103 manually. The following are the environment variables recognized by
104 QTest, not including test-specific ones:
105
106 ``QTEST_QEMU_BINARY``
107 The QEMU binary itself (generally a ``qemu-system-<arch>`` binary).
108
109 ``QTEST_QEMU_ARGS``
110 Extra arguments for the QEMU command line.
111
112 ``QTEST_QEMU_IMG``
113 The ``qemu-img`` binary.
114
115 ``QTEST_QEMU_STORAGE_DAEMON_BINARY``
116 The ``qemu-storage-daemon`` binary.
117
118 ``QTEST_STOP``
119 Instruct QTest to stop the QEMU process with SIGSTOP before continuing
120 execution.
121
122 ``QTEST_LOG``
123 Comma-separated list of log domains to allow verbose logging.
124 The currently-defined log domains are:
125
126 ``qmp``
127 controls verbose output of QMP command invocations.
128
129 ``qtest``
130 controls verbose output of QTest operations.
131
132 ``test``
133 controls verbose output of tests.
134
135 A dash ``-`` used in front of a log domain name has the effect
136 of enabling verbose logging for all other domains while
137 keeping it disabled for the specified domain.