pytest-timeout

2.4.0 · active · verified Sat Mar 28

pytest-timeout is an actively maintained pytest plugin designed to automatically abort excessively long-running or hanging tests. It helps in maintaining efficient test suites by enforcing timeout limits at various levels (global, session, per-test) and provides different methods to terminate tests. The current version is 2.4.0 and it is part of the pytest-dev organization, implying regular updates and maintenance.

Warnings

breaking Minimum `pytest` version has increased. For `pytest-timeout` versions 2.2.0 and later, `pytest>=7.0.0` is required. Ensure your `pytest` installation is up-to-date to avoid compatibility issues. Python 3.7+ is required for version 2.4.0.
Fix: Upgrade pytest to `pytest>=7.0.0` using `pip install --upgrade pytest` and ensure Python is 3.7 or newer.
gotcha The plugin offers two timeout methods: 'signal' (default on supported systems) and 'thread'. The 'signal' method (using SIGALRM) is generally more efficient but can interfere with code under test that also uses SIGALRM. The 'thread' method is more portable and reliable but incurs more overhead and can prevent other `pytest` features (like JUnit XML or fixture teardown) from completing normally because it terminates the entire process.
Fix: If experiencing issues, explicitly set the method using `--timeout-method=thread` CLI option or `timeout_method = thread` in `pytest.ini`. Consider the implications of each method on your test suite's behavior.
gotcha Session timeouts (`--session-timeout`) are 'cooperative'. They check the session time at the end of each test function and stop *further* tests from running if the timeout is exceeded. They will *not* interrupt a test currently in progress. To ensure a test-in-progress is interrupted, a per-function timeout must also be set.
Fix: For hard limits on individual test execution, always combine `--session-timeout` with global or per-test `timeout` settings. E.g., `pytest --session-timeout=3600 --timeout=300`.
gotcha By default, timeouts apply to the entire test lifecycle, including fixture setup and teardown. If your fixtures are long-running, they can cause tests to time out prematurely.
Fix: If you only want to time the test function body, set `timeout_func_only = True` in your `pytest.ini` file, or increase the timeout duration to account for fixture overhead.
gotcha By default, `pytest-timeout` attempts to detect when a debugger (like pdb or PyCharm's debugger) is active and disables timeouts to prevent interruption during debugging sessions. This behavior can be explicitly disabled.
Fix: If you need timeouts to function even when a debugger is attached (e.g., for automated debugging workflows), use the `--timeout-disable-debugger-detection` CLI option or `disable_debugger_detection = True` in `pytest.ini`.

Install

pip install pytest-timeout Install stable version

Imports

pytest.mark.timeout
```
import pytest
@pytest.mark.timeout(300)
def test_example():
    pass
```
pytest-timeout is a plugin and typically configured via pytest.ini, command-line options, or test markers, rather than direct Python imports of its internal classes.

Quickstart

This quickstart demonstrates how to apply timeouts using `pytest-timeout`. It shows setting a global timeout via `pytest.ini` (or `PYTEST_TIMEOUT` environment variable), and overriding it for specific tests using the `@pytest.mark.timeout` decorator. The example includes tests that should pass and one designed to explicitly time out.

import pytest
import time
import os

# Example pytest.ini content (can be placed in a file named pytest.ini)
# [pytest]
# timeout = 5

# Or set via environment variable (e.g., in CI/CD)
# export PYTEST_TIMEOUT=10

# A test that should pass within the global timeout (if set to > 1)
def test_fast_operation():
    time.sleep(1) # Simulates a quick operation
    assert True

# A test with a specific timeout marker, overriding global settings
@pytest.mark.timeout(os.environ.get('PYTEST_LONG_TIMEOUT', 20))
def test_long_running_operation():
    time.sleep(15) # Simulates a potentially long operation
    assert True

# A test designed to time out if default or global timeout is low
@pytest.mark.timeout(2)
def test_should_timeout():
    time.sleep(3) # This will exceed the 2-second mark
    assert False, "Should not reach here if timeout works"

# To run these tests:
# 1. Save as a Python file (e.g., test_timeouts.py)
# 2. Run from your terminal: pytest test_timeouts.py
#    (or pytest test_timeouts.py --timeout=5 to set a global CLI timeout)

view raw JSON →