Re: [PATCH v2 for-11.2] docs/devel/testing: iotests check script should be run via 'run'

[Eric Blake <eblake@redhat.com>]

On Fri, Nov 06, 2026 at 05:01:57PM +0000, Peter Maydell wrote:
> The iotests section of the testing documentation suggests directly
> running the "./check" script.  However if you do this then the
> script complains:
> 
> WARNING: iotests is being run from outside of the configure-time python virtual environment
> [...]
> Please use the meson run script:
>         /home/pm215/qemu/build/x86-tgt-san-dbg/run ./check

Huh. I did a git checkout, mkdir build, cd build && ../configure, then:

$ build/run tests/qemu-iotests/check 5

WARNING: iotests is being run from outside of the configure-time python virtual environment

current python: /home/eblake/qemu/build/pyvenv/bin/python3
pyvenv python:  /home/pyvenv/bin/python3
...

but running directly from the configured directory:

$ cd build
$ ./run tets/qemu-iotests/check 5

does what this patch recommends.

> 
> Update the documentation to match this.  While we are here,
> standardize on "run from the root of the build tree", which is how we
> generally document running things under "run" (e.g.  the functional
> tests), since the iotests don't have a dependency on their current
> working directory.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> v1->v2: Use "./run ./tests-qemu-iotests/check", for consistency

Typo in the notes - but those don't make it into git, so that one is
irrelevant.

> +++ b/docs/devel/testing/main.rst
> @@ -271,9 +271,13 @@ than "make check" tests and 99% of the code is written in bash or Python
>  scripts.  The testing success criteria is golden output comparison, and the
>  test files are named with numbers.
>  
> -To run iotests, make sure QEMU is built successfully, then switch to the
> -``tests/qemu-iotests`` directory under the build directory, and run ``./check``
> -with desired arguments from there.
> +To run iotests, make sure QEMU is built successfully, then switch to
> +the build tree and run the ``tests/qemu-iotests/check`` script via the
> +``run`` wrapper which sets up the environment:
> +
> +.. code::
> +
> +   ./run ./tests/qemu-iotests/check [args]
>  
>  By default, "raw" format and "file" protocol is used; all tests will be
>  executed, except the unsupported ones. You can override the format and protocol
> @@ -282,22 +286,22 @@ with arguments:
>  .. code::
>  
>    # test with qcow2 format
> -  ./check -qcow2
> +  ./run ./tests/qemu-iotests/check -qcow2
>    # or test a different protocol
> -  ./check -nbd
> +  .run ./tests/qemu-iotests/check -nbd

"./run", not ".run".

With that typo fixed,

Reviewed-by: Eric Blake <eblake@redhat.com>

Technically, "tests/qemu-iotests" and "./tests/qemu-iotests" will have
the same behavior to ./run, but while your variant is slightly longer
to type, I don't see a problem in spelling it that way.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org