1*a738a50eSEduardo Habkost======================================== 2*a738a50eSEduardo HabkostQTest Device Emulation Testing Framework 3*a738a50eSEduardo Habkost======================================== 4*a738a50eSEduardo Habkost 5*a738a50eSEduardo HabkostQTest is a device emulation testing framework. It can be very useful to test 6*a738a50eSEduardo Habkostdevice models; it could also control certain aspects of QEMU (such as virtual 7*a738a50eSEduardo Habkostclock stepping), with a special purpose "qtest" protocol. Refer to the 8*a738a50eSEduardo Habkostdocumentation in ``qtest.c`` for more details of the protocol. 9*a738a50eSEduardo Habkost 10*a738a50eSEduardo HabkostQTest cases can be executed with 11*a738a50eSEduardo Habkost 12*a738a50eSEduardo Habkost.. code:: 13*a738a50eSEduardo Habkost 14*a738a50eSEduardo Habkost make check-qtest 15*a738a50eSEduardo Habkost 16*a738a50eSEduardo HabkostThe QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is 17*a738a50eSEduardo Habkostdefined in ``tests/qtest/libqtest.h``. 18*a738a50eSEduardo Habkost 19*a738a50eSEduardo HabkostConsider adding a new QTest case when you are introducing a new virtual 20*a738a50eSEduardo Habkosthardware, or extending one if you are adding functionalities to an existing 21*a738a50eSEduardo Habkostvirtual device. 22*a738a50eSEduardo Habkost 23*a738a50eSEduardo HabkostOn top of libqtest, a higher level library, ``libqos``, was created to 24*a738a50eSEduardo Habkostencapsulate common tasks of device drivers, such as memory management and 25*a738a50eSEduardo Habkostcommunicating with system buses or devices. Many virtual device tests use 26*a738a50eSEduardo Habkostlibqos instead of directly calling into libqtest. 27*a738a50eSEduardo Habkost 28*a738a50eSEduardo HabkostSteps to add a new QTest case are: 29*a738a50eSEduardo Habkost 30*a738a50eSEduardo Habkost1. Create a new source file for the test. (More than one file can be added as 31*a738a50eSEduardo Habkost necessary.) For example, ``tests/qtest/foo-test.c``. 32*a738a50eSEduardo Habkost 33*a738a50eSEduardo Habkost2. Write the test code with the glib and libqtest/libqos API. See also existing 34*a738a50eSEduardo Habkost tests and the library headers for reference. 35*a738a50eSEduardo Habkost 36*a738a50eSEduardo Habkost3. Register the new test in ``tests/qtest/Makefile.include``. Add the test 37*a738a50eSEduardo Habkost executable name to an appropriate ``check-qtest-*-y`` variable. For example: 38*a738a50eSEduardo Habkost 39*a738a50eSEduardo Habkost ``check-qtest-generic-y = tests/qtest/foo-test$(EXESUF)`` 40*a738a50eSEduardo Habkost 41*a738a50eSEduardo Habkost4. Add object dependencies of the executable in the Makefile, including the 42*a738a50eSEduardo Habkost test source file(s) and other interesting objects. For example: 43*a738a50eSEduardo Habkost 44*a738a50eSEduardo Habkost ``tests/qtest/foo-test$(EXESUF): tests/qtest/foo-test.o $(libqos-obj-y)`` 45*a738a50eSEduardo Habkost 46*a738a50eSEduardo HabkostDebugging a QTest failure is slightly harder than the unit test because the 47*a738a50eSEduardo Habkosttests look up QEMU program names in the environment variables, such as 48*a738a50eSEduardo Habkost``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy 49*a738a50eSEduardo Habkostto attach gdb to the QEMU process spawned from the test. But manual invoking 50*a738a50eSEduardo Habkostand using gdb on the test is still simple to do: find out the actual command 51*a738a50eSEduardo Habkostfrom the output of 52*a738a50eSEduardo Habkost 53*a738a50eSEduardo Habkost.. code:: 54*a738a50eSEduardo Habkost 55*a738a50eSEduardo Habkost make check-qtest V=1 56*a738a50eSEduardo Habkost 57*a738a50eSEduardo Habkostwhich you can run manually. 58*a738a50eSEduardo Habkost 59