docs/devel/testing/functional: Add a section about logging

Commit Message

Thomas Huth March 18, 2025, 9:20 a.m. UTC

From: Thomas Huth <[e-mail]>

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 <[e-mail]>
Signed-off-by: Thomas Huth <[e-mail]>
---
 docs/devel/testing/functional.rst | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

Comments

Daniel P. Berrangé March 18, 2025, 9:23 a.m. UTC | #1

On Tue, Mar 18, 2025 at 10:20:21AM +0100, Thomas Huth wrote:
> From: Thomas Huth <[e-mail]>
> 
> 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 <[e-mail]>
> Signed-off-by: Thomas Huth <[e-mail]>
> ---
>  docs/devel/testing/functional.rst | 22 ++++++++++++++++++++--
>  1 file changed, 20 insertions(+), 2 deletions(-)

Reviewed-by: Daniel P. Berrangé <[e-mail]>


With regards,
Daniel

Patch

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.