Testpaths configuration in PyTest - Deep Dive

Overview - Testpaths configuration

What is it?

Testpaths configuration in pytest is a way to tell pytest where to look for test files when running tests. Instead of searching the entire project, you can specify certain folders or paths to focus on. This helps pytest find tests faster and avoid running unwanted files. It is set in the pytest configuration file, usually named pytest.ini.

Why it matters

Without testpaths configuration, pytest searches the whole project directory for tests, which can slow down test runs and include irrelevant files. This wastes time and can cause confusion if non-test files are accidentally run. By configuring testpaths, you control test discovery, making testing faster and more reliable, especially in large projects.

Where it fits

Before learning testpaths, you should understand basic pytest test discovery and how pytest finds and runs tests. After mastering testpaths, you can explore other pytest configuration options like markers, addopts, and test selection strategies to further customize test runs.

Mental Model

Core Idea

Testpaths configuration tells pytest exactly where to look for tests, focusing discovery and speeding up test runs.

Think of it like...

It's like giving a treasure hunter a map with marked spots instead of letting them search the entire island randomly.

Project Root
├── src
│   └── code.py
├── tests
│   ├── unit
│   │   └── test_math.py
│   └── integration
│       └── test_api.py
└── pytest.ini (testpaths = tests/unit tests/integration)

Build-Up - 6 Steps

1

Foundation

Understanding pytest test discovery

Concept: pytest automatically finds test files and functions based on naming conventions.

pytest looks for files named test_*.py or *_test.py and inside them functions starting with test_. It searches the current directory and subdirectories by default.

Result

pytest collects all matching test files and functions to run.

Knowing how pytest finds tests helps you understand why controlling search paths can improve efficiency.

2

Foundation

What is pytest.ini configuration file

Concept: pytest.ini is a file where you can set options to customize pytest behavior globally for your project.

You create a pytest.ini file in your project root and add sections like [pytest] with key=value pairs to configure pytest.

Result

pytest reads this file automatically and applies the settings when running tests.

Using pytest.ini centralizes configuration, making test runs consistent and easier to manage.

3

Intermediate

Introducing testpaths option

🤔Before reading on: do you think testpaths limits test discovery to only specified folders or just prioritizes them? Commit to your answer.

Concept: testpaths tells pytest to only look inside specified folders or paths for test files.

In pytest.ini, under [pytest], add testpaths = folder1 folder2 to restrict test discovery to those folders only.

Result

pytest ignores other folders outside testpaths, speeding up discovery and avoiding unwanted tests.

Understanding testpaths lets you control test scope, which is crucial for large projects with many files.

4

Intermediate

Configuring multiple testpaths

🤔Before reading on: can testpaths accept multiple folders separated by spaces or only one? Commit to your answer.

Concept: You can specify multiple folders in testpaths separated by spaces to include several test locations.

Example pytest.ini: [pytest] testpaths = tests/unit tests/integration This tells pytest to look in both folders.

Result

pytest collects tests from all listed folders, ignoring others.

Knowing you can list multiple paths gives flexibility to organize tests in different places.

5

Advanced

How testpaths interacts with other discovery options

🤔Before reading on: does testpaths override or combine with python_files and norecursedirs? Commit to your answer.

Concept: testpaths limits folders searched, while python_files controls file name patterns, and norecursedirs excludes folders; they work together.

pytest first limits search to testpaths folders, then applies python_files pattern to find test files, and skips norecursedirs folders inside testpaths.

Result

This layered filtering ensures precise control over which tests run.

Understanding this interaction helps avoid confusion when tests are missing or extra tests run.

6

Expert

Unexpected effects of testpaths on test discovery

🤔Before reading on: do you think testpaths affects test collection order or only discovery scope? Commit to your answer.

Concept: testpaths changes discovery scope but can also affect test collection order and test session behavior in subtle ways.

Because testpaths restricts folders, pytest collects tests in the order of listed paths, which may affect fixtures or test dependencies relying on order. Also, if testpaths excludes some tests, coverage reports or plugins may behave differently.

Result

Tests run faster but may have different order or coverage results than without testpaths.

Knowing these subtle effects prevents surprises in complex test suites and helps maintain test reliability.

Under the Hood

pytest reads the pytest.ini file at startup and parses the testpaths option. During test collection, it uses testpaths as root directories to recursively search for test files matching naming patterns. It skips folders not listed in testpaths, reducing filesystem traversal and speeding up collection. Internally, testpaths acts as a filter on the filesystem walker before applying file name filters.

