Pytest Timeouts Plugin

Warnings

• breaking This plugin is explicitly 'Linux-only'. It relies on the SIGALRM signal, which is not reliably available or behaves differently on other operating systems like macOS or Windows. It will not function as expected on non-Linux platforms.
  Fix: Ensure usage only on Linux environments or consider the more general `pytest-timeout` plugin if cross-platform compatibility is required.
• gotcha The `pytest-timeouts` plugin has a fixed order of precedence for applying timeout settings: command-line options (`opts`) > markers (`markers`) > `pytest.ini` (`ini`). This order can be customized or disabled using the `--timeouts-order` command-line option, e.g., `--timeouts-order oi` to prioritize `opts` then `ini` and disable markers.
  Fix: Be explicit about your desired timeout order using `--timeouts-order` if multiple configuration sources are used. Understand that command-line options generally override markers, which override `pytest.ini`.
• gotcha When a test is terminated due to a timeout, especially with hard termination methods (like `os._exit()` which is often used), it may result in an abrupt exit without proper fixture teardown, incomplete JUnit XML output, or other post-test processing. While debugging information is usually preserved, be aware of these side-effects.
  Fix: Design tests to be robust against abrupt termination. If graceful teardown is critical, explore `pytest-forked` for process isolation or use the `thread` timeout method (if available and suitable for your tests, though `pytest-timeouts` primarily uses `SIGALRM`). Review the plugin's documentation on termination methods.
• deprecated Version 1.2.1 fixed a `PyTest get_marker warning` that specifically affected `pytest 3.10.X`. This indicates potential compatibility issues or warnings when using `pytest-timeouts` with specific `pytest` versions, particularly around how markers are accessed. Newer `pytest` versions generally prefer `request.node.get_closest_marker`.
  Fix: Upgrade to `pytest-timeouts` version 1.2.1 or newer to resolve `get_marker` warnings with `pytest 3.10.X`. Ensure your `pytest` version is compatible with the `pytest-timeouts` version you are using.
• gotcha This plugin (`pytest-timeouts`) is distinct from the more widely known `pytest-timeout` plugin. `pytest-timeouts` is specifically designed for Linux and focuses on granular phase timeouts (setup, execution, teardown) using `SIGALRM`, whereas `pytest-timeout` offers broader OS support and different timeout mechanisms.
  Fix: Carefully choose the correct plugin based on your operating system and specific timeout requirements. If you need phase-specific timeouts on Linux, `pytest-timeouts` is the one. For general timeouts across platforms, `pytest-timeout` might be more appropriate.

Install

• pip install pytest-timeouts Install stable version

Imports

• pytest.mark.<timeout_type>

  import pytest
  
  @pytest.mark.execution_timeout(1.5)
  def test_something():
      ...

  Configuration is primarily done via pytest markers, command-line options, or pytest.ini, rather than direct imports of `pytest-timeouts` classes or functions.

Quickstart

This example demonstrates how to apply timeouts to the setup, execution, and teardown phases of a test using markers. The `test_timeout_phases` function's execution phase is intentionally set to exceed its defined timeout, which should cause a failure. You can also configure timeouts globally via `pytest.ini` or command-line options like `--setup-timeout`.

import time
import pytest

# Configure global timeouts in pytest.ini (optional):
# [pytest]
# setup_timeout = 0.3
# execution_timeout = 0.5
# teardown_timeout = 0.4

@pytest.mark.setup_timeout(0.3)
@pytest.mark.execution_timeout(0.5)
@pytest.mark.teardown_timeout(0.4)
def test_timeout_phases():
    print("\nStarting setup (simulated)")
    time.sleep(0.1) # Simulate setup
    print("Starting execution (simulated)")
    time.sleep(0.6) # This will exceed execution_timeout(0.5)
    print("Starting teardown (simulated)")
    time.sleep(0.1) # Simulate teardown

def test_no_timeout():
    print("\nRunning test without explicit timeouts")
    time.sleep(0.1)

# To run this test, save as test_example.py and execute:
# pytest -v test_example.py