Pytest Tagging

1.6.0 · active · verified Thu Apr 16

pytest-tagging is an active pytest plugin, currently at version 1.6.0, designed to simplify test categorization by allowing users to tag tests with arbitrary strings without the need for explicit marker registration. It enhances pytest's built-in capabilities, enabling granular selection and exclusion of tests based on these tags, and providing summary statistics like failed test counts per tag. The library typically sees several minor or patch releases per year, indicating active maintenance.

Common errors

```
PytestUnknownMarkWarning: Unknown 'your_custom_tag' mark. Add 'your_custom_tag' to 'markers' in your pytest config file to avoid this warning.
```
cause This warning occurs when you use `@pytest.mark.your_custom_tag` directly without registering 'your_custom_tag' in your `pytest.ini` or `pyproject.toml` configuration. `pytest-tagging` is designed to circumvent this by providing `@pytest.mark.tags()` for arbitrary tags.

fix Instead of `@pytest.mark.your_custom_tag`, use `@pytest.mark.tags("your_custom_tag")`. `pytest-tagging` will handle the dynamic tagging without requiring explicit registration for each tag.
```
No tests were collected / 0 tests ran
```
cause When running tests with `--tags`, this typically means no tests matched the specified tag criteria. This could be due to typos in tags, incorrect logical expressions, or the tests simply not having the expected tags.

fix Double-check the tags on your test functions and classes for accuracy. Verify the `--tags` command-line argument for typos or logical errors (e.g., `pytest --tags "tag1 and tag2"` will only run tests with *both* tags). Use `pytest --collect-only` to see collected tests and their marks/tags without running them.
```
AttributeError: 'Module' object has no attribute 'mark_tags'
```
cause This error or similar (e.g., trying to import `tag` directly) occurs if you attempt to import `tags` or `mark_tags` directly from the `pytest_tagging` library. `pytest-tagging` is a plugin that integrates with `pytest.mark`, not a module meant for direct import of marking decorators.

fix Ensure you are importing `pytest` and using `@pytest.mark.tags("your_tag")`. Do not try to import `tag` or `mark_tags` from `pytest_tagging`.

Warnings

gotcha When using both `--tags` and `--exclude-tags`, excluded tags take precedence. A test matching a selected tag will still be skipped if it also matches an excluded tag.
Fix: Carefully design your tag selection and exclusion logic. If a test is unexpectedly skipped, check if it has any tags listed in `--exclude-tags`.
gotcha The primary benefit of `pytest-tagging` is to avoid `PytestUnknownMarkWarning` (or errors with `strict_markers=True`) that occur when using arbitrary `@pytest.mark.<custom_tag>` without registering the custom tag in `pytest.ini` or `pyproject.toml`. With `pytest-tagging`, you consistently use `@pytest.mark.tags("your_tag")` and the plugin handles the collection.
Fix: Always use `@pytest.mark.tags("your_tag")` provided by `pytest-tagging` for arbitrary tags instead of `pytest.mark.<your_custom_tag>` if you want to avoid explicit marker registration. If you want to use standard `pytest.mark` markers, ensure they are registered or you are not using `strict_markers=True`.
breaking While `pytest-tagging` version 1.6.0 relaxed its `pytest` dependency, older versions of the plugin might have stricter `pytest` version requirements. Incompatible `pytest` versions could lead to unexpected behavior or plugin not loading correctly. [cite: 27 on GitHub]
Fix: Always check the `pytest-tagging` release notes and PyPI metadata for the `requires_python` and `install_requires` to ensure compatibility with your `pytest` version. Upgrade `pytest-tagging` to the latest version (1.6.0+) for broader `pytest` compatibility.

Install

pip install pytest-tagging Install stable version

Imports

pytest.mark.tags
wrong:
```
from pytest_tagging import tag
```
correct:
```
import pytest

@pytest.mark.tags("smoke", "api")
def test_critical_api():
    assert True
```
pytest-tagging works by extending the `pytest.mark` system; you do not import a separate `tag` decorator from `pytest_tagging` itself. The primary decorator to use is `@pytest.mark.tags()` for function or class level tagging.

Quickstart

Create a file named `test_example.py` with the content above. Then, run pytest from your terminal using the `--tags` option to select tests. You can combine tags with 'and', 'or', and 'not' logic. To run tests tagged 'smoke' or 'login', use `pytest --tags "smoke or login"`. To run tests tagged 'regression' but *not* 'critical', use `pytest --tags "regression not critical"`.

import pytest

# Tagging a test function
@pytest.mark.tags("smoke", "login")
def test_successful_login():
    assert 1 == 1

# Tagging a whole test class
@pytest.mark.tags("regression")
class TestUserProfile:
    def test_view_profile(self):
        assert True

    @pytest.mark.tags("critical")
    def test_update_profile(self):
        assert False # This test is expected to fail for demonstration

view raw JSON →