docs/devel/qtest.rst

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