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.