Re: [PATCH v1 3/3] docs/devel/qtest: Mention environment variables usage

[Fabiano Rosas <farosas@suse.de>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Wed, 29 Apr 2026 at 01:31, Fabiano Rosas <farosas@suse.de> wrote:
>>
>> Document the QTEST_ environment variables. Only include the ones used
>> by QTest itself, don't document test-specific variables as they are
>> more prone to change.
>>
>> Suggested-by: Peter Maydell <peter.maydell@linaro.org>
>> Signed-off-by: Fabiano Rosas <farosas@suse.de>
>> ---
>>  docs/devel/testing/qtest.rst | 33 +++++++++++++++++++++++++++++++++
>>  1 file changed, 33 insertions(+)
>>
>> diff --git a/docs/devel/testing/qtest.rst b/docs/devel/testing/qtest.rst
>> index 73ef7702b7..0aac0f0aaf 100644
>> --- a/docs/devel/testing/qtest.rst
>> +++ b/docs/devel/testing/qtest.rst
>> @@ -91,3 +91,36 @@ libqtest API reference
>>  ----------------------
>>
>>  .. kernel-doc:: tests/qtest/libqtest.h
>> +
>> +
>> +QTest valid environment variables
>> +---------------------------------
>> +
>> +A few environment variables are used to point QTest at artifacts to be
>> +used in the tests, mostly QEMU binaries or to control the behavior of
>> +the tests. Environment variables are set automatically by the build
>> +system, but it can be useful to alter them when running tests
>> +manually. The following are the environment variables recognized by
>> +QTest, not including test-specific ones:
>> +
>> +QTEST_QEMU_BINARY - The QEMU binary itself
>> +
>> +QTEST_QEMU_ARGS - Extra arguments for the QEMU command line
>> +
>> +QTEST_QEMU_IMG - The qemu-img binary
>> +
>> +QTEST_QEMU_STORAGE_DAEMON_BINARY - The qemu-storage-daemon binary
>> +
>> +QTEST_STOP - Instruct QTest to stop the QEMU process with SIGSTOP before continuing execution.
>> +
>> +QTEST_LOG - Comma-separated list of log domains to allow verbose logging. Basic log domains include:
>> +
>> +           qmp - controls verbose output of QMP command invocations.
>> +
>> +           qtest - controls verbose ouput of qtest operations.
>
> "output"
>
>> +
>> +           test - controls verbose output of tests.
>> +
>> +           A dash '-' used in front of a log domain has the effect of
>> +           enabling verbose logging for all other domains while
>> +           keeping it disabled for the specified domain.
>
> We could write this using rST definition-lists, which I think
> makes the generated HTML look a little nicer. Here's a version
> which is basically the same text but with a little more rST
> markup sprinkled over it:
>
> ===begin===
> +
> +
> +QTest valid environment variables
> +---------------------------------
> +
> +A few environment variables are used to point QTest at artifacts to be
> +used in the tests, mostly QEMU binaries or to control the behavior of
> +the tests. Environment variables are set automatically by the build
> +system, but it can be useful to alter them when running tests
> +manually. The following are the environment variables recognized by
> +QTest, not including test-specific ones:
> +
> +``QTEST_QEMU_BINARY``
> +    The QEMU binary itself (generally a ``qemu-system-<arch>`` binary).
> +
> +``QTEST_QEMU_ARGS``
> +    Extra arguments for the QEMU command line.
> +
> +``QTEST_QEMU_IMG``
> +    The ``qemu-img`` binary.
> +
> +``QTEST_QEMU_STORAGE_DAEMON_BINARY``
> +    The ``qemu-storage-daemon`` binary.
> +
> +``QTEST_STOP``
> +    Instruct QTest to stop the QEMU process with SIGSTOP before continuing
> +    execution.
> +
> +``QTEST_LOG``
> +    Comma-separated list of log domains to allow verbose logging.
> +    The currently-defined log domains are:
> +
> +    ``qmp``
> +        controls verbose output of QMP command invocations.
> +
> +    ``qtest``
> +        controls verbose output of QTest operations.
> +
> +    ``test``
> +        controls verbose output of tests.
> +
> +    A dash ``-`` used in front of a log domain name has the effect
> +    of enabling verbose logging for all other domains while
> +    keeping it disabled for the specified domain.
> ===endit===
>

Excellent, thank you for this.

> Either way,
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
>


> thanks
> -- PMM