| name | qemu-qtest |
| description | Use as a QEMU flow primitive for QEMU qtest design, registration, execution, and immediate qtest evidence capture. |
QEMU qtest
Use this operational/domain skill for QEMU device and board tests using the qtest framework.
Primitive Boundary
This primitive owns only qtest design, registration, execution commands, and
immediate qtest evidence. It consumes a behavior claim, source tree, build
directory, and artifact root supplied by the caller and does not choose build,
debug, verification, or iterative-fix workflow steps.
Hard policy boundary
Do not produce source code intended for QEMU upstream submission. Do not add DCO or review trailers.
What qtest should prove
Use qtest for:
- MMIO/PIO register contracts;
- reset behavior;
- IRQ assertion/deassertion;
- virtual clock/timer behavior;
- QMP-visible state and hotplug;
- board instantiation and memory-map probes;
- simple DMA or guest-memory effects.
Prefer qtest over boot smoke for device contracts.
Running qtests
Run from a configured build directory. Default to build/.
List tests:
build/pyvenv/bin/meson test -C build --list
Run one test:
build/pyvenv/bin/meson test -C build qtest-riscv64/<test-name>
Make frontends from inside build/:
make check-qtest
make check-qtest-riscv64
V=1 make check-qtest-riscv64
Use the narrow Meson test name when possible.
Finding/registering tests
Inspect:
tests/qtest/meson.build for architecture buckets;
tests/qtest/<name>.c for source;
tests/qtest/libqtest.h for API;
build/meson-logs/testlog.txt for failures.
Register architecture-specific tests under the matching qtests_<arch> list. Use qtests_generic only when the test is truly architecture-independent.
Useful libqtest APIs
- startup/shutdown:
qtest_init(), qtest_initf(), qtest_quit();
- reset:
qtest_system_reset();
- QMP/HMP:
qtest_qmp(), qtest_qmp_assert_success(), qtest_qmp_eventwait(), qtest_hmp();
- MMIO:
qtest_readb/readw/readl/readq(), qtest_writeb/writew/writel/writeq();
- memory:
qtest_memread(), qtest_memwrite(), qtest_memset();
- PIO:
qtest_inb/inw/inl(), qtest_outb/outw/outl();
- IRQ:
qtest_irq_intercept_in(), qtest_irq_intercept_out(), qtest_set_irq_in();
- virtual clock:
qtest_clock_step_next(), qtest_clock_step(), qtest_clock_set().
Use libqos/qgraph when nearby subsystem tests already do.
Device qtest checklist
- reset values;
- masks and reserved bits;
- read-only/write-only/W1C behavior;
- unsupported width behavior when guest-visible;
- IRQ level and clear path;
- virtual-clock timer expiry;
- DMA guest-memory effects;
- dirty-state reset.
Debugging qtests
Qtest environment variables include:
QTEST_QEMU_BINARY
QTEST_QEMU_ARGS
QTEST_QEMU_IMG
QTEST_QEMU_STORAGE_DAEMON_BINARY
QTEST_STOP
QTEST_LOG
Use verbose test output to recover exact commands. Use QTEST_STOP=1 when attaching a debugger to spawned QEMU is needed.
Portability rules
- Use GLib temp/file APIs.
- Avoid hardcoded
/tmp.
- Avoid POSIX-only paths unless guarded.
- Use double quotes in extra QEMU command-line strings.
- Open binary files in binary mode when data comparison matters.
Report
Include:
- PASS/FAIL/INCONCLUSIVE;
- build dir;
- exact command;
- qtest name;
- decisive excerpt;
- log path;
- behavior proven and not proven.
Upstream references
- QEMU code provenance and AI policy:
docs/devel/code-provenance.rst.
- QEMU RFC
qemu-testing skill.
- Testing overview:
docs/devel/testing/main.rst.
- QTest docs:
docs/devel/testing/qtest.rst.
- API:
tests/qtest/libqtest.h.