Why designed this way?

pytest was designed to be flexible and fast. Allowing users to specify testpaths avoids scanning irrelevant files, which is costly in large projects. This design balances ease of use (automatic discovery) with control (configurable paths). Alternatives like hardcoding paths in commands were less maintainable.

pytest.ini
  └─ testpaths = [folder1, folder2]
       ↓
Filesystem walker
  ├─ Scans only folder1
  ├─ Scans only folder2
  └─ Skips all other folders
       ↓
Apply python_files pattern
       ↓
Collect test files
       ↓
Run tests

Myth Busters - 4 Common Misconceptions

Quick: Does testpaths include subfolders of specified folders automatically? Commit yes or no.

Common Belief: testpaths only includes the exact folders listed, not their subfolders.

Reality: testpaths includes the listed folders and all their subfolders recursively during test discovery.

Why it matters: If you think subfolders are excluded, you might miss tests nested deeper, causing incomplete test runs.

Quick: Does testpaths override python_files patterns or combine with them? Commit your answer.

Common Belief: testpaths overrides python_files patterns, so python_files settings are ignored when testpaths is set.

Reality: testpaths limits folders searched, but python_files still filters which files inside those folders are considered tests.

Why it matters: Misunderstanding this can lead to tests being missed or unexpected files being run.

Quick: Does setting testpaths speed up test runs by itself? Commit yes or no.

Common Belief: Just setting testpaths always makes tests run faster.

Reality: testpaths speeds up discovery by limiting search scope, but actual test run time depends on test code and fixtures, so speed gains vary.

Why it matters: Expecting huge speedups only from testpaths can lead to ignoring other performance improvements.

Quick: Can testpaths be set via command line options? Commit yes or no.

Common Belief: You can set testpaths directly via pytest command line options.

Reality: testpaths is a configuration file option and cannot be set directly on the command line; you specify folders on the command line to run tests there.

Why it matters: Confusing this leads to failed attempts to control discovery dynamically via command line.

Expert Zone

1

testpaths affects test collection order, which can impact tests relying on order-dependent fixtures or setup.

2

When using testpaths with plugins like coverage or xdist, the limited discovery scope can change plugin behavior subtly.

3

If testpaths excludes folders with conftest.py files, pytest may miss important fixtures or hooks, causing test failures.

When NOT to use

Avoid using testpaths when you want to run tests across the entire project dynamically or when tests are scattered unpredictably. Instead, use command line folder arguments or pytest markers to select tests.

Production Patterns

In large projects, teams configure testpaths to separate unit, integration, and functional tests into different folders. CI pipelines run tests by specifying testpaths to run only relevant tests per pipeline stage, improving speed and clarity.

Connections

Test markers in pytest

Builds-on

Understanding testpaths helps focus test discovery, while markers help select tests by category; combining both gives precise test control.

Filesystem indexing in operating systems

Same pattern

Both testpaths and filesystem indexing optimize search by limiting scope, improving speed and efficiency.

Library classification in a bookstore

Builds-on

Just as testpaths narrows where to find tests, classifying books by genre narrows where to find certain books, making retrieval faster.

Common Pitfalls

#1 Forgetting to include all test folders in testpaths

Wrong approach:

[pytest]
testpaths = tests/unit

Correct approach:

[pytest]
testpaths = tests/unit tests/integration

Root cause:

Assuming testpaths includes all test folders by default, leading to missing tests in other folders.

#2 Setting testpaths but naming test files incorrectly

Wrong approach:

[pytest]
testpaths = tests

# test file named math_tests.py instead of test_math.py

Correct approach:

[pytest]
testpaths = tests

# test file named test_math.py

Root cause:

Not matching pytest's default test file naming patterns, causing tests to be ignored.

#3 Expecting testpaths to be settable via command line

Wrong approach:

pytest --testpaths=tests/unit

Correct approach:

pytest tests/unit

Root cause:

Misunderstanding that testpaths is a config file option, not a command line argument.

Key Takeaways

Testpaths configuration tells pytest exactly which folders to search for tests, improving discovery speed and focus.

It works together with other pytest options like python_files and norecursedirs to finely control test collection.

Misconfiguring testpaths can cause tests to be missed or unexpected tests to run, so careful setup is important.

Testpaths is set in pytest.ini and cannot be changed via command line, distinguishing it from folder arguments.

Understanding testpaths helps manage large test suites efficiently and avoid common pitfalls in test discovery.