Features/QTest

Summary

QTest is an internal framework used in the QEMU unit tests. A QTest based test will spin up one or more QEMU binaries and orchestrate the test via a qtest control socket. The binaries themselves are usually controlled using a QMP socket to trigger events.

Debugging

Usually the first problem a new developer comes across is understanding how a test fails. The qtest tests are all grouped together by target architectures so the first step is to re-run make check for the particular architecture that failed:

   make check-qtest-i386 V=1

The test run will now dump a lot more information about how the test is run. This will be a gtester call with a large number of tests included. This can then be repeated with just the tests you want. For example:

   QTEST_QEMU_BINARY=i386-softmmu/qemu-system-i386 QTEST_QEMU_IMG=qemu-img MALLOC_PERTURB_=${MALLOC_PERTURB_:-$((RANDOM % 255 + 1))} gtester -k --verbose -m=quick tests tests/vhost-user-test

For additional information you can set QTEST_LOG and also use qtester -p to specify the subtest you want to run:

   QTEST_LOG=1 QTEST_QEMU_BINARY=i386-softmmu/qemu-system-i386 QTEST_QEMU_IMG=qemu-img MALLOC_PERTURB_=${MALLOC_PERTURB_:-$((RANDOM % 255 + 1))} gtester -k --verbose -m=quick tests/vhost-user-test -p /i386/vhost-user/migrate

Since the QEMU binary is run as a separate process, it can be awkward to attach a gdb to it. You can use a command like this to get the test harness to start a new xterm with a gdb in it for each test it runs:

   QTEST_QEMU_BINARY="xterm -e gdb --tty $(tty) --args aarch64-softmmu/qemu-system-aarch64" QTEST_QEMU_IMG=qemu-img gtester -k --verbose -m=quick  tests/device-introspect-test

The gdb will get control before the QEMU process has done anything, so you can set breakpoints and so on before using 'continue' to make it start execution.

Implementation

Please see tests/libqtest.h for device test APIs. Search the tests/ directory for examples using libqtest.