Introduction

As Selenium automation projects grow, different categories of tests are created for various purposes. While PyTest provides built-in marks, you can also create your own labels to organize tests according to your project’s needs.

These labels are called Custom Markers. They allow you to group related tests, making it easy to execute only the required subset of your automation suite.

In this tutorial, you’ll learn what Custom Markers are, how to create them, and how to register them properly in PyTest.

What are Custom Markers?

Custom Markers are user-defined labels that categorize test cases.

Unlike built-in markers, you choose the marker names based on your project requirements.

For example:

                    Test Suite

                         │

      ┌──────────────────┼──────────────────┐

      │                  │                  │

  smoke            regression         playground

      │                  │                  │

      ▼                  ▼                  ▼

 Critical Tests     Full Testing      Selenium Playground

Each marker represents a logical group of tests.

Why Use Custom Markers?

Custom Markers help you:

Organize large test suites.
Execute only selected tests.
Improve test readability.
Simplify CI/CD execution.
Group related Selenium tests.

How Custom Markers Work

PyTest uses the @pytest.mark decorator.

Example:

@pytest.mark.playground

This attaches the playground marker to the test.

The marked test can later be executed using:

pytest -s -m playground

Example

import pytest
from selenium import webdriver


# Topic: 41. Advanced PyTest - Custom Markers
# Practice site: https://www.testmuai.com/selenium-playground/
# Run: pytest -s -m playground 41_examples/test_03_custom_markers.py
#
# Custom markers should be registered in pytest.ini so PyTest does not warn
# about unknown marks.


@pytest.mark.playground
def test_custom_markers():
    driver = webdriver.Chrome()

    try:
        driver.get("https://www.testmuai.com/selenium-playground/")
        assert "selenium-playground" in driver.current_url
    finally:
        driver.quit()

Understanding the Code

Import Required Libraries

import pytest
from selenium import webdriver

These modules are used to:

Apply PyTest markers.
Launch the Chrome browser.

Create a Custom Marker

@pytest.mark.playground

The @pytest.mark.playground decorator assigns the playground marker to this test.

This groups the test into the playground category.

Define the Test Function

def test_custom_markers():

This is a standard PyTest test function.

Because it has the playground marker, it can be executed independently.

Launch the Browser

driver = webdriver.Chrome()

Starts a new Chrome browser session.

Open the Practice Website

driver.get(
    "https://www.testmuai.com/selenium-playground/"
)

Navigates to the Selenium Playground website.

Verify the Current URL

assert "selenium-playground" in driver.current_url

The assert statement verifies that the browser has successfully opened the Selenium Playground page.

If the URL does not contain selenium-playground, the test fails.

Close the Browser

driver.quit()

Closes the browser and ends the WebDriver session.

Registering Custom Markers

Custom markers should always be registered to prevent Unknown Mark Warnings.

In this project, the markers are registered using the pytest_configure() hook:

def pytest_configure(config):
    config.addinivalue_line(
        "markers",
        "playground: tests that use Selenium Playground"
    )

Another common approach is registering markers inside the pytest.ini file, which you’ll learn in the next topic.

Running Custom Marker Tests

To execute only the playground tests, run:

pytest -s -m playground

PyTest executes only tests marked with:

@pytest.mark.playground

Practical Example

Suppose your project contains:

Login tests
Payment tests
Dashboard tests
Selenium Playground practice tests

You can assign the playground marker to all practice examples and execute only those tests whenever needed.

Automation Testing Example

Consider an enterprise automation framework.

Different teams create custom markers such as:

ui
api
smoke
regression
payment
mobile

Each team can execute only the tests relevant to their work.

Real-World Example

Custom Markers are commonly used in:

Selenium automation frameworks
Enterprise applications
Regression testing
Smoke testing
API automation
CI/CD pipelines
Cross-browser testing
Large QA projects

Advantages of Custom Markers

Organize tests logically.
Execute selected test groups.
Improve automation maintainability.
Reduce execution time.
Simplify CI/CD workflows.

Common Mistakes Beginners Make

Forgetting to Register the Marker

Unregistered markers may produce an Unknown Mark Warning.

Always register custom markers.

Using Inconsistent Marker Names

Use clear names such as:

smoke
regression
api
ui
playground

Avoid confusing or unnecessary marker names.

Creating Too Many Markers

Only create markers that have a clear purpose.

Too many custom markers make automation frameworks difficult to manage.

Forgetting the `-m` Option

Adding a marker alone does not change test execution.

Use:

pytest -m playground

to execute only the marked tests.

Best Practices

Use meaningful custom marker names.
Register every custom marker.
Group related tests together.
Keep marker names consistent across the project.
Use markers to improve test organization and CI/CD execution.

Conclusion

Custom Markers allow Selenium tests to be grouped according to project requirements. By assigning meaningful labels and registering them properly, PyTest can execute only the required subset of tests, making automation faster, cleaner, and easier to maintain. They are widely used in professional Selenium automation frameworks to organize large test suites efficiently.

Frequently Asked Questions (FAQs)