Files

Andrew Vaillancourt b849e6ded6 Doc: Add structured step logging usage

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>

2025-06-18 16:54:17 -04:00

3.7 KiB

Raw Blame History

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.

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:

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:

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.

3.7 KiB Raw Blame History Unescape Escape