Running tests by marker (-m) in PyTest - Deep Dive

Overview - Running tests by marker (-m)

What is it?

Running tests by marker (-m) in pytest means selecting and executing only those tests that have a specific label or tag called a marker. Markers are special keywords you add to tests to group or categorize them. Using the -m option lets you run tests with certain markers without running the entire test suite. This helps focus on relevant tests quickly.

Why it matters

Without the ability to run tests by marker, you would have to run all tests every time, which wastes time and resources. Markers let you organize tests by features, bug fixes, or test types, so you can run just what you need. This speeds up development and debugging, making testing more efficient and manageable.

Where it fits

Before learning about running tests by marker, you should understand basic pytest test creation and execution. After this, you can learn about advanced pytest features like test parametrization, fixtures, and custom markers to further organize and optimize tests.

Mental Model

Core Idea

Markers are labels on tests that let you pick and run only the tests you want using the -m option.

Think of it like...

Imagine a big box of mixed keys where each key has a colored tag. If you only want keys with a red tag, you pick out those and ignore the rest. Markers are like those colored tags on tests.

Test Suite
├─ Test A [marker: smoke]
├─ Test B [marker: slow]
├─ Test C [marker: smoke]
└─ Test D [no marker]

Command: pytest -m smoke
Runs: Test A, Test C only

Build-Up - 7 Steps

1

Foundation

What are pytest markers?

Concept: Markers are special labels you add to tests to group or identify them.

In pytest, you add a marker by placing @pytest.mark.name above a test function. For example: import pytest @pytest.mark.smoke def test_example(): assert True This marks the test as 'smoke'.

Result

The test is now labeled with 'smoke' and can be selected by this marker.

Understanding markers is key to organizing tests beyond just naming conventions.

2

Foundation

How to run all tests normally

Concept: By default, pytest runs all tests it finds without filtering.

Run pytest in the terminal: pytest This runs every test in the current directory and subdirectories.

Result

All tests execute regardless of markers or labels.

Knowing the default behavior helps appreciate why filtering by marker is useful.

3

Intermediate

Running tests by a single marker

🤔Before reading on: do you think pytest -m smoke runs tests without the smoke marker? Commit to yes or no.

Concept: The -m option runs only tests with the specified marker name.

Use the command: pytest -m smoke This runs only tests marked with @pytest.mark.smoke.

Result

Only tests labeled 'smoke' run; others are skipped.

Filtering tests by marker saves time by focusing on relevant tests.

4

Intermediate

Combining markers with expressions

🤔Before reading on: can you combine markers with 'and' or 'or' in pytest -m? Commit to yes or no.

Concept: You can use logical expressions with -m to run tests matching complex marker conditions.

Examples: pytest -m "smoke and not slow" Runs tests marked 'smoke' but not 'slow'. pytest -m "smoke or slow" Runs tests marked 'smoke' or 'slow'.

Result

Tests run based on combined marker logic, allowing precise selection.

Logical expressions with markers give powerful control over test selection.

5

Advanced

Registering custom markers in pytest.ini

🤔Before reading on: do you think pytest requires marker registration to avoid warnings? Commit to yes or no.

Concept: Pytest recommends registering custom markers in a config file to document them and avoid warnings.

Create pytest.ini with: [pytest] markers = smoke: quick smoke tests slow: slow running tests This tells pytest about your markers.

Result

Pytest runs markers without warnings and documents them for others.

Registering markers improves test suite clarity and prevents confusion.

6

Advanced

Using markers for test selection in CI pipelines

Concept: Markers help run only relevant tests in continuous integration to save time and resources.

In CI config, run: pytest -m smoke to run only smoke tests on every commit, and run full tests nightly.

Result

Faster feedback on critical tests, full coverage later.

Markers enable efficient testing strategies in real-world development.

7

Expert

Marker pitfalls and best practices

🤔Before reading on: do you think using too many markers always improves test management? Commit to yes or no.

Concept: Overusing markers or inconsistent naming can cause confusion and maintenance issues.

Avoid creating too many markers or overlapping meanings. Use clear, documented markers and register them. Review marker usage regularly.

Result

Cleaner test suites and reliable test selection.

Knowing marker limits prevents complexity that harms test clarity and reliability.

Under the Hood

