Terminal Reporting

Purpose

Terminal Reporting addresses the need for clear, concise, and informative feedback to users during and after test execution in the terminal. While the broader **Test Execution and Reporting** main topic covers running tests and generating reports, Terminal Reporting focuses specifically on how these results are presented live in the console and summarized at the end. It ensures that users can track progress, understand outcomes immediately, and quickly identify failures, warnings, and other test statuses without parsing complex report files.

This subtopic solves the problem of providing real-time visual feedback and a readable summary that balances verbosity and clarity, adapting to different user preferences and terminal capabilities.

Functionality

Terminal Reporting orchestrates the display of test progress and results via the terminal. Its key workflows and features include:

• Configurable verbosity and output style: Users control the level of detail (quiet, normal, verbose) and output style (classic, progress bar, count) through CLI options and configuration (-v, -q, --no-header, --no-summary, console_output_style ini).

• Real-time test progress display: As tests run, a concise representation of results is output, typically using single characters (e.g., . for passed, F for failed). Progress indicators show counts or percentages, updated dynamically to avoid clutter.

• Test location and status lines: When verbosity is higher, detailed lines indicate the test node ID, file location, test outcome, and skip/fail reasons, aiding diagnosis.

• Collection reporting: During test discovery, collection progress and summary statistics are shown, including counts of collected, deselected, skipped, and errored tests.

• Summaries of results: At session end, Terminal Reporting produces summaries grouped by outcome categories (failures, errors, skipped, warnings, xfail, xpass, passes), optionally folding skipped tests for brevity.

• Warnings and error messages: Dedicated sections list warnings collected during the session and errors encountered in collection or setup phases.

• Support for output capturing preferences: Based on configuration, captured stdout/stderr/log output from tests is selectively displayed alongside failure reports.

• Color and formatting: Uses terminal markup to apply colors and styles to test status symbols, summary lines, and headers for improved readability.

• Interrupt handling: Gracefully reports keyboard interrupts with optional full traceback display.

• Integration with pytest hooks: Implements and wraps numerous hooks (pytest_runtest_logreport, pytest_collection_finish, pytest_sessionfinish, pytest_terminal_summary, etc.) to insert terminal output at correct lifecycle points.

Example snippet showing how test status letters are printed during test execution:

def pytest_runtest_logreport(self, report: TestReport) -> None:
    # ...
    category, letter, word = self.config.hook.pytest_report_teststatus(report=rep, config=self.config)
    self._add_stats(category, [rep])
    if self.config.get_verbosity(Config.VERBOSITY_TEST_CASES) <= 0:
        self._tw.write(letter, **markup)
        # Progress info updated here if applicable

Integration

Terminal Reporting is tightly integrated with the overall **Test Execution and Reporting** parent topic as the user-facing presentation layer of test results. It builds upon the raw test outcome data generated by test runners and reports (`TestReport`, `CollectReport`) and transforms them into digestible terminal output.

It complements other subtopics as follows:

• Test Lifecycle Management: Receives notifications about test start, completion, and status through hooks to update terminal output dynamically.

• JUnit XML Reporting: While JUnit XML produces machine-readable reports for CI systems, Terminal Reporting focuses on human-readable console output.

• Plugin System and Hooks: Leverages pytest hooks extensively to customize terminal output behavior and respond to test events, and it allows plugins to extend or alter reporting.

• Output and Log Capture: Coordinates with output capture to optionally show captured logs in failure summaries.

• Warnings and Unraisable Exception Handling: Incorporates warnings collected during test runs into terminal summaries.

• Debugger Integration: Works alongside debugging features to display relevant information when tests fail or are interrupted.

By managing all terminal output related to test progress and results, Terminal Reporting forms an essential bridge between the pytest core execution engine and the user’s immediate test feedback experience.

Diagram

flowchart TD
    Start[Test Session Start] --> Collect[Test Discovery & Collection]
    Collect --> DisplayCollect[Display Collection Progress]
    DisplayCollect --> RunTests[Test Execution Loop]
    RunTests --> LogReport[Receive Test Reports]
    LogReport --> UpdateProgress[Update Terminal Progress]
    LogReport --> ShowDetails[Display Detailed Info (if verbose)]
    RunTests --> Capture[Coordinate with Output Capture]
    RunTests --> HandleWarnings[Collect Warnings]
    RunTests --> HandleInterrupts[Handle Keyboard Interrupts]
    RunTests --> StoreStats[Accumulate Stats by Category]
    RunTests --> LoopContinue{More Tests?}
    LoopContinue -->|Yes| RunTests
    LoopContinue -->|No| SessionFinish[Test Session Finish]
    SessionFinish --> Summary[Display Final Summaries]
    Summary --> End[End of Test Run]

This flowchart visualizes the core process of terminal reporting during a pytest session: starting with test collection, running tests while updating progress and outputting status, handling warnings and interrupts, and finally producing a comprehensive summary.