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.

Practice

1. What does the -m option do when running pytest?

easy

A. Runs only tests with the specified marker

B. Runs tests in a specific directory

C. Runs tests in parallel

D. Generates a test report

Solution

1. Step 1: Understand pytest markers

   Markers are labels you add to tests to group them logically.

2. Step 2: Use -m option

   The -m option runs only tests that have the specified marker label.

3. Final Answer:

   Runs only tests with the specified marker -> Option A

4. Quick Check:

   pytest -m runs tests by marker = A [OK]

Hint: Remember: -m filters tests by marker name [OK]

Common Mistakes:

• Confusing -m with directory or file options
• Thinking -m runs all tests regardless of marker
• Assuming -m runs tests in parallel

2. Which of the following is the correct syntax to run pytest tests marked as slow?

easy

A. pytest --marker slow

B. pytest -m slow

C. pytest -marker slow

D. pytest --m slow

Solution

1. Step 1: Recall pytest command options

   The correct option to select tests by marker is -m, not --marker or others.

2. Step 2: Match syntax to run tests with marker

   The correct command is pytest -m slow to run tests marked as slow.

3. Final Answer:

   pytest -m slow -> Option B

4. Quick Check:

   Use single dash -m for marker filter = D [OK]

Hint: Use single dash -m, not --marker [OK]

Common Mistakes:

• Using --marker instead of -m
• Adding extra dashes like --m
• Confusing option names

3. Given these tests marked as fast and db:

@pytest.mark.fast
def test_a(): pass

@pytest.mark.db
def test_b(): pass

@pytest.mark.fast
def test_c(): pass

What tests run with the command pytest -m "fast and not db"?

medium

A. test_b only

B. No tests run

C. test_a, test_b, and test_c

D. test_a and test_c

Solution

1. Step 1: Understand the marker expression

   The command runs tests marked with fast AND NOT marked with db.

2. Step 2: Check each test's markers

   test_a and test_c have fast only; test_b has db only.

3. Final Answer:

   test_a and test_c -> Option D

4. Quick Check:

   fast and not db = test_a, test_c [OK]

Hint: Use logical operators to combine markers correctly [OK]

Common Mistakes:

• Including tests marked only with db
• Ignoring the 'not' operator
• Assuming all tests run

4. You run pytest -m slow but no tests run, even though some tests have @pytest.mark.slow. What is the most likely cause?

medium

A. Markers are not registered in pytest.ini

B. You used -m instead of --m

C. The tests are skipped by default

D. The test files are missing

Solution

1. Step 1: Check marker registration

   Pytest requires custom markers to be registered in pytest.ini to avoid warnings and ensure correct filtering.

2. Step 2: Understand effect of missing registration

   If markers are not registered, pytest may ignore them or not run tests filtered by them.

3. Final Answer:

   Markers are not registered in pytest.ini -> Option A

4. Quick Check:

   Unregistered markers cause no tests run = C [OK]

Hint: Always register custom markers in pytest.ini [OK]

Common Mistakes:

• Confusing -m and --m options
• Assuming tests are skipped by default
• Not checking test file presence

5. You have tests marked as api, ui, and db. You want to run tests that are either api or ui, but not db. Which command achieves this?

hard

A. pytest -m "api or (ui and not db)"

B. pytest -m "api or ui and not db"

C. pytest -m "(api or ui) and not db"

D. pytest -m "api and ui and not db"

Solution

1. Step 1: Understand operator precedence

   Logical AND has higher precedence than OR, so parentheses are needed to group api or ui together.

2. Step 2: Analyze each option

   pytest -m "(api or ui) and not db" correctly groups (api or ui) and excludes db with and not db.

3. Final Answer:

   pytest -m "(api or ui) and not db" -> Option C

4. Quick Check:

   Use parentheses to group OR conditions = A [OK]

Hint: Use parentheses to group markers with OR before AND [OK]

Common Mistakes:

• Ignoring operator precedence without parentheses
• Using AND instead of OR between api and ui
• Including db tests by mistake