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.

Practice

1. What is the main purpose of the testpaths setting in a pytest.ini file?

easy

A. To configure the test report format

B. To specify which folders pytest should look in for test files

C. To set the timeout for each test

D. To define the order in which tests run

Solution

1. Step 1: Understand the role of testpaths

   The testpaths setting tells pytest where to find test files by listing directories.

2. Step 2: Compare with other options

   Other options like test order, timeout, or report format are configured differently, not with testpaths.

3. Final Answer:

   To specify which folders pytest should look in for test files -> Option B

4. Quick Check:

   testpaths = test folders [OK]

Hint: testpaths lists folders to find tests [OK]

Common Mistakes:

• Confusing testpaths with test order settings
• Thinking testpaths sets test timeouts
• Assuming testpaths changes report style

2. Which of the following is the correct syntax to set testpaths in pytest.ini to look in folders tests and integration?

easy

A. [pytest]
testpaths = tests integration

B. [pytest]
testpaths = ['tests', 'integration']

C. [pytest]
testpaths = tests,integration

D. [pytest]
testpaths = "tests integration"

Solution

1. Step 1: Check pytest.ini syntax for testpaths

   In pytest.ini, testpaths lists folders separated by spaces without quotes or commas.

2. Step 2: Validate each option

   [pytest] testpaths = tests integration uses space-separated folder names correctly. Options A and D use quotes or brackets incorrectly. [pytest] testpaths = tests,integration uses commas which pytest does not accept here.

3. Final Answer:

   [pytest] testpaths = tests integration -> Option A

4. Quick Check:

   Space-separated folder names, no quotes [OK]

Hint: Use space-separated folder names without quotes [OK]

Common Mistakes:

• Using commas instead of spaces
• Adding quotes or brackets around folder names
• Placing testpaths outside [pytest] section

3. Given this pytest.ini content:

[pytest]
testpaths = tests integration

And this folder structure:

project/
  tests/
    test_alpha.py
  integration/
    test_beta.py
  docs/
    test_docs.py

Which test files will pytest discover and run?

medium

A. Only test_docs.py

B. test_alpha.py, test_beta.py, and test_docs.py

C. Only test_alpha.py

D. test_alpha.py and test_beta.py only

Solution

1. Step 1: Identify folders listed in testpaths

   The testpaths setting includes tests and integration folders only.

2. Step 2: Match test files in those folders

   Files test_alpha.py in tests and test_beta.py in integration will be found. test_docs.py is in docs, which is not listed.

3. Final Answer:

   test_alpha.py and test_beta.py only -> Option D

4. Quick Check:

   Only testpaths folders' tests run [OK]

Hint: Only tests in testpaths folders run [OK]

Common Mistakes:

• Assuming all test files in project run
• Including tests from folders not in testpaths
• Confusing folder names with test file names

4. You set testpaths = tests in pytest.ini but pytest still discovers tests in other folders. What is the most likely cause?

medium

A. There is another config file overriding testpaths

B. You forgot to restart pytest after editing pytest.ini

C. testpaths only filters test names, not folders

D. pytest ignores testpaths by default

Solution

1. Step 1: Understand pytest config precedence

   pytest can read multiple config files like tox.ini or setup.cfg that may override pytest.ini.

2. Step 2: Check for conflicting configs

   If tests outside tests run, likely another config file sets different testpaths or disables it.

3. Final Answer:

   There is another config file overriding testpaths -> Option A

4. Quick Check:

   Multiple configs can override testpaths [OK]

Hint: Check for multiple config files overriding settings [OK]

Common Mistakes:

• Assuming pytest.ini changes apply without reload
• Thinking testpaths filters test names only
• Believing pytest ignores testpaths by default

5. You want pytest to only run tests in unit_tests and api_tests folders, but exclude api_tests/slow. How can you configure pytest.ini using testpaths and other settings to achieve this?

hard

A. [pytest]
testpaths = unit_tests
norecursedirs = api_tests/slow

B. [pytest]
testpaths = unit_tests api_tests/slow
norecursedirs = api_tests

C. [pytest]
testpaths = unit_tests api_tests
norecursedirs = api_tests/slow

D. [pytest]
testpaths = unit_tests api_tests
ignore = api_tests/slow

Solution

1. Step 1: Use testpaths to include desired folders

   Set testpaths = unit_tests api_tests to include both folders.

2. Step 2: Exclude the slow subfolder with norecursedirs

   Use norecursedirs = api_tests/slow to prevent pytest from searching inside that subfolder.

3. Step 3: Verify other options are incorrect

   [pytest] testpaths = unit_tests api_tests/slow norecursedirs = api_tests includes the slow folder in testpaths, which is wrong. [pytest] testpaths = unit_tests norecursedirs = api_tests/slow excludes api_tests entirely. [pytest] testpaths = unit_tests api_tests ignore = api_tests/slow uses ignore which is not a valid pytest.ini setting.

4. Final Answer:

   [pytest] testpaths = unit_tests api_tests norecursedirs = api_tests/slow -> Option C

5. Quick Check:

   Include folders with testpaths, exclude subfolders with norecursedirs [OK]

Hint: Use testpaths to include, norecursedirs to exclude subfolders [OK]

Common Mistakes:

• Including excluded folders in testpaths
• Using invalid config keys like ignore
• Excluding whole folders instead of subfolders