[PATCH v1 0/3] tests/qtest: Tweak env variables

[PATCH v1 0/3] tests/qtest: Tweak env variables

[Fabiano Rosas]

Allow QEMU command line options to be passed via an environment
variable, make QTEST_LOG more useful and document QTEST standard
variables.

CI run: https://gitlab.com/farosas/qemu/-/pipelines/2486792726

Fabiano Rosas (3):
  tests/qtest/libqtest: Replace QTEST_TRACE with QTEST_QEMU_ARGS
  tests/qtest: Individual verbose switches
  docs/devel/qtest: Mention environment variables usage

 docs/devel/testing/qtest.rst          | 33 +++++++++++++
 tests/qtest/fuzz/fuzz.c               |  7 +--
 tests/qtest/fuzz/generic_fuzz.c       |  2 +-
 tests/qtest/libqmp.c                  |  7 +--
 tests/qtest/libqtest.c                | 67 ++++++++++++++++++++++++---
 tests/qtest/libqtest.h                | 11 +++++
 tests/qtest/migration/framework.c     |  2 +-
 tests/qtest/migration/framework.h     |  5 +-
 tests/qtest/migration/precopy-tests.c |  2 +-
 tests/unit/meson.build                |  2 +-
 tests/unit/test-qga.c                 |  2 +-
 11 files changed, 120 insertions(+), 20 deletions(-)

-- 
2.51.0

[PATCH v1 1/3] tests/qtest/libqtest: Replace QTEST_TRACE with QTEST_QEMU_ARGS

[Fabiano Rosas]

The QTEST_TRACE environment variable allows for any QEMU command line
option to be passed if used like so:

export QTEST_TRACE="-trace tracepoint -more -opts -here"

Formalize that usage by accepting a new QTEST_QEMU_ARGS
variable. Since the QTEST_TRACE now becomes redundant, remove its
usage.

Signed-off-by: Fabiano Rosas <farosas@suse.de>
---
 tests/qtest/libqtest.c | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/tests/qtest/libqtest.c b/tests/qtest/libqtest.c
index 051faf31e1..a580d75179 100644
--- a/tests/qtest/libqtest.c
+++ b/tests/qtest/libqtest.c
@@ -454,11 +454,9 @@ gchar *qtest_qemu_args(const char *extra_args)
 {
     g_autofree gchar *socket_path = qtest_socket_path("sock");
     g_autofree gchar *qmp_socket_path = qtest_socket_path("qmp");
-    const char *trace = g_getenv("QTEST_TRACE");
-    g_autofree char *tracearg = trace ? g_strdup_printf("-trace %s ", trace) :
-                                        g_strdup("");
+    const char *args_from_env = g_getenv("QTEST_QEMU_ARGS");
+
     gchar *args = g_strdup_printf(
-                      "%s"
                       "-qtest unix:%s "
                       "-qtest-log %s "
                       "-chardev socket,path=%s,id=char0 "
@@ -466,16 +464,17 @@ gchar *qtest_qemu_args(const char *extra_args)
                       "-display none "
                       "-audio none "
                       "%s"
+                      "%s "
                       "%s"
                       " -accel qtest",
 
-                      tracearg,
                       socket_path,
                       getenv("QTEST_LOG") ? DEV_STDERR : DEV_NULL,
                       qmp_socket_path,
                       can_exit_with_parent() ?
                       "-run-with exit-with-parent=on " : "",
-                      extra_args ?: "");
+                      extra_args ?: "",
+                      args_from_env ?: "");
 
     return args;
 }
-- 
2.51.0

[PATCH v1 2/3] tests/qtest: Individual verbose switches

[Fabiano Rosas]

Allow logging to be set for specific parts of QTest. Having a single
QTEST_LOG knob creates an output stream that is almost useless due to
spamming from some operations.

Add a backward-compatible way of selecting which parts will be made
verbose. Reuse the existing QTEST_LOG variable. The new options are:

QTEST_LOG=
fuzz - fuzz.c
qga - unit/test-qga.c
qmp - libqmp.c
qtest - QTest device, i.e. -qtest-log option
test - generic term for usage of all tests

E.g.:

QTEST_LOG=fuzz,qga,qmp,qtest,test
  equivalent to QTEST_LOG=1

QTEST_LOG=qmp,qtest
  enables logging of qmp operations from libqmp.c and logging of the
  qtest device.

QTEST_LOG=test,qmp
  enable test output and libqmp.c output.

QTEST_LOG=-qmp
  enable all output, except for libqmp.c

