Skip to contentSkip to conversation

tests/qtest: Tweak env variables

PATCH In review Fabiano Rosas 4 participants 11 messages Apr 29 – Apr 30 Arm/Amlogic Meson SoC support

lore
Share & tools
lore
#0 lore raw

cover tests/qtest: Tweak env variables

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(-)
Signature · 1 line
2.51.0
#1 lore raw

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

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.

---
 tests/qtest/libqtest.c | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)
tests/qtest/libqtest.c +5 -6
index 051faf31e1..a580d75179 100644
@@ -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;
 }
Signature · 1 line
2.51.0
Reviewed-by on v1 1/3
#2 lore raw

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

Quoted 40 lines · 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.

---
 tests/qtest/libqtest.c | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)
tests/qtest/libqtest.c +3 -4
index 051faf31e1..a580d75179 100644
@@ -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",

tests/qtest/libqtest.c gchar *qtest_qemu_args(const char *extra_args) · line 477

Quoted 10 lines
tests/qtest/libqtest.c +2 -2
 
-                      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

thanks
-- PMM

#3 lore raw

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

Quoted 42 lines · Peter Maydell
Quoted 41 lines · 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.

---
 tests/qtest/libqtest.c | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)
tests/qtest/libqtest.c +3 -4
index 051faf31e1..a580d75179 100644
@@ -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",
 
Quoted 14 lines

tests/qtest/libqtest.c gchar *qtest_qemu_args(const char *extra_args) · line 477

Quoted 9 lines
tests/qtest/libqtest.c +2 -2
-                      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.

Quoted 13 lines

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

thanks
-- PMM

#4 lore raw

PATCH 2/3 tests/qtest: Individual verbose switches

In reply to 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

---
 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(-)
tests/qtest/fuzz/fuzz.c +4 -3
index ca248a51a6..d235598961 100644
@@ -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);
tests/qtest/fuzz/generic_fuzz.c +1 -1
index 440de25034..e48f868775 100644
@@ -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")) {
tests/qtest/libqmp.c +4 -3
index 16fe546885..cd12bd2678 100644
@@ -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) {
tests/qtest/libqtest.c +55 -1

65 lines not on this page · raw message

tests/qtest/libqtest.h +11 -0
index 9c118c89ca..950ea2baaf 100644
@@ -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
tests/qtest/migration/framework.c +1 -1
index 9f71d51f1e..49c7f37e60 100644
@@ -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
tests/qtest/migration/framework.h +3 -2
index 79604c60f5..bb534b8110 100644
@@ -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;
tests/qtest/migration/precopy-tests.c +1 -1
index a0e3ff0547..e65d9e04a5 100644
@@ -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,
tests/unit/meson.build +1 -1
index 41e8b06c33..4b9d4d5934 100644
@@ -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
 
tests/unit/test-qga.c +1 -1
index 587e30c7e4..01ccf826e6 100644
@@ -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);
Signature · 1 line
2.51.0
Acked-by on v1 2/3
#5 lore raw

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

Quoted 23 lines · 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.

Quoted 7 lines

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

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

Ohhh this is nice..

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"?

Signature · 1 line
Peter Xu
#6 lore raw

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

Quoted 32 lines · Peter Xu
Quoted 23 lines · 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.

Quoted 7 lines

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

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

Quoted 8 lines

Ohhh this is nice..

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.

#7 lore raw

PATCH 3/3 docs/devel/qtest: Mention environment variables usage

In reply to 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.

---
 docs/devel/testing/qtest.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
docs/devel/testing/qtest.rst +33 -0
index 73ef7702b7..0aac0f0aaf 100644
@@ -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.
Signature · 1 line
2.51.0
Reviewed-by on v1 3/3
#8 lore raw

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

Quoted 10 lines · 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.

---
 docs/devel/testing/qtest.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
Reviewed-by on v1 3/3
#9 lore raw

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

In reply to Fabiano Rosas
Quoted 36 lines · 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.

---
 docs/devel/testing/qtest.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
docs/devel/testing/qtest.rst +17 -0
index 73ef7702b7..0aac0f0aaf 100644
@@ -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

docs/devel/testing/qtest.rst libqtest API reference · line 120

Quoted 10 lines
docs/devel/testing/qtest.rst +10 -0
+
+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"

docs/devel/testing/qtest.rst libqtest API reference · line 126

Quoted 6 lines
docs/devel/testing/qtest.rst +6 -0
+
+           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,

thanks
-- PMM

#10 lore raw

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

Quoted 107 lines · Peter Maydell
Quoted 36 lines · 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.

---
 docs/devel/testing/qtest.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
docs/devel/testing/qtest.rst +17 -0
index 73ef7702b7..0aac0f0aaf 100644
@@ -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

docs/devel/testing/qtest.rst libqtest API reference · line 120

Quoted 10 lines
docs/devel/testing/qtest.rst +10 -0
+
+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"

docs/devel/testing/qtest.rst libqtest API reference · line 126

Quoted 6 lines
docs/devel/testing/qtest.rst +6 -0
+
+           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===

docs/devel/testing/qtest.rst +44 -0
+
+
+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.
Quoted 2 lines

===endit===

Excellent, thank you for this.

Quoted 7 lines

Either way,

thanks
-- PMM