Grouping related tests in PyTest - Deep Dive

Overview - Grouping related tests

What is it?

Grouping related tests means organizing tests that check similar features or behaviors together. In pytest, this helps keep tests tidy and easier to run selectively. Instead of running all tests every time, you can run just one group. This makes testing faster and clearer.

Why it matters

Without grouping, tests become a big messy list that is hard to manage and slow to run. Developers waste time finding tests or running unnecessary ones. Grouping related tests saves time, reduces errors, and helps teams understand what is tested. It makes fixing bugs and adding features safer and faster.

Where it fits

Before learning grouping, you should know how to write simple pytest tests and run them. After grouping, you can learn about test fixtures, parameterization, and test markers to make tests even more powerful and flexible.

Mental Model

Core Idea

Grouping related tests bundles similar checks so you can run, understand, and maintain them easily as one unit.

Think of it like...

It's like putting all your socks of the same color in one drawer. When you want a pair, you open just that drawer instead of searching through the whole closet.

┌───────────────┐
│ Test Suite    │
│ ┌───────────┐ │
│ │ Group A   │ │
│ │ ┌───────┐ │ │
│ │ │Test 1 │ │ │
│ │ │Test 2 │ │ │
│ │ └───────┘ │ │
│ └───────────┘ │
│ ┌───────────┐ │
│ │ Group B   │ │
│ │ ┌───────┐ │ │
│ │ │Test 3 │ │ │
│ │ │Test 4 │ │ │
│ │ └───────┘ │ │
│ └───────────┘ │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Writing simple pytest tests

Concept: Learn how to write basic test functions using pytest.

In pytest, a test is a function whose name starts with 'test_'. For example: def test_addition(): assert 1 + 1 == 2 You run tests by typing 'pytest' in the terminal. Pytest finds all functions starting with 'test_' and runs them.

Result

Pytest runs the test and shows 'PASSED' if the assertion is true.

Understanding how pytest discovers and runs tests is the base for grouping them later.

2

Foundation

Running multiple tests together

Concept: Learn how pytest runs all tests in a file or folder by default.

If you have multiple test functions in one file, pytest runs them all: def test_add(): assert 2 + 2 == 4 def test_subtract(): assert 5 - 3 == 2 Run 'pytest' and both tests run automatically.

Result

Both tests run and pass, shown in the terminal output.

Knowing pytest runs all tests helps you see why grouping is useful to run only some tests.

3

Intermediate

Using test classes to group tests

🤔Before reading on: do you think test classes in pytest require inheritance from a special base class? Commit to your answer.

Concept: Test classes group related test functions inside a class without needing inheritance.

You can group tests by putting them inside a class whose name starts with 'Test': class TestMathOperations: def test_add(self): assert 1 + 1 == 2 def test_subtract(self): assert 5 - 3 == 2 Pytest runs all methods starting with 'test_' inside this class.

Result

Pytest runs both tests inside the class as a group.

Understanding that classes group tests logically without extra setup helps organize tests by feature or module.

4

Intermediate

Marking tests with pytest markers

🤔Before reading on: do you think pytest markers change test code behavior or just help select tests? Commit to your answer.

Concept: Markers label tests with tags to select or skip groups during runs.

You can add markers to tests to group them: import pytest @pytest.mark.login def test_login_success(): assert True @pytest.mark.login def test_login_fail(): assert False Run only login tests with 'pytest -m login'.

Result

Only tests marked with 'login' run when using the marker option.

Knowing markers let you run or skip groups without changing test code structure improves test flexibility.

5

Intermediate

Organizing tests in folders and files

Concept: Tests can be grouped by placing them in folders and files named by feature or module.

Create folders like 'tests/login/' and put related test files inside: tests/login/test_login.py tests/payment/test_payment.py Run tests in a folder with 'pytest tests/login/'.

Result

Only tests in the specified folder run, grouping tests by feature.

Using folders and files to group tests matches how code is organized, making tests easier to find and run.

6

Advanced

Combining markers and classes for flexible grouping

🤔Before reading on: do you think combining markers and classes can run overlapping test groups? Commit to your answer.

Concept: You can combine markers and classes to create flexible, overlapping test groups.

Example: import pytest @pytest.mark.api class TestAPI: def test_get(self): assert True @pytest.mark.slow def test_post(self): assert True Run all API tests: 'pytest -m api' Run slow tests: 'pytest -m slow' Run API but not slow: 'pytest -m "api and not slow"'

Result

You can run tests by combined groups using marker expressions.

Understanding marker expressions lets you run exactly the tests you want, saving time and focusing on relevant tests.

7

Expert

Custom markers and pytest.ini for scalable grouping

🤔Before reading on: do you think pytest requires marker registration to avoid warnings? Commit to your answer.

Concept: Custom markers should be registered in pytest.ini to avoid warnings and document test groups.

Create pytest.ini: [pytest] markers = login: tests related to login api: tests for API endpoints Use markers in tests as before. Pytest now knows these markers and shows no warnings.

Result