Signed-off-by: Fabiano Rosas <farosas@suse.de>
---
 tests/qtest/fuzz/fuzz.c               |  7 ++--
 tests/qtest/fuzz/generic_fuzz.c       |  2 +-
 tests/qtest/libqmp.c                  |  7 ++--
 tests/qtest/libqtest.c                | 56 ++++++++++++++++++++++++++-
 tests/qtest/libqtest.h                | 11 ++++++
 tests/qtest/migration/framework.c     |  2 +-
 tests/qtest/migration/framework.h     |  5 ++-
 tests/qtest/migration/precopy-tests.c |  2 +-
 tests/unit/meson.build                |  2 +-
 tests/unit/test-qga.c                 |  2 +-
 10 files changed, 82 insertions(+), 14 deletions(-)

diff --git a/tests/qtest/fuzz/fuzz.c b/tests/qtest/fuzz/fuzz.c
index ca248a51a6..d235598961 100644
--- a/tests/qtest/fuzz/fuzz.c
+++ b/tests/qtest/fuzz/fuzz.c
@@ -105,7 +105,7 @@ static void usage(char *path)
            "Set the environment variable FUZZ_SERIALIZE_QTEST=1 to serialize\n"
            "QTest commands into an ASCII protocol. Useful for building crash\n"
            "reproducers, but slows down execution.\n\n"
-           "Set the environment variable QTEST_LOG=1 to log all qtest commands"
+           "Set the environment variable QTEST_LOG=fuzz to log all qtest commands"
            "\n");
     exit(0);
 }
@@ -168,6 +168,7 @@ int LLVMFuzzerInitialize(int *argc, char ***argv, char ***envp)
     GString *cmd_line;
     gchar *pretty_cmd_line;
     bool serialize = false;
+    bool verbose = qtest_verbose("fuzz");
 
     /* Initialize qgraph and modules */
     qos_graph_init();
@@ -211,14 +212,14 @@ int LLVMFuzzerInitialize(int *argc, char ***argv, char ***envp)
     /* Run QEMU's system main with the fuzz-target dependent arguments */
     cmd_line = fuzz_target->get_init_cmdline(fuzz_target);
     g_string_append_printf(cmd_line, " %s -qtest /dev/null ",
-                           getenv("QTEST_LOG") ? "" : "-qtest-log none");
+                           verbose ? "" : "-qtest-log none");
 
     /* Split the runcmd into an argv and argc */
     wordexp_t result;
     wordexp(cmd_line->str, &result, 0);
     g_string_free(cmd_line, true);
 
-    if (getenv("QTEST_LOG")) {
+    if (verbose) {
         pretty_cmd_line  = g_strjoinv(" ", result.we_wordv + 1);
         printf("Starting %s with Arguments: %s\n",
                 result.we_wordv[0], pretty_cmd_line);
diff --git a/tests/qtest/fuzz/generic_fuzz.c b/tests/qtest/fuzz/generic_fuzz.c
index 440de25034..e48f868775 100644
--- a/tests/qtest/fuzz/generic_fuzz.c
+++ b/tests/qtest/fuzz/generic_fuzz.c
@@ -776,7 +776,7 @@ static void generic_pre_fuzz(QTestState *s)
     if (!getenv("QEMU_FUZZ_OBJECTS")) {
         usage();
     }
-    if (getenv("QTEST_LOG")) {
+    if (qtest_verbose("fuzz")) {
         qtest_log_enabled = 1;
     }
     if (getenv("QEMU_AVOID_DOUBLE_FETCH")) {
diff --git a/tests/qtest/libqmp.c b/tests/qtest/libqmp.c
index 16fe546885..cd12bd2678 100644
--- a/tests/qtest/libqmp.c
+++ b/tests/qtest/libqmp.c
@@ -17,6 +17,7 @@
 #include "qemu/osdep.h"
 
 #include "libqmp.h"
+#include "libqtest.h"
 
 #ifndef _WIN32
 #include <sys/socket.h>
@@ -62,7 +63,7 @@ static void qmp_response(void *opaque, QObject *obj, Error *err)
 QDict *qmp_fd_receive(int fd)
 {
     QMPResponseParser qmp;
-    bool log = getenv("QTEST_LOG") != NULL;
+    bool log = qtest_verbose("qmp");
 
     qmp.response = NULL;
     json_message_parser_init(&qmp.parser, qmp_response, &qmp, NULL);
@@ -149,7 +150,7 @@ _qmp_fd_vsend_fds(int fd, int *fds, size_t fds_num,
 
     /* No need to send anything for an empty QObject.  */
     if (qobj) {
-        int log = getenv("QTEST_LOG") != NULL;
+        bool log = qtest_verbose("qmp");
         GString *str = qobject_to_json(qobj);
 
         /*
@@ -220,7 +221,7 @@ void qmp_fd_send(int fd, const char *fmt, ...)
 
 void qmp_fd_vsend_raw(int fd, const char *fmt, va_list ap)
 {
-    bool log = getenv("QTEST_LOG") != NULL;
+    bool log = qtest_verbose("qmp");
     char *str = g_strdup_vprintf(fmt, ap);
 
     if (log) {
diff --git a/tests/qtest/libqtest.c b/tests/qtest/libqtest.c
index a580d75179..b12b8d3dce 100644
--- a/tests/qtest/libqtest.c
+++ b/tests/qtest/libqtest.c
@@ -469,7 +469,7 @@ gchar *qtest_qemu_args(const char *extra_args)
                       " -accel qtest",
 
                       socket_path,
-                      getenv("QTEST_LOG") ? DEV_STDERR : DEV_NULL,
+                      qtest_verbose("qtest") ? DEV_STDERR : DEV_NULL,
                       qmp_socket_path,
                       can_exit_with_parent() ?
                       "-run-with exit-with-parent=on " : "",
@@ -2125,3 +2125,57 @@ bool mkimg(const char *file, const char *fmt, unsigned size_mb)
 
     return ret && !err;
 }
+
+bool qtest_verbose(const char *domain)
+{
+    const char *log = getenv("QTEST_LOG");
+    char *found;
+
+    assert(domain);
+
+    if (log) {
+        /*
+         * verbose=true for all domains if:
+         *  QTEST_LOG=
+         *  QTEST_LOG=1
+         *  other one-character variations
+         */
+        if (log[0] == '\0' || log[1] == '\0') {
+            return true;
+        }
+
+        /*
+         * verbose=true for specified domains if:
+         *  QTEST_LOG=<domain>
+         *  QTEST_LOG=<domain1>,<domain2>
+         *  allows other separators, except - and +
+         *
+         * verbose=false for specified domains if:
+         *  QTEST_LOG=-<domain>
+         *  QTEST_LOG=<domain1>,-<domain2> (only false for domain2)
+         *  allows other separators, except - and +
+         */
+        found = strstr(log, domain);
+
+        if (found) {
+            /* reject options given twice */
+            assert(!strstr(found + strlen(domain), domain));
+
+            if (found > log) {
+                ptrdiff_t i = found - log - 1;
+                if (log[i] == '-') {
+                    return false;
+                }
+            }
+            return true;
+        } else {
+            /*
+             * If filtering out a specific domain, all others are
+             * enabled.
+             */
+            return !!strstr(log, "-");
+        }
+    }
+
+    return false;
+}
diff --git a/tests/qtest/libqtest.h b/tests/qtest/libqtest.h
index 9c118c89ca..950ea2baaf 100644
--- a/tests/qtest/libqtest.h
+++ b/tests/qtest/libqtest.h
@@ -1178,4 +1178,15 @@ bool have_qemu_img(void);
  */
 bool mkimg(const char *file, const char *fmt, unsigned size_mb);
 
+/**
+ * qtest_verbose:
+ * @domain: The logging domain
+ *
+ * Read the QTEST_LOG environment variable and return whether the
+ * specified domain is enabled for verbose logging. Enable specific
+ * logging domains with QTEST_LOG=<domain> or use QTEST_LOG=-<domain> to
+ * enable all domains except for the specific one.
+ */
+bool qtest_verbose(const char *domain);
+
 #endif
diff --git a/tests/qtest/migration/framework.c b/tests/qtest/migration/framework.c
index 9f71d51f1e..49c7f37e60 100644
--- a/tests/qtest/migration/framework.c
+++ b/tests/qtest/migration/framework.c
@@ -365,7 +365,7 @@ int migrate_args(char **from, char **to, const char *uri, MigrateStart *args)
         g_assert_not_reached();
     }
 
-    if (!getenv("QTEST_LOG") && args->hide_stderr) {
+    if (!qtest_verbose("test") && args->hide_stderr) {
 #ifndef _WIN32
         ignore_stderr = "2>/dev/null";
 #else
diff --git a/tests/qtest/migration/framework.h b/tests/qtest/migration/framework.h
index 79604c60f5..bb534b8110 100644
--- a/tests/qtest/migration/framework.h
+++ b/tests/qtest/migration/framework.h
@@ -118,8 +118,9 @@ typedef void (*TestMigrateEndHook)(QTestState *from,
  */
 typedef struct {
     /*
-     * QTEST_LOG=1 may override this.  When QTEST_LOG=1, we always dump errors
-     * unconditionally, because it means the user would like to be verbose.
+     * QTEST_LOG=test may override this in which case we dump errors
+     * unconditionally, because it means the user would like to be
+     * verbose.
      */
     bool hide_stderr;
     MemType mem_type;
diff --git a/tests/qtest/migration/precopy-tests.c b/tests/qtest/migration/precopy-tests.c
index a0e3ff0547..e65d9e04a5 100644
--- a/tests/qtest/migration/precopy-tests.c
+++ b/tests/qtest/migration/precopy-tests.c
@@ -130,7 +130,7 @@ static bool mlock_check(void)
 static int new_rdma_link(char *buffer, bool ipv6)
 {
     char cmd[256];
-    bool verbose = g_getenv("QTEST_LOG");
+    bool verbose = qtest_verbose("test");
 
     snprintf(cmd, sizeof(cmd), "IP_FAMILY=%s %s detect %s",
              ipv6 ? "ipv6" : "ipv4", RDMA_MIGRATION_HELPER,
diff --git a/tests/unit/meson.build b/tests/unit/meson.build
index 41e8b06c33..4b9d4d5934 100644
--- a/tests/unit/meson.build
+++ b/tests/unit/meson.build
@@ -160,7 +160,7 @@ if have_system
 endif
 
 if have_ga and host_os == 'linux'
-  tests += {'test-qga': ['../qtest/libqmp.c']}
+  tests += {'test-qga': ['../qtest/libqmp.c', '../qtest/libqtest.c']}
   test_deps += {'test-qga': qga}
 endif
 
diff --git a/tests/unit/test-qga.c b/tests/unit/test-qga.c
index 587e30c7e4..01ccf826e6 100644
--- a/tests/unit/test-qga.c
+++ b/tests/unit/test-qga.c
@@ -68,7 +68,7 @@ fixture_setup(TestFixture *fixture, gconstpointer data, gchar **envp)
     cmd = g_strdup_printf("%s%cqga%cqemu-ga -m unix-listen -t %s -p %s %s %s",
                           cwd, G_DIR_SEPARATOR, G_DIR_SEPARATOR,
                           fixture->test_dir, path,
-                          getenv("QTEST_LOG") ? "-v" : "",
+                          qtest_verbose("qga") ? "-v" : "",
                           extra_arg ?: "");
     g_shell_parse_argv(cmd, NULL, &argv, &error);
     g_assert_no_error(error);
-- 
2.51.0

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

[Fabiano Rosas]

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.
+
+	    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.
-- 
2.51.0

Re: [PATCH v1 2/3] tests/qtest: Individual verbose switches

[Peter Xu]

On Tue, Apr 28, 2026 at 09:31:29PM -0300, Fabiano Rosas wrote:
> Allow logging to be set for specific parts of QTest. Having a single
> QTEST_LOG knob creates an output stream that is almost useless due to
> spamming from some operations.
> 
> Add a backward-compatible way of selecting which parts will be made
> verbose. Reuse the existing QTEST_LOG variable. The new options are:
> 
> QTEST_LOG=
> fuzz - fuzz.c
> qga - unit/test-qga.c
> qmp - libqmp.c
> qtest - QTest device, i.e. -qtest-log option
> test - generic term for usage of all tests
> 
> E.g.:
> 
> QTEST_LOG=fuzz,qga,qmp,qtest,test
>   equivalent to QTEST_LOG=1
> 
> QTEST_LOG=qmp,qtest
>   enables logging of qmp operations from libqmp.c and logging of the
>   qtest device.
> 
> QTEST_LOG=test,qmp
>   enable test output and libqmp.c output.
> 
> QTEST_LOG=-qmp
>   enable all output, except for libqmp.c
> 
> Signed-off-by: Fabiano Rosas <farosas@suse.de>

Ohhh this is nice..

Acked-by: Peter Xu <peterx@redhat.com>

Some quick thoughts, doesn't need to do it immediately or at all: make the
parsing of QTEST_LOG var only once might be nice (e.g. switch to flag for
qtest_verbose()).  The other nitpick is would the word "test" too hard to
guess for what it does?  Maybe "misc"?

-- 
Peter Xu

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

[Pierrick Bouvier]

On 4/28/2026 5:31 PM, Fabiano Rosas 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(+)
> 

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

Re: [PATCH v1 2/3] tests/qtest: Individual verbose switches

[Fabiano Rosas]

Peter Xu <peterx@redhat.com> writes:

> On Tue, Apr 28, 2026 at 09:31:29PM -0300, Fabiano Rosas wrote:
>> Allow logging to be set for specific parts of QTest. Having a single
>> QTEST_LOG knob creates an output stream that is almost useless due to
>> spamming from some operations.
>> 
>> Add a backward-compatible way of selecting which parts will be made
>> verbose. Reuse the existing QTEST_LOG variable. The new options are:
>> 
>> QTEST_LOG=
>> fuzz - fuzz.c
>> qga - unit/test-qga.c
>> qmp - libqmp.c
>> qtest - QTest device, i.e. -qtest-log option
>> test - generic term for usage of all tests
>> 
>> E.g.:
>> 
>> QTEST_LOG=fuzz,qga,qmp,qtest,test
>>   equivalent to QTEST_LOG=1
>> 
>> QTEST_LOG=qmp,qtest
>>   enables logging of qmp operations from libqmp.c and logging of the
>>   qtest device.
>> 
>> QTEST_LOG=test,qmp
>>   enable test output and libqmp.c output.
>> 
>> QTEST_LOG=-qmp
>>   enable all output, except for libqmp.c
>> 
>> Signed-off-by: Fabiano Rosas <farosas@suse.de>
>
> Ohhh this is nice..
>
> Acked-by: Peter Xu <peterx@redhat.com>
>
> Some quick thoughts, doesn't need to do it immediately or at all: make the
> parsing of QTEST_LOG var only once might be nice (e.g. switch to flag for
> qtest_verbose()).  The other nitpick is would the word "test" too hard to
> guess for what it does?  Maybe "misc"?

I'd like to add an _env function, like we did with migration-test. So
all environment stuff is read once there and it's all kept in a single
structure that's exposed to the rest of the code. I see scary messages
in glib code about thread-unsafety of getenv, I would not be surprised
if they start to complain more about it. See my dbus-vmstate-series for
more on that.

About the "test" word, I don't mind changing, but I think "misc" is
worse. My intention long-term is actually to reduce the usage of
QTEST_LOG in tests directly. This should be only for "qtest modules" to
use internally (such as libqmp, libqos). Otherwise the notion of what
counts as verbose gets lost among all the test writers.

The usage in migration-test should be removed at some point. We had an
idea of implementing a filtering scheme like the iotests do, which would
do away with the need for redirecting QEMU's output to devnull.

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

[Peter Maydell]

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===

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

thanks
-- PMM

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

[Fabiano Rosas]

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

Re: [PATCH v1 1/3] tests/qtest/libqtest: Replace QTEST_TRACE with QTEST_QEMU_ARGS

[Peter Maydell]

On Wed, 29 Apr 2026 at 01:32, Fabiano Rosas <farosas@suse.de> wrote:
>
> The QTEST_TRACE environment variable allows for any QEMU command line
> option to be passed if used like so:
>
> export QTEST_TRACE="-trace tracepoint -more -opts -here"
>
> Formalize that usage by accepting a new QTEST_QEMU_ARGS
> variable. Since the QTEST_TRACE now becomes redundant, remove its
> usage.
>
> Signed-off-by: Fabiano Rosas <farosas@suse.de>
> ---
>  tests/qtest/libqtest.c | 11 +++++------
>  1 file changed, 5 insertions(+), 6 deletions(-)
>
> diff --git a/tests/qtest/libqtest.c b/tests/qtest/libqtest.c
> index 051faf31e1..a580d75179 100644
> --- a/tests/qtest/libqtest.c
> +++ b/tests/qtest/libqtest.c
> @@ -454,11 +454,9 @@ gchar *qtest_qemu_args(const char *extra_args)
>  {
>      g_autofree gchar *socket_path = qtest_socket_path("sock");
>      g_autofree gchar *qmp_socket_path = qtest_socket_path("qmp");
> -    const char *trace = g_getenv("QTEST_TRACE");
> -    g_autofree char *tracearg = trace ? g_strdup_printf("-trace %s ", trace) :
> -                                        g_strdup("");
> +    const char *args_from_env = g_getenv("QTEST_QEMU_ARGS");
> +
>      gchar *args = g_strdup_printf(
> -                      "%s"
>                        "-qtest unix:%s "
>                        "-qtest-log %s "
>                        "-chardev socket,path=%s,id=char0 "
> @@ -466,16 +464,17 @@ gchar *qtest_qemu_args(const char *extra_args)
>                        "-display none "
>                        "-audio none "
>                        "%s"
> +                      "%s "
>                        "%s"
>                        " -accel qtest",
>
> -                      tracearg,
>                        socket_path,
>                        getenv("QTEST_LOG") ? DEV_STDERR : DEV_NULL,
>                        qmp_socket_path,
>                        can_exit_with_parent() ?
>                        "-run-with exit-with-parent=on " : "",
> -                      extra_args ?: "");
> +                      extra_args ?: "",
> +                      args_from_env ?: "");

Maybe we should have all those "%s" consistently be "%s "
(and drop the trailing space in the "-run-with exit-with-parent=on "
string and the leading one in " -accel qtest")?

Sometimes we might get an extra space we don't technically
need in the command line, but on the other hand we would be able
to look at the format string and see at a glance that it
definitely doesn't potentially run one argument into the next
without having to cross-check all the %s with the arguments,
and the arguments would consistently always be just strings
with no requirement to bring along a leading or trailing space.

But either way
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH v1 1/3] tests/qtest/libqtest: Replace QTEST_TRACE with QTEST_QEMU_ARGS

[Fabiano Rosas]

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

> On Wed, 29 Apr 2026 at 01:32, Fabiano Rosas <farosas@suse.de> wrote:
>>
>> The QTEST_TRACE environment variable allows for any QEMU command line
>> option to be passed if used like so:
>>
>> export QTEST_TRACE="-trace tracepoint -more -opts -here"
>>
>> Formalize that usage by accepting a new QTEST_QEMU_ARGS
>> variable. Since the QTEST_TRACE now becomes redundant, remove its
>> usage.
>>
>> Signed-off-by: Fabiano Rosas <farosas@suse.de>
>> ---
>>  tests/qtest/libqtest.c | 11 +++++------
>>  1 file changed, 5 insertions(+), 6 deletions(-)
>>
>> diff --git a/tests/qtest/libqtest.c b/tests/qtest/libqtest.c
>> index 051faf31e1..a580d75179 100644
>> --- a/tests/qtest/libqtest.c
>> +++ b/tests/qtest/libqtest.c
>> @@ -454,11 +454,9 @@ gchar *qtest_qemu_args(const char *extra_args)
>>  {
>>      g_autofree gchar *socket_path = qtest_socket_path("sock");
>>      g_autofree gchar *qmp_socket_path = qtest_socket_path("qmp");
>> -    const char *trace = g_getenv("QTEST_TRACE");
>> -    g_autofree char *tracearg = trace ? g_strdup_printf("-trace %s ", trace) :
>> -                                        g_strdup("");
>> +    const char *args_from_env = g_getenv("QTEST_QEMU_ARGS");
>> +
>>      gchar *args = g_strdup_printf(
>> -                      "%s"
>>                        "-qtest unix:%s "
>>                        "-qtest-log %s "
>>                        "-chardev socket,path=%s,id=char0 "
>> @@ -466,16 +464,17 @@ gchar *qtest_qemu_args(const char *extra_args)
>>                        "-display none "
>>                        "-audio none "
>>                        "%s"
>> +                      "%s "
>>                        "%s"
>>                        " -accel qtest",
>>
>> -                      tracearg,
>>                        socket_path,
>>                        getenv("QTEST_LOG") ? DEV_STDERR : DEV_NULL,
>>                        qmp_socket_path,
>>                        can_exit_with_parent() ?
>>                        "-run-with exit-with-parent=on " : "",
>> -                      extra_args ?: "");
>> +                      extra_args ?: "",
>> +                      args_from_env ?: "");
>
> Maybe we should have all those "%s" consistently be "%s "
> (and drop the trailing space in the "-run-with exit-with-parent=on "
> string and the leading one in " -accel qtest")?
>

Yep, I'll fix it.

At some point I'll figure out how to integrate this qgraph thing with
the rest of qtest so we can build command lines in a cleaner way.

> Sometimes we might get an extra space we don't technically
> need in the command line, but on the other hand we would be able
> to look at the format string and see at a glance that it
> definitely doesn't potentially run one argument into the next
> without having to cross-check all the %s with the arguments,
> and the arguments would consistently always be just strings
> with no requirement to bring along a leading or trailing space.
>
> But either way
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
>
> thanks
> -- PMM