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