---
id: detect-test-pollution
version: "1.2.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# detect-test-pollution — a tool to detect test pollution

License: permissive · Maintenance: active · Downloads: 324.3K/mo

## What it is and what it does

detect-test-pollution is a command-line tool that finds which test is polluting another test when test order matters. Test pollution occurs when a test fails mysteriously in one order but passes when run alone—a common flake symptom. The tool works by bisecting your test suite: given a failing test, it repeatedly runs subsets of your other tests alongside it to narrow down which test causes the failure. It supports two modes: normal detection (when you've identified a failing test) and fuzzing (shuffling tests until a failure appears, then finding its cause).

The tool is pytest-specific and requires your tests to be discoverable and runnable via pytest. It has no runtime dependencies beyond Python itself, making installation and setup straightforward. Bisection typically completes in logarithmic steps relative to your test count, so even large suites can be debugged in reasonable time.

Use it for:

- Isolate the root cause of a flaky test that fails in CI but passes locally or when run in isolation.
- Debug test suites where pytest-randomly or pytest-xdist expose hidden test interdependencies.
- Fuzz a test suite to discover latent pollution before it causes production issues.
- Identify global state mutations (module-level variables, mocked objects, database state) left behind by tests.
- Refactor or split a monolithic test file by finding which tests depend on execution order.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Detects test pollution—failures caused by side effects from other tests—by bisecting your test suite to isolate the pair of tests that interact.

Yes. If you maintain a pytest suite and have encountered flaky tests or test-order sensitivity, this tool directly solves a hard debugging problem with low friction and no dependencies. Even if you haven't hit the problem yet, it's lightweight enough to keep on hand. No security concerns, active maintenance, and permissive license.

## Install

pip install detect-test-pollution
uv add detect-test-pollution
poetry add detect-test-pollution

## Installing detect-test-pollution

Before you install: Low friction: pure Python wheel with no runtime dependencies. Actively maintained as of July 2026 with 205 repository stars.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install detect-test-pollution

detect-test-pollution \
    --failing-test test.py::test_id_here \
    --tests ./tests

Requires pytest to be installed and your tests to be runnable via pytest; requires Python >=3.8.

Verify before relying:

- Effectiveness on very large test suites (thousands of tests) and whether bisection time remains practical.
- Whether the tool handles parametrized tests, fixtures with side effects, or async test pollution.
- Support for pytest plugins that affect test ordering or isolation (e.g., pytest-xdist in worker mode).

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 324.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

test pollution detection, find flaky test causes, test isolation debugging, pytest test dependencies, test order sensitivity, bisect failing tests, test side effects finder, pytest-plugin, test-debugging, flaky-tests

[View on SkillFed](https://skillfed.io/packages/detect-test-pollution) · [View on PyPI](https://pypi.org/project/detect-test-pollution/)