Pytest collects all test functions and reads their markers as metadata attached to each test item. When you run pytest with -m, it evaluates the marker expression against each test's markers. Only tests matching the expression are scheduled for execution; others are skipped. This filtering happens before test execution, making it efficient.

Why designed this way?

Markers were designed to provide flexible, human-readable grouping of tests without changing test code structure. The expression syntax allows complex selection without writing custom code. Registering markers prevents typos and documents test intent, improving collaboration.

Test Collection
┌───────────────┐
│ Test Functions│
│ with Markers  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Marker Filter │ <─ Command: pytest -m "expression"
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Selected Tests│
│   to Run      │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does pytest -m run tests without the specified marker? Commit yes or no.

Common Belief: Running pytest -m smoke runs all tests including those without the smoke marker.

Reality: Only tests explicitly marked with 'smoke' run; others are skipped.

Why it matters: Expecting unmarked tests to run can cause missed test coverage and false confidence.

Quick: Can you use any random word as a marker without registering it? Commit yes or no.

Common Belief: You can freely use any marker name without setup or warnings.

Reality: Pytest warns about unknown markers unless registered in pytest.ini or config.

Why it matters: Ignoring marker registration leads to warnings and confusion about marker meanings.

Quick: Does combining markers with 'and' or 'or' in -m work? Commit yes or no.

Common Belief: You cannot combine markers with logical operators in pytest -m.

Reality: Pytest supports logical expressions like 'and', 'or', and 'not' in -m.

Why it matters: Not knowing this limits test selection flexibility and efficiency.

Quick: Does adding many markers always improve test organization? Commit yes or no.

Common Belief: More markers always make tests easier to manage.

Reality: Too many or unclear markers cause confusion and maintenance overhead.

Why it matters: Overusing markers can make test suites harder to understand and select correctly.

Expert Zone

1

Markers are stored as metadata on test items, allowing plugins and hooks to interact with them for advanced behaviors.

2

Marker expressions in -m are parsed using Python's own expression syntax, enabling complex logical combinations.

3

Unregistered markers still work but cause warnings; registering markers documents intent and improves team communication.

When NOT to use

Avoid using markers for selecting tests when test selection depends on runtime data or external conditions; use pytest hooks or custom plugins instead. Also, do not rely on markers alone for test prioritization; combine with test ordering or parametrization.

Production Patterns

Teams use markers to separate smoke, regression, slow, or flaky tests. CI pipelines run smoke tests on every commit using -m smoke, nightly full runs without -m, and special runs for slow tests. Markers also help skip tests on certain platforms or environments.

Connections

Feature Flags in Software Development

Both use labels to control what runs or is enabled dynamically.

Understanding markers as dynamic selectors helps grasp how feature flags enable or disable features without code changes.

Tags in Project Management Tools

Markers in tests are like tags on tasks to organize and filter work items.

Knowing how tags help filter tasks clarifies why markers help filter tests efficiently.

Database Query Filters

Marker expressions act like WHERE clauses filtering test records to run.

Seeing marker selection as a query helps understand the power of logical expressions in test filtering.

Common Pitfalls

#1 Running pytest -m with a typo in marker name silently skips all tests.

Wrong approach:

pytest -m smkoe

Correct approach:

pytest -m smoke

Root cause:

Typos in marker names cause no matches, so no tests run, leading to false success.

#2 Not registering custom markers causes warnings and confusion.

Wrong approach:

Using @pytest.mark.slow without adding to pytest.ini

Correct approach:

[pytest]
markers =
slow: marks slow tests

Root cause:

Pytest requires marker registration to document and avoid warnings.

#3 Using too many overlapping markers makes test selection confusing.

Wrong approach:

Marking tests with both @pytest.mark.smoke and @pytest.mark.quick without clear rules

Correct approach:

Define clear marker purposes and avoid overlap, e.g., smoke for critical, quick for fast tests

Root cause:

Lack of marker strategy leads to ambiguous test groups.

Key Takeaways

Markers are labels that let you run only selected tests using pytest's -m option.

You can combine markers with logical expressions like and, or, and not for precise test selection.

Registering custom markers in pytest.ini prevents warnings and documents test intent.

Using markers wisely improves test speed and organization, especially in large projects and CI pipelines.

Overusing or misusing markers can cause confusion and skipped tests, so maintain clear marker strategies.