Custom Marks and Filtering Tests

Introduction to Marking

At its core, a mark is simply a decorator that labels your test function with specific metadata. By using the @pytest.mark syntax, you inform the testing framework that a particular test belongs to a logical grouping or possesses a specific characteristic. This mechanism works by creating a dictionary of markers associated with each test item, which the internal runner inspects before and during test execution. When you label a function, you are effectively tagging it so that you can later filter or selectively execute subsets of your suite. This is far more robust than naming conventions or directory structures, as a single test can belong to multiple categories simultaneously. Because these marks are attached at the function or class level, they provide a declarative way to define test attributes without cluttering the business logic within the test itself, keeping the codebase maintainable as the test suite scales over time.

import pytest

# Mark a test as belonging to the 'smoke' category
@pytest.mark.smoke
def test_critical_path_login():
    assert True

# Marks can be applied to functions or classes
@pytest.mark.ui
def test_dashboard_rendering():
    assert True

Filtering Tests via Command Line

Once you have labeled your tests with custom markers, you gain the power to filter them at the command line using the -m flag. This flag tells the engine to only execute tests that match the specified expression. The evaluation engine processes your request by comparing your provided expression against the markers existing in the collected test items. If a test does not contain the requested label, it is dynamically deselected, meaning it won't even show up in your test report unless you explicitly ask to see skipped or deselected tests. This behavior is incredibly powerful because it allows a single test file to house tests for different environments, such as local development, staging, or production, without requiring separate configuration files. You effectively build a query engine that lets you extract precisely the subset of tests relevant to your current focus, saving significant time during the development loop and allowing for faster feedback cycles.

# Run only smoke tests
# command: pytest -m smoke

# Run smoke tests but exclude 'slow' ones
# command: pytest -m "smoke and not slow"

def test_fast_check():
    assert 1 == 1

@pytest.mark.slow
def test_large_data_processing():
    assert 1 == 1

Registering Custom Marks

As you begin adding many unique marks to your codebase, you may encounter warnings informing you that your marks are not registered. This is a deliberate safety feature designed to prevent typos, such as accidentally writing @pytest.mark.smkoe instead of @pytest.mark.smoke, from creating silent failures where tests are ignored. To solve this, you must explicitly register your custom marks in a configuration file like pytest.ini. Registration provides a central registry that the framework consults. By defining your marks here, you not only eliminate these warnings but also create a searchable documentation layer where developers can see which categories exist and why they are used. This configuration acts as a single source of truth for the project's metadata structure, ensuring consistency across all contributors. It enforces discipline in how tests are labeled and allows you to add descriptions, which further aids in onboarding and helps maintain the architectural integrity of your testing strategy.

# File: pytest.ini
# [pytest]
# markers =
#     smoke: Critical tests for deployment
#     ui: Tests involving browser interaction

import pytest

@pytest.mark.smoke
def test_registration_verification():
    assert True

Conditional Execution with Marks

Beyond simple filtering, marks can be used to skip tests conditionally based on the environment or the state of the system under test. This is achieved by combining marks with the 'skipif' or 'xfail' decorators. When you define a mark that influences test execution, you are providing the framework with logic that is evaluated at collection time. For example, you might mark a test as requiring a specific database or a particular operating system. The internal engine evaluates the expression associated with the mark, and if the condition is not met, the test is marked as skipped. This ensures that you don't waste cycles attempting to run tests that are guaranteed to fail due to missing dependencies. This pattern is essential for cross-platform applications where certain features only exist on Linux or specific cloud providers, effectively turning your test suite into an environment-aware system that adapts to its surroundings automatically.

import sys
import pytest

# Skip this test if not running on Linux
@pytest.mark.skipif(sys.platform != "linux", reason="Requires Linux")
def test_linux_specific_feature():
    assert True

# Mark as expected to fail, but only for a specific reason
@pytest.mark.xfail(reason="Feature pending implementation")
def test_not_yet_implemented():
    assert 0

Applying Marks Dynamically

While static decorators are the most common way to apply markers, there are scenarios where you must determine the marks at runtime based on external factors like configuration files or environment variables. This is handled through a hook called pytest_collection_modifyitems, which allows you to programmatically inspect and modify the collected tests before they run. This hook provides access to the list of test items, enabling you to add or remove markers based on your own logic. By interacting with the collection process directly, you achieve a level of dynamism that static decorators cannot reach. For instance, you could read a list of 'flaky' tests from a database and dynamically mark them as 'xfail' so that they don't break your CI pipeline. This advanced pattern decouples the test logic from the test configuration, allowing for high levels of automation and flexible test suite management in complex enterprise environments.

# File: conftest.py
def pytest_collection_modifyitems(config, items):
    for item in items:
        if "slow" in item.keywords:
            # Dynamically skip all tests marked as slow if requested
            if config.getoption("--no-slow"):
                item.add_marker(pytest.mark.skip(reason="slow tests disabled"))

def test_dynamic_example():
    assert True

Interview questions

All pytest & Testing interview questions →

Check yourself

Take the full pytest & Testing quiz →