pytest-threadleak

0.5.0 · active · verified Fri Apr 17

pytest-threadleak is a pytest plugin that automatically detects non-daemon thread leaks after tests complete. It helps identify when tests leave background threads running, which can cause resource exhaustion or unexpected behavior. The current version is 0.5.0, and it is maintained with releases as needed for bug fixes or new features.

Common errors

```
pytest.FixtureLookupError: fixture 'threadleak' not found
```
cause The pytest-threadleak plugin is not installed, or pytest cannot find it in the current environment.

fix Ensure `pytest-threadleak` is installed in the same Python environment where you are running pytest: `pip install pytest-threadleak`.
```
Failed: ThreadLeakError: The following threads were still running after the test: ['<Thread(Thread-1, started 123456789)>']
```
cause A non-daemon thread was spawned during the test and was still active when the test completed. This is the core functionality of the plugin detecting a leak.

fix Identify the code spawning the listed thread(s) and ensure they are either daemonized (if background processing) or properly joined/terminated before the test function finishes. If it's an expected background thread, consider adding its name pattern to `threadleak_thread_name_patterns_to_ignore` in `pytest.ini`.

Warnings

breaking Python 2 support was dropped in version 0.3.0. Users on Python 2 must use an older version.
Fix: Upgrade to Python 3 or restrict pytest-threadleak version to 0.2.0 or earlier if Python 2 is strictly required (not recommended for new projects).
gotcha pytest-threadleak only detects threads that are *still running* and are *not daemon threads* after a test. Threads that complete and join successfully before the test ends will not be flagged. Daemon threads are also ignored by default.
Fix: Ensure all non-daemon threads are explicitly joined or terminated within the test's scope. For long-running background threads that are expected, configure `threadleak_thread_name_patterns_to_ignore` in your `pytest.ini`.
gotcha If tests fail with `ThreadLeakError` for threads that are part of standard libraries or external packages (e.g., from `requests` or `concurrent.futures`), these threads might need to be explicitly ignored.
Fix: Use the `threadleak_thread_name_patterns_to_ignore` option in your `pytest.ini` to specify regular expressions matching the names of threads that should be ignored, for example: `threadleak_thread_name_patterns_to_ignore = 'ThreadPoolExecutor.*'`.

Install

pip install pytest-threadleak pytest Install pytest-threadleak and pytest

Imports

threadleak
wrong:
```
from pytest_threadleak import threadleak
```
correct:
```
def test_something(threadleak): ...
```
pytest-threadleak provides fixtures, not direct module imports for its core functionality. The 'threadleak' fixture is automatically discovered and injected by pytest.

Quickstart

To get started, simply install `pytest-threadleak` and include the `threadleak` fixture in your test functions. The plugin automatically checks for new non-daemon threads spawned during the test that are still active when the test finishes. The example demonstrates a clean test and how to intentionally create a leak to see the plugin in action.

import threading
import time

# test_my_app.py

def test_my_function_no_leak(threadleak):
    """
    This test uses the 'threadleak' fixture to ensure no new
    non-daemon threads are left running after the test completes.
    This specific test should pass cleanly.
    """
    def do_something_brief():
        time.sleep(0.01)
    
    t = threading.Thread(target=do_something_brief)
    t.start()
    t.join() # Ensure the thread finishes before the test does

# To run this test:
# pip install pytest-threadleak pytest
# pytest test_my_app.py

# To observe a leak (uncomment and run):
# def test_my_function_with_leak(threadleak):
#     """
#     This test will intentionally leave a non-daemon thread running,
#     causing pytest-threadleak to report a ThreadLeakError.
#     """
#     def infinite_loop():
#         while True:
#             time.sleep(0.1)
#     
#     threading.Thread(target=infinite_loop).start()

view raw JSON →