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