Why pyproject.toml configuration in PyTest? - Purpose & Use Cases

The Big Idea

Discover how one simple file can save you from test chaos and confusion!

The Scenario

Imagine you have many test settings scattered in different files or command lines. Every time you run tests, you must remember and type all options manually.

The Problem

This manual way is slow and easy to forget. You might run tests with wrong settings or waste time fixing simple mistakes. It feels like juggling many balls at once.

The Solution

Using pyproject.toml lets you keep all test settings in one neat place. Pytest reads this file automatically, so you never forget or mistype options again.

Before vs After

✗ Before

pytest tests/ --maxfail=2 --disable-warnings

✓ After

[tool.pytest.ini_options]
maxfail = 2
addopts = "--disable-warnings"

What It Enables

It makes running tests simple, consistent, and error-free every time.

Real Life Example

A developer shares the pyproject.toml file with the team. Everyone runs tests the same way without confusion or extra instructions.

Key Takeaways

Manual test options are hard to manage and easy to forget.

pyproject.toml centralizes pytest settings for consistency.

This saves time and reduces errors in testing.

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