output.rst

Overview

The `output.rst` file is a comprehensive documentation guide focused on managing and customizing the output produced by pytest, the popular Python testing framework. It explains how users can control pytest’s output verbosity, traceback formatting, truncation limits, and result reporting formats such as JUnit XML. The file also covers advanced features like recording custom properties and attributes in test reports, sending test reports to online pastebin services, and fine-grained control over output verbosity.

This document is primarily aimed at pytest users and plugin developers who want to tailor the test output to their needs for better debugging, reporting, and integration with Continuous Integration (CI) systems.

Detailed Explanations

Traceback Printing Modifications

Pytest provides several command-line options to customize how Python tracebacks are displayed when tests fail or errors occur.

**Usage Example:**

pytest --showlocals --tb=long --capture=no

Verbosity Control

Pytest output verbosity can be controlled using the `-q` (quiet) and `-v` (verbose) flags. Higher verbosity levels provide more detailed information about tests being executed and failed assertions.

**Examples:**

**Effect on Output:** Increasing verbosity changes how much detail is shown about each test, including full diffs for assertion failures, test function names, and untruncated output.

Fine-Grained Verbosity

Pytest allows independent control over specific verbosity aspects via configuration options:

These can be set in pytest's config files (`pytest.ini`, `tox.ini`, or `setup.cfg`) to fine-tune output behavior beyond the global `-v` flag.

Detailed Summary Reports (-r flag)

The `-r` option produces a short summary of test outcomes at the end of the test run, showing failures, skips, errors, and other statuses.

**Example:**

pytest -rfs

Shows only failed and skipped tests in the summary.

Truncation Limits

Introduced in pytest 8.4, users can configure how much output is truncated in assertion failures.

Setting both to 0 disables truncation entirely.

**Configuration (`pytest.ini`):**

[pytest]
truncation_limit_lines = 10
truncation_limit_chars = 90

JUnit XML Report Generation

Pytest can produce test result files in JUnit XML format for CI systems like Jenkins.

Recording Additional Information in Test Reports

record_property Fixture

Allows adding custom `` elements inside the `` XML element.

**Example:**

def test_function(record_property):
    record_property("example_key", 1)
    assert True

Generates XML:

<testcase ...>
  <properties>
    <property name="example_key" value="1" />
  </properties>
</testcase>

record_xml_attribute Fixture

Adds or overrides attributes on the `` element directly.

**Example:**

def test_function(record_xml_attribute):
    record_xml_attribute("assertions", "REQ-1234")
    record_xml_attribute("classname", "custom_classname")
    assert True

Generates XML:

<testcase classname="custom_classname" assertions="REQ-1234" ...>
  ...
</testcase>

*Note:* This is experimental and may break schema validations in some CI tools.

record_testsuite_property Fixture

Session-scoped fixture to add properties at the `` level, affecting all tests.

**Example:**

@pytest.fixture(scope="session", autouse=True)
def log_global_env_facts(record_testsuite_property):
    record_testsuite_property("ARCH", "PPC")
    record_testsuite_property("STORAGE_TYPE", "CEPH")

Generates XML:

<testsuite ...>
  <properties>
    <property name="ARCH" value="PPC"/>
    <property name="STORAGE_TYPE" value="CEPH"/>
  </properties>
  ...
</testsuite>

Sending Test Reports to Online Pastebin Services

Pytest can post failure logs or full test session logs to pastebin services (currently https://bpaste.net/).

If the upload fails, pytest will emit a warning but continue.

Implementation Details & Algorithms

This file is primarily documentation and examples rather than executable code. It does not contain direct implementations of pytest features but describes how pytest’s internal mechanisms behave and how users can configure them via CLI flags or config files.

Notable aspects covered:

Interaction With Other System Components

Usage Examples Summary

Visual Diagram

The file is a **utility-like documentation file** describing multiple independent functions and features related to pytest output management. Thus, a flowchart representing main topics and their relationships is most appropriate.

flowchart TD
    A[Managing pytest Output] --> B(Traceback Printing)
    A --> C(Verbosity Control)
    A --> D(Detailed Summary Reports)
    A --> E(Truncation Limits)
    A --> F(JUnit XML Reports)
    A --> G(Recording Test Properties)
    A --> H(Pastebin Integration)

    B --> B1[--showlocals / --no-showlocals]
    B --> B2[--capture modes]
    B --> B3[--tb traceback styles]
    B --> B4[--full-trace]

    C --> C1[-q / --quiet]
    C --> C2[-v / -vv / -vvv]
    C --> C3[Fine-grained verbosity config]

    D --> D1[-r flag summary chars]
    D --> D2[Skip folding]

    E --> E1[truncation_limit_lines]
    E --> E2[truncation_limit_chars]

    F --> F1[--junit-xml option]
    F --> F2[junit_suite_name]
    F --> F3[junit_duration_report]

    G --> G1[record_property fixture]
    G --> G2[record_xml_attribute fixture]
    G --> G3[record_testsuite_property fixture]

    H --> H1[--pastebin=failed]
    H --> H2[--pastebin=all]

Summary

The `output.rst` file serves as an essential guide to customizing pytest output for diverse use cases, including debugging, CI reporting, and enhanced test result visibility. It covers configuration options, command-line flags, practical examples, and advanced features for extending test reports with additional metadata. Users can leverage this information to tailor their test runs and integrate pytest seamlessly into complex development workflows.

**End of Documentation**