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

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

[Peter Maydell]

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

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
with other uses of the run script
---
 docs/devel/testing/main.rst | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/docs/devel/testing/main.rst b/docs/devel/testing/main.rst
index b0ca37fe2ba..3195f997e85 100644
--- a/docs/devel/testing/main.rst
+++ 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
 
 It's also possible to list test numbers explicitly:
 
 .. code::
 
   # run selected cases with qcow2 format
-  ./check -qcow2 001 030 153
+  ./run ./tests/qemu-iotests/check -qcow2 001 030 153
 
 Cache mode can be selected with the "-c" option, which may help reveal bugs
 that are specific to certain cache mode.
 
-More options are supported by the ``./check`` script, run ``./check -h`` for
-help.
+More options are supported by the ``check`` script; run
+``./tests/qemu-iotests/check -h`` for help.
 
 Writing a new test case
 ~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.43.0

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

[Daniel P. Berrangé]

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
> 
> 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
> with other uses of the run script
> ---
>  docs/devel/testing/main.rst | 20 ++++++++++++--------
>  1 file changed, 12 insertions(+), 8 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|

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

[Pierrick Bouvier]

On 11/6/2026 9:01 AM, 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
> 
> 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
> with other uses of the run script
> ---
>  docs/devel/testing/main.rst | 20 ++++++++++++--------
>  1 file changed, 12 insertions(+), 8 deletions(-)
> 

Reviewed-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>

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

[Eric Blake]

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

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

[Daniel P. Berrangé]

On Fri, Nov 06, 2026 at 01:55:39PM -0600, Eric Blake wrote:
> 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
> ...

Beyond that warning, the 'check' script has bad heuristics for
finding the build directory, looking for 'cwd' in this particular
case which is wrong. I've sent a path that addresses this which
does the job in my testing at least.

> but running directly from the configured directory:
> 
> $ cd build
> $ ./run tets/qemu-iotests/check 5
> 
> does what this patch recommends.
> 

With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|