pyproject.toml configuration in PyTest

Introduction

The pyproject.toml file helps you set up pytest settings in one place. It makes running tests easier and organized.

You want to change pytest options without typing them every time in the command line.

You want to tell pytest where to find your tests.

You want to add plugins or change how pytest shows test results.

You want to share test settings with your team in a simple file.

Syntax

PyTest

[tool.pytest.ini_options]
addopts = "--maxfail=3 --disable-warnings"
testpaths = ["tests"]
markers = ["slow: marks tests as slow"]

The section [tool.pytest.ini_options] is where pytest reads its settings from pyproject.toml.

Use simple key-value pairs to set options like addopts or testpaths.

Examples

This example runs pytest in verbose mode and looks for tests in the tests folder.

PyTest

[tool.pytest.ini_options]
addopts = "-v"
testpaths = ["tests"]

This example defines two custom markers to label tests as slow or fast.

PyTest

[tool.pytest.ini_options]
markers = ["slow: marks tests as slow", "fast: marks tests as fast"]

This example stops testing after 2 failures and shows shorter tracebacks.

PyTest

[tool.pytest.ini_options]
addopts = "--maxfail=2 --tb=short"

Sample Program

This setup runs tests verbosely and stops after the first failure. The tests include one passing, one failing, and one skipped test.

PyTest

# pyproject.toml content
[tool.pytest.ini_options]
addopts = "-v --maxfail=1"
testpaths = ["tests"]

# tests/test_sample.py
import pytest

def test_pass():
    assert 1 == 1

def test_fail():
    assert 1 == 2

def test_skip():
    pytest.skip("Skipping this test")

Important Notes

Make sure pyproject.toml is in your project root folder.

Use quotes around strings and square brackets for lists in TOML syntax.

After changing pyproject.toml, just run pytest without extra options.

Summary

pyproject.toml stores pytest settings in one file.

It helps run tests with your preferred options automatically.

You can define test folders, markers, and run options easily.

Practice

1. What is the main purpose of the pyproject.toml file in pytest?

easy

A. To store pytest configuration settings in one place

B. To write test functions directly

C. To install pytest dependencies

D. To generate test reports automatically

Solution

1. Step 1: Understand the role of pyproject.toml

   This file is used to keep configuration settings for pytest centralized.

2. Step 2: Differentiate from other files

   It does not contain test code or install dependencies but configures how pytest runs.

3. Final Answer:

   To store pytest configuration settings in one place -> Option A

4. Quick Check:

   Configuration file [OK]

Hint: Remember: pyproject.toml holds settings, not test code [OK]

Common Mistakes:

• Confusing configuration file with test code file
• Thinking it installs packages
• Assuming it generates reports automatically

2. Which of the following is the correct way to specify the test paths in pyproject.toml for pytest?

easy

A. [pytest]
testpaths = "tests"

B. [tool.pytest]
testpaths = ["tests"]

C. [tool.pytest]
test_paths = ["tests"]

D. [tool.pytest]
paths = "tests"

Solution

1. Step 1: Identify correct section header

   pytest settings go under [tool.pytest] in pyproject.toml.

2. Step 2: Check correct key and value format

   The key is testpaths and it expects a list of strings, e.g., ["tests"].

3. Final Answer:

   [tool.pytest] testpaths = ["tests"] -> Option B

4. Quick Check:

   Section and key names must be exact [OK]

Hint: Use [tool.pytest] and testpaths as a list [OK]

Common Mistakes:

• Using wrong section header like [pytest]
• Using wrong key names like test_paths
• Assigning string instead of list for testpaths

3. Given this pyproject.toml snippet:

[tool.pytest]
markers = ["slow: marks tests as slow"]
addopts = "-v --maxfail=2"

What happens when you run pytest?

medium

A. Tests run verbosely but do not stop on failures; 'slow' marker ignored

B. Tests run silently and stop after 2 failures; 'slow' marker ignored

C. Tests run verbosely and stop after 2 failures; 'slow' marker is recognized

D. Tests run silently and continue on failures; 'slow' marker recognized

Solution

1. Step 1: Understand addopts settings

   The -v flag makes output verbose; --maxfail=2 stops tests after 2 failures.

2. Step 2: Understand markers setting

   Defining slow marker means pytest recognizes it and can filter or mark tests accordingly.

3. Final Answer:

   Tests run verbosely and stop after 2 failures; 'slow' marker is recognized -> Option C

4. Quick Check:

   Verbose + maxfail + marker recognized [OK]

Hint: addopts controls run options; markers define test tags [OK]

Common Mistakes:

• Ignoring that -v means verbose output
• Not knowing --maxfail stops after failures
• Assuming markers are ignored without explicit use

4. You wrote this in pyproject.toml:

[tool.pytest]
markers = "slow: marks slow tests"
addopts = -v

What is the problem when running pytest?

medium

A. addopts ignored but markers work

B. No error; configuration works fine

C. Markers ignored but addopts works

D. Syntax error because markers should be a list, and addopts needs quotes

Solution

1. Step 1: Check markers format

   Markers must be a list of strings, but here it is a single string without brackets.

2. Step 2: Check addopts format

   addopts value must be a string in quotes; here it is unquoted, causing syntax error.

3. Final Answer:

   Syntax error because markers should be a list, and addopts needs quotes -> Option D

4. Quick Check:

   Lists need brackets; strings need quotes [OK]

Hint: Always use brackets for lists and quotes for strings in TOML [OK]

Common Mistakes:

• Writing markers as a plain string instead of list
• Forgetting quotes around string values
• Assuming pytest ignores bad config silently

5. You want pytest to automatically run tests only in the integration_tests folder and recognize a custom marker api. Which pyproject.toml configuration is correct?

hard

A. [tool.pytest]
testpaths = ["integration_tests"]
markers = ["api: marks API tests"]

B. [tool.pytest]
testpaths = "integration_tests"
markers = "api: marks API tests"

C. [pytest]
testpaths = ["integration_tests"]
markers = ["api"]

D. [tool.pytest]
paths = ["integration_tests"]
markers = ["api: marks API tests"]

Solution

1. Step 1: Set correct testpaths key and value

   Use testpaths as a list under [tool.pytest] to specify test folders.

2. Step 2: Define markers properly

   Markers must be a list of strings describing each marker with a colon and description.

3. Final Answer:

   [tool.pytest] testpaths = ["integration_tests"] markers = ["api: marks API tests"] -> Option A

4. Quick Check:

   Correct keys, list format, and section [OK]

Hint: Use [tool.pytest], testpaths list, and markers list with descriptions [OK]

Common Mistakes:

• Using string instead of list for testpaths
• Wrong section header like [pytest]
• Markers missing description or wrong format