Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 38 ยท Parametrization and Marks

Custom Marks and Strict Markers

Label tests with custom marks like slow or integration, register them in pytest.ini, select with the -m expression, enforce --strict-markers, and mark whole modules and classes.

A mark is a label you attach to a test. You have already used built-in marks (skip, skipif, xfail, parametrize, usefixtures, filterwarnings). pytest lets you invent your own: slow, integration, smoke, needs_network, windows_only. Then you tell pytest, from the command line, which labelled tests to run or leave out.

Marks are how a suite grows without becoming unusable: the 200 fast unit tests run on every save, the 20 slow integration tests run before a release, and nobody has to maintain separate folders for them.

Creating and using a mark

Apply a mark with the decorator syntax @pytest.mark.<name>. Any name works:

Python A custom mark and the -m option

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The -m option takes a mark expression. The first run executes only the two slow tests; the second runs everything except them. A test may carry several marks (see test_full_checkout).

Mark expressions

-m supports and, or, not and parentheses:

Command Runs
pytest -m slow tests marked slow
pytest -m "not slow" everything else
pytest -m "smoke and not slow" fast smoke tests
pytest -m "slow or integration" either label
pytest -m "(smoke or regression) and not flaky" grouping

Do not confuse -m with -k: -m selects by mark, -k by name text.

Python Combining marks in an expression

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Only test_a matches. --collect-only is a nice way to preview any selection.

Register your marks

pytest warns about marks it does not know, because @pytest.mark.slwo (a typo) would silently label nothing. Register each mark in your configuration with a description:

INI
# pytest.ini
[pytest]
markers =
    slow: tests that take more than a second
    integration: tests that need a database or network
    smoke: quick checks of the critical paths

Or in pyproject.toml:

TOML
[tool.pytest.ini_options]
markers = [
    "slow: tests that take more than a second",
    "integration: tests that need a database or network",
]

pytest --markers lists every registered mark with its description, including pytest's own.

Strict markers

Run with --strict-markers (or put it in addopts) and an unregistered mark becomes an error instead of a warning. This turns typos into immediate failures:

Python --strict-markers catches typos

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The collection error says 'slwo' not found in markers configuration option. Without strict mode this test would run normally with only a warning, and -m slow would silently miss it. Most projects set:

INI
[pytest]
addopts = --strict-markers --strict-config

Marks on classes and whole modules

A mark on a class applies to all its tests. To mark an entire module, assign pytestmark:

Python Class and module marks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

pytestmark may also be a list: pytestmark = [pytest.mark.api, pytest.mark.slow]. Marks combine from module, class and function.

Marks with arguments

A mark can carry arguments, which you read through the test item. This makes marks a tiny configuration language for fixtures and hooks:

Python Reading mark arguments in a fixture

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

get_closest_marker(name) finds the mark on the function, then its class, then the module, returning None if there is none. The plugin pytest-timeout works in just this way.

Automatic marking in conftest.py

You can apply marks by rule instead of editing every test. The pytest_collection_modifyitems hook receives all collected items and can add marks, for example "everything under tests/integration is integration":

Python
# conftest.py
import pytest

def pytest_collection_modifyitems(items):
    for item in items:
        if "integration" in item.nodeid:
            item.add_marker(pytest.mark.integration)

This is the usual way to keep mark use consistent in large suites.

Practical mark strategy

  1. Keep the list of marks short and meaningful: slow, integration, smoke, and platform or service markers.
  2. Register them, describe them, and use --strict-markers.
  3. Run the fast subset locally (-m "not slow and not integration") and everything in CI.
  4. Do not use marks to hide broken tests; use xfail with a reason for that.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command runs only tests marked slow?

    -m selects by mark; -k matches names.
  2. 2. What does --strict-markers do?

    With strict markers, using a mark that is not registered in the configuration is an error.
  3. 3. How do you apply one mark to every test in a module?

    A module-level variable named pytestmark applies its marks to all tests in the file.
  4. 4. What does request.node.get_closest_marker("timeout") return?

    It searches from the test outward and returns the first matching Mark object or None.

Summary

  • A mark is a label: @pytest.mark.slow; select with -m "expression" using and, or, not.
  • Register marks in pytest.ini or pyproject.toml and list them with pytest --markers.
  • --strict-markers turns typos into errors.
  • Mark classes with the decorator and whole modules with pytestmark.
  • Marks can carry arguments, read with get_closest_marker, and hooks like pytest_collection_modifyitems can add marks automatically.

Next: The monkeypatch Fixture