[PATCH] docs/devel/testing/functional: Add a section about logging

[PATCH] docs/devel/testing/functional: Add a section about logging

[Thomas Huth]

From: Thomas Huth <thuth@redhat.com>

We should tell the users where to find the log file.
While we're at it, also rename the "Overview" heading to a
more accurate "Introduction to writing tests" instead.

Reported-by: Aditya Gupta <adityag@linux.ibm.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
---
 docs/devel/testing/functional.rst | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/docs/devel/testing/functional.rst b/docs/devel/testing/functional.rst
index a9fa45eac1f..9bc973392aa 100644
--- a/docs/devel/testing/functional.rst
+++ b/docs/devel/testing/functional.rst
@@ -72,8 +72,26 @@ files around on disk by setting ```QEMU_TEST_KEEP_SCRATCH=1``` as an env
 variable.  Any preserved files will be deleted the next time the test is run
 without this variable set.
 
-Overview
---------
+Logging
+-------
+
+The framework collects log files for each test in the build directory
+in the following subfolder::
+
+ <builddir>/tests/functional/<arch>/<fileid>.<classid>.<testname>/
+
+There are usually three log files:
+
+* ``base.log`` contains the generic logging information that is written
+  by the calls to the logging functions in the test code (e.g. by calling
+  the ``self.log.info()`` or ``self.log.debug()`` functions).
+* ``console.log`` contains the output of the serial console of the guest.
+* ``default.log`` contains the output of QEMU. This file could be named
+  differently if the test chooses to use a different identifier for
+  the guest VM (e.g. when the test spins up multiple VMs).
+
+Introduction to writing tests
+-----------------------------
 
 The ``tests/functional/qemu_test`` directory provides the ``qemu_test``
 Python module, containing the ``qemu_test.QemuSystemTest`` class.
-- 
2.48.1

Re: [PATCH] docs/devel/testing/functional: Add a section about logging

[Daniel P. Berrangé]

On Tue, Mar 18, 2025 at 10:20:21AM +0100, Thomas Huth wrote:
> From: Thomas Huth <thuth@redhat.com>
> 
> We should tell the users where to find the log file.
> While we're at it, also rename the "Overview" heading to a
> more accurate "Introduction to writing tests" instead.
> 
> Reported-by: Aditya Gupta <adityag@linux.ibm.com>
> Signed-off-by: Thomas Huth <thuth@redhat.com>
> ---
>  docs/devel/testing/functional.rst | 22 ++++++++++++++++++++--
>  1 file changed, 20 insertions(+), 2 deletions(-)

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


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|