💡 pytest-only-markers

A pytest plugin that lets you isolate specific tests using ONLY_* markers. When any test is decorated with a marker prefixed ONLY_ (case-insensitive: ONLY_ or only_), only those tests are collected and run — all other tests (and their inherited pytestmark markers) are suppressed.

📦 Installation

uv add pytest-only-markers

🚀 Features

• ✅ Selective collection — only tests carrying an ONLY_* marker are collected; all others are deselected
• ✅ Case-insensitive prefix — both ONLY_* and only_* are recognised (e.g. @pytest.mark.ONLY_smoke and @pytest.mark.only_smoke are equivalent)
• ✅ Marker isolation — non-ONLY_* markers (including module-level pytestmark) are stripped from matching items
• ✅ Transparent deselection — skipped tests appear in pytest's x deselected summary, not silently dropped
• ✅ Instance-level patch — iter_markers is patched per item so downstream plugins see only ONLY_* markers
• ✅ Opt-in via flag — behaviour is disabled by default; activate with --only-markers-prefix

🛠️ How to Use

1. Install the plugin via uv add pytest-only-markers
2. Enable it by adding --only-markers-prefix to your pytest.ini or passing it on the CLI
3. Decorate any test with @pytest.mark.ONLY_<name> (or @pytest.mark.only_<name>) to mark it for isolated execution
4. Run pytest — only tests with ONLY_* markers will be collected and executed

🚀 Quick Start

Add to pytest.ini:

[pytest]
addopts = --only-markers-prefix
markers =
    ONLY_smoke: Run only smoke tests
    ONLY_api: Run only API tests

Then tag your tests:

pytestmark = [pytest.mark.regression, pytest.mark.slow]

@pytest.mark.ONLY_smoke
def test_health_check():
    ...
# Collected and run — effective markers: ONLY_smoke only

def test_full_flow():
    ...
# Deselected — no ONLY_* marker

▶️ Usage Examples

Example 1: Single ONLY_ marker

import pytest

pytestmark = [pytest.mark.regression, pytest.mark.slow]

@pytest.mark.ONLY_smoke
def test_ping():
    assert True
# Result: collected, runs with only ONLY_smoke marker
# test_heavy and test_regression are deselected

Example 2: Multiple ONLY_ markers on one test

import pytest

pytestmark = [pytest.mark.dummy]

@pytest.mark.ONLY_api
@pytest.mark.ONLY_smoke
def test_create_user():
    assert True
# Result: collected, effective markers are ONLY_api + ONLY_smoke
# pytestmark (dummy) is stripped

Example 3: Case-insensitive prefix

import pytest

@pytest.mark.only_smoke   # lowercase — works the same as ONLY_smoke
def test_ping():
    assert True

@pytest.mark.ONLY_smoke   # uppercase — equivalent
def test_pong():
    assert True

Example 4: CLI usage without modifying pytest.ini

pytest --only-markers-prefix tests/

🤝 Contributing

If you have a helpful pattern or improvement to suggest: Fork the repo Create a new branch Submit a pull request I welcome additions that promote clean, productive, and maintainable development.

📄 License

MIT License — see LICENSE for details.

🙏 Thanks

Thanks for exploring this repository!
Happy coding!