Pytest runs tests with custom markers cleanly and documents them for the team.

Knowing to register markers prevents confusion and helps teams maintain clear, scalable test groupings.

Under the Hood

Pytest discovers tests by scanning files and functions matching naming patterns. Grouping via classes or markers adds metadata or structure that pytest uses to filter tests before running. Markers are stored as attributes on test functions or classes. When running, pytest evaluates marker expressions to select tests. Test classes are simple Python classes; pytest collects methods starting with 'test_'.

Why designed this way?

Pytest was designed to be simple and flexible. Using Python classes for grouping leverages existing language features without extra syntax. Markers provide a lightweight tagging system to select tests dynamically. This avoids complex configuration files or rigid test hierarchies, making pytest easy to extend and adapt.

Test Discovery Flow:

┌───────────────┐
│ Test Files    │
│ (test_*.py)   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Test Functions│
│ (test_*)      │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Grouping Info │
│ Classes,     │
│ Markers      │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Test Selection│
│ (filter by   │
│ markers/class)│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Test Execution│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do test classes in pytest need to inherit from unittest.TestCase? Commit to yes or no.

Common Belief: Test classes must inherit from unittest.TestCase to work in pytest.

Reality: Pytest test classes do NOT need to inherit from any base class; any class named starting with 'Test' works.

Why it matters: Believing this limits pytest use and confuses beginners who try to add inheritance unnecessarily.

Quick: Does marking a test with a marker change how the test runs internally? Commit to yes or no.

Common Belief: Markers change test behavior or execution logic.

Reality: Markers only label tests for selection or skipping; they do not alter test code execution unless explicitly programmed.

Why it matters: Misunderstanding this leads to expecting side effects from markers and misusing them.

Quick: Can you run tests by folder without any special configuration? Commit to yes or no.

Common Belief: You must configure pytest to run tests by folder.

Reality: Pytest can run tests by folder out of the box by specifying the folder path.

Why it matters: Thinking configuration is needed wastes time and complicates simple test runs.

Quick: Does combining markers with logical expressions require complex code? Commit to yes or no.

Common Belief: Combining markers with 'and', 'or', 'not' needs custom code.

Reality: Pytest supports marker expressions natively in the command line for flexible test selection.

Why it matters: Not knowing this limits efficient test runs and leads to running unnecessary tests.

Expert Zone

1

Markers can be applied to test classes, modules, or individual functions, allowing hierarchical grouping.

2

Using pytest hooks, you can dynamically modify test groups or markers at runtime for advanced test selection.

3

Marker expressions support parentheses and complex boolean logic, enabling precise test filtering without code changes.

When NOT to use

Grouping tests by classes is not ideal when tests need to be fully independent or when using parameterized tests extensively; in such cases, markers or folder organization are better. Avoid overusing markers as too many can confuse test selection; use clear folder structures instead.

Production Patterns

In large projects, teams use markers to tag tests by feature, priority, or speed (e.g., 'smoke', 'slow'). CI pipelines run fast groups on every commit and full groups nightly. Test classes group related tests by module. pytest.ini files document markers and configure default test groups.

Connections

Modular programming

Grouping tests mirrors grouping code into modules and classes.

Understanding code modularity helps grasp why grouping tests by classes or folders improves maintainability.

Tagging in project management

Markers in pytest are like tags in task trackers to filter and organize work items.

Knowing tagging systems in other fields clarifies how markers help select and manage test subsets.

Library classification in a bookstore

Grouping tests is like organizing books by genre and author for easy finding.

Seeing grouping as a classification system helps appreciate its role in managing large collections efficiently.

Common Pitfalls

#1 Putting unrelated tests in one class to group them.

Wrong approach:

class TestMixed:
def test_login(self):
assert True
def test_payment(self):
assert True

Correct approach:

class TestLogin:
def test_login(self):
assert True

class TestPayment:
def test_payment(self):
assert True

Root cause:

Misunderstanding that test classes should group related tests, not just collect any tests.

#2 Using markers without registering them in pytest.ini causing warnings.

Wrong approach:

import pytest

@pytest.mark.slow
def test_something():
assert True

Correct approach:

[pytest]
markers =
slow: marks tests as slow

import pytest

@pytest.mark.slow
def test_something():
assert True

Root cause:

Not knowing pytest requires marker registration to avoid warnings and document usage.

#3 Running tests by folder but specifying wrong path causing no tests to run.

Wrong approach:

pytest tests/login_test.py # file does not exist or wrong path

Correct approach:

pytest tests/login/ # correct folder path

Root cause:

Confusing file and folder paths or typos in command line.

Key Takeaways

Grouping related tests helps organize and run tests efficiently by feature or behavior.

Pytest supports grouping via test classes, markers, and folder structures without extra code complexity.

Markers are flexible tags that let you select or skip groups of tests dynamically during runs.

Registering custom markers in pytest.ini avoids warnings and documents test groups for teams.

Combining grouping methods and marker expressions enables precise control over which tests run, saving time and improving focus.