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