1======================================== 2QTest Device Emulation Testing Framework 3======================================== 4 5.. toctree:: 6 7 qgraph 8 9QTest is a device emulation testing framework. It can be very useful to test 10device models; it could also control certain aspects of QEMU (such as virtual 11clock stepping), with a special purpose "qtest" protocol. Refer to 12:ref:`qtest-protocol` for more details of the protocol. 13 14QTest cases can be executed with 15 16.. code:: 17 18 make check-qtest 19 20The QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is 21defined in ``tests/qtest/libqtest.h``. 22 23Consider adding a new QTest case when you are introducing a new virtual 24hardware, or extending one if you are adding functionalities to an existing 25virtual device. 26 27On top of libqtest, a higher level library, ``libqos``, was created to 28encapsulate common tasks of device drivers, such as memory management and 29communicating with system buses or devices. Many virtual device tests use 30libqos instead of directly calling into libqtest. 31Libqos also offers the Qgraph API to increase each test coverage and 32automate QEMU command line arguments and devices setup. 33Refer to :ref:`qgraph` for Qgraph explanation and API. 34 35Steps to add a new QTest case are: 36 371. 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 402. Write the test code with the glib and libqtest/libqos API. See also existing 41 tests and the library headers for reference. 42 433. 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 544. 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 } 64 65Debugging a QTest failure is slightly harder than the unit test because the 66tests 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 68to attach gdb to the QEMU process spawned from the test. But manual invoking 69and using gdb on the test is still simple to do: find out the actual command 70from the output of 71 72.. code:: 73 74 make check-qtest V=1 75 76which you can run manually. 77 78 79.. _qtest-protocol: 80 81QTest Protocol 82-------------- 83 84.. kernel-doc:: system/qtest.c 85 :doc: QTest Protocol 86 87 88libqtest API reference 89---------------------- 90 91.. kernel-doc:: tests/qtest/libqtest.h 92