exit-codes.rst

Overview

This documentation file describes the exit codes used by the `pytest` testing framework to signal the outcome of test runs. Exit codes are numeric values returned by the `pytest` command-line tool after execution, indicating various results such as success, failure, interruption, or errors encountered during testing.

The primary purpose of this file is to document the meaning of each exit code and guide users on how to interpret them. Additionally, it references the [pytest.ExitCode](/projects/286/67332) enumeration that encapsulates these exit codes as part of the public API, allowing developers to programmatically access and handle these codes.

This file does **not** contain executable code but serves as an important reference for understanding test execution results and integrating custom exit code handling via plugins.

Exit Codes Defined

`pytest` defines six distinct exit codes representing the overall result of a test session:

These exit codes help users and CI/CD pipelines determine the state of test runs and take appropriate actions, such as reporting failures or rerunning tests.

pytest.ExitCode Enum

The exit codes are encapsulated in the `ExitCode` enumeration class within the `pytest` package. This enum provides a programmatic way to refer to exit codes by name instead of numeric literals, improving code readability and maintainability.

Importing ExitCode

from pytest import ExitCode

Usage Example

import subprocess
from pytest import ExitCode

# Run pytest programmatically
result = subprocess.run(["pytest", "tests/"], capture_output=True)
exit_code = result.returncode

# Check exit code using the ExitCode enum
if exit_code == ExitCode.OK:
    print("All tests passed successfully.")
elif exit_code == ExitCode.TESTS_FAILED:
    print("Some tests failed.")
else:
    print(f"Pytest exited with code {exit_code}.")

Important Notes

• The exit codes form part of the public API of pytest, so they can be reliably imported and used in user scripts or CI configurations.

• Users interested in customizing exit codes for specific scenarios (e.g., when no tests are collected) can consider using the third-party plugin pytest-custom_exit_code.

System Interaction

This documentation file ties directly to the `pytest` test execution lifecycle:

• When pytest is invoked via command line or programmatically, it runs test discovery and execution.

• Based on the outcomes, it returns one of the documented exit codes.

• CI systems, shell scripts, or other automation tools can consume these exit codes to determine next steps (e.g., fail a build, rerun tests, alert developers).

• Plugins can hook into the exit code mechanism to modify or extend behavior.

Mermaid Diagram

Below is a flowchart representing the workflow of determining and handling exit codes in `pytest`:

flowchart TD
    A[Start pytest test run] --> B{Tests found?}
    B -- Yes --> C{All tests passed?}
    B -- No --> E[Exit with code 5 (No tests collected)]
    C -- Yes --> D[Exit with code 0 (Success)]
    C -- No --> F[Exit with code 1 (Tests failed)]
    A --> G{Interrupted by User?}
    G -- Yes --> H[Exit with code 2 (Interrupted)]
    G -- No --> I{Internal error?}
    I -- Yes --> J[Exit with code 3 (Internal error)]
    I -- No --> K{Command line error?}
    K -- Yes --> L[Exit with code 4 (Usage error)]
    K -- No --> M[Exit with appropriate code from above]

Summary

• This file documents the six standard exit codes returned by pytest after test runs.

• Exit codes are defined in the pytest.ExitCode enum for easy reference.

• Understanding exit codes enables proper handling of test outcomes in automation and development workflows.

• Customization of exit codes is possible via external plugins.

• The file acts as a key reference in the pytest ecosystem for interpreting test run results.

End of [exit-codes.rst](/projects/286/67391) documentation.