b849e6ded6
This update enhances the Sphinx documentation under framework/logging to include examples and usage guidance for structured test step logging. It introduces a new section that explains how to use log_setup_step(), log_test_case_step(), and log_teardown_step(), with sample code and realistic log output. The documentation also updates the log source code table to include TSU and TTD, alongside AUT, TST, and others. This helps test authors adopt consistent step logging across setup, execution, and teardown phases. Test Plan: - Verified live doc rendering using: pipenv run sphinx-autobuild doc/source doc/build/html - Confirmed new section renders correctly with preserved spacing. - Ensured table updates appear in the generated HTML output. Change-Id: I797cf10b0e1c619ebe696089b0570a4007a31319 Signed-off-by: Andrew Vaillancourt <andrew.vaillancourt@windriver.com>
131 lines
3.7 KiB
ReStructuredText
131 lines
3.7 KiB
ReStructuredText
========================================
|
||
**framework/logging/** Documentation
|
||
========================================
|
||
|
||
The **framework/logging/** directory provides centralized logging for the StarlingX Test Automation Framework. It standardizes log format, sources, and behavior across keywords, test cases, and framework utilities.
|
||
|
||
--------
|
||
Contents
|
||
--------
|
||
|
||
.. contents::
|
||
:local:
|
||
:depth: 2
|
||
|
||
Overview
|
||
========
|
||
|
||
Logging is handled via a singleton instance of `AutomationLogger`, which wraps Python's `logging` module but adds:
|
||
|
||
- Structured test step logging
|
||
- Automatic source tagging (e.g., AUT, TST, SSH)
|
||
- Support for per-test logs and exception filtering
|
||
- CLI + file output with unified formatting
|
||
|
||
Accessing the Logger
|
||
=====================
|
||
|
||
Always use:
|
||
|
||
.. code-block:: python
|
||
|
||
from framework.logging.automation_logger import get_logger
|
||
get_logger().log_info("My log message")
|
||
|
||
This ensures:
|
||
|
||
- You don’t manually instantiate or manage loggers.
|
||
- All logs use the centralized format and handler structure.
|
||
- Logging behavior (formatting, filtering, file output) is consistent.
|
||
|
||
Logging Conventions
|
||
====================
|
||
|
||
Log messages are tagged with a **source** code:
|
||
|
||
- ``AUT`` – General automation logs
|
||
- ``TST`` – Structured test execution steps
|
||
- ``TSU`` – Structured setup steps
|
||
- ``TTD`` – Structured teardown steps
|
||
- ``SSH`` – SSH commands and output
|
||
- ``KEY`` – Keyword-level trace logs
|
||
- ``EXC`` – Exception logs (stack traces)
|
||
- ``LIB`` – 3rd-party logs
|
||
|
||
Framework Methods
|
||
------------------
|
||
|
||
The following methods are available:
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - Method
|
||
- Description
|
||
- Source
|
||
* - ``log_info()``
|
||
- Log a general message
|
||
- AUT
|
||
* - ``log_debug()``
|
||
- Log a debug message
|
||
- AUT
|
||
* - ``log_warning()``
|
||
- Log a warning
|
||
- AUT
|
||
* - ``log_error()``
|
||
- Log a non-exception error
|
||
- AUT
|
||
* - ``log_exception()``
|
||
- Log an exception (no stack trace duplication)
|
||
- EXC
|
||
* - ``log_keyword()``
|
||
- Auto-logged when keyword wrappers are used
|
||
- KEY
|
||
* - ``log_ssh()``
|
||
- Logs SSH commands sent and received
|
||
- SSH
|
||
* - ``log_test_case_step()``
|
||
- Structured, numbered test execution step
|
||
- TST
|
||
* - ``log_setup_step()``
|
||
- Structured, numbered setup step
|
||
- TSU
|
||
* - ``log_teardown_step()``
|
||
- Structured, numbered teardown step
|
||
- TTD
|
||
|
||
|
||
Structured Step Logging
|
||
=======================
|
||
|
||
The test framework supports structured logging for each stage of test execution:
|
||
Setup, Execution, and Teardown.
|
||
|
||
Each stage has a corresponding logger method:
|
||
|
||
- get_logger().log_setup_step("...")
|
||
- get_logger().log_test_case_step("...")
|
||
- get_logger().log_teardown_step("...")
|
||
|
||
These methods log clearly formatted, numbered steps using a consistent visual layout.
|
||
Each stage uses its own prefix (TSU, TST, TTD) to aid visual scanning and support
|
||
machine parsing or grep-based analysis.
|
||
|
||
Example usage:
|
||
::
|
||
|
||
get_logger().log_setup_step("Connecting to system")
|
||
get_logger().log_test_case_step("Create PVC")
|
||
get_logger().log_teardown_step("Disconnecting from system")
|
||
|
||
Example log output:
|
||
::
|
||
|
||
[2025-06-18 16:44:01] TSU INFO ... :: -------------------- [ Setup Step 1: Connecting to system ] -------------------------------
|
||
[2025-06-18 16:44:01] TST INFO ... :: -------------------- [ Test Step 1: Create PVC ] ------------------------------------------
|
||
[2025-06-18 16:44:01] TTD INFO ... :: -------------------- [ Teardown Step 1: Disconnecting from system ] -----------------------
|
||
|
||
Each step banner auto-increments a counter and maintains consistent alignment
|
||
regardless of description length. Counters reset automatically at the beginning
|
||
of each test case.
|