This provides basic instructions for running tests but doesn't try to exhaustively describe the whole setup.
Signed-off-by: Alex Bennée <[email protected]> --- v2 - add link to testing docs. --- .agents/skills/qemu-testing/SKILL.md | 56 ++++++++++++++++++++++++++++ AGENTS.md | 1 + 2 files changed, 57 insertions(+) create mode 100644 .agents/skills/qemu-testing/SKILL.md diff --git a/.agents/skills/qemu-testing/SKILL.md b/.agents/skills/qemu-testing/SKILL.md new file mode 100644 index 00000000000..e5979dfc1c5 --- /dev/null +++ b/.agents/skills/qemu-testing/SKILL.md @@ -0,0 +1,56 @@ +--- +name: qemu-testing +description: Provides instructions on how to find, list, and run individual tests for QEMU (Unit, QTest, Functional, TCG). You MUST use this skill whenever the user asks about tests, wants to list available tests, or wants to run any test in a build directory, even for simple exploratory queries like "what tests can I run". It includes details about spawning sub-agents. +license: GPL-2.0-or-later +--- + +# Instructions +To run QEMU tests, you can use several different suites depending on what you are testing. **Note**: Ensure you have a recent build of QEMU before running tests. Use the `qemu-build` skill if you need to configure or run a build. + +For exhaustive details on the testing infrastructure, architectures, and specific test requirements, you MUST refer to the official documentation in: +- `docs/devel/testing/` (specifically `main.rst`) + +## General Test Suites +- **Unit Tests**: `make check-unit` +- **QTest (Device emulation)**: `make check-qtest` +- **Functional Tests (Python based)**: `make check-functional` +- **TCG Tests (CPU instruction tests)**: `make check-tcg` + +## Launching Tests +**Crucial**: You MUST NEVER run a test suites directly in the main agent context. You MUST ALWAYS launch them by spawning a sub-agent. Pass the specific build or test commands, along with the required build directory, in the `task` argument. Give the subagent explicit instructions on what to verify and what to report back to you. +For example: `task: "Navigate to builds/debug and check what meson tests touch replay and report back."` or `task: "Run make check-tcg in builds/arm and summarize any failing tests."` + +### From the Build Directory +Most individual tests from within a build directory. Most (unit, qtest, block, functional) can be individually selected and run via meson. + +As QEMU often needs a newer meson than the build host you should use the build `pyenv` to launch it: +- **Example**: `./pyvenv/bin/meson test --suite thorough --list` to see what tests are in the thorough test suite + +## Running Individual Tests + +### Meson Test Runner (Unit, QTest, Functional, softfloat etc) +To run a single test, you can use the meson test runner from within your pyvenv: +`./pyvenv/bin/meson test [testname]` +Example: `./pyvenv/bin/meson test qtest-x86_64/boot-serial-test` + +### TCG Tests +To run individual TCG tests for a specific architecture: +1. Navigate to the relevant build directory, e.g.: `cd tests/tcg/aarch64-softmmu` +2. Run a specific test with make: `make run-[testname]` + Example: `make run-memory-sve` +3. Use `make help` within the architecture directory to see the full list of available tests. + +### Functional Tests +Individual functional tests can be run directly using the run script although from the source directory: +- **Example**: `./builds/all/run tests/functional/aarch64/test_virt_vbsa.py` + +### Environment Variables +- `V=1` for verbose output from tests. +- `SPEED=slow` to run slower tests that are normally skipped. + +## Reporting Results +**Crucial**: After completing the build and test tasks, provide a concise summary of the results to the calling agent. +1. **Summary**: State whether the build and tests passed or failed. +2. **Failure Excerpts**: If any task fails, include relevant excerpts from the logs (e.g., compiler errors, test failures). +3. **Full Paths**: Always provide the **absolute file paths** to the full logs and result sets for further inspection. + diff --git a/AGENTS.md b/AGENTS.md index 29a13ca01b4..f5439282967 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,6 +32,7 @@ If unsure read the linked document for guidance. You should use the following specialized skills for common tasks: - `qemu-code-explorer`: For finding where things are defined, how they're used, or understanding a specific subsystem. - `qemu-build`: For configuring and building QEMU (including debug and sanitizer builds). +- `qemu-testing`: For finding, listing, and running individual tests (Unit, QTest, Functional, TCG). ## Source Code Layout (see `docs/devel/codebase.rst`) - **`accel/`**: Hardware accelerators (KVM, TCG, HVF, Xen, etc.) and architecture-agnostic acceleration code. -- 2.47.3
