pyproject.toml configuration in PyTest - Framework Patterns

Framework Mode - pyproject.toml configuration

Folder Structure

tests/
├── test_example.py
├── conftest.py
src/
├── app_module.py
pyproject.toml
README.md

Test Framework Layers

• Tests: Located in tests/ folder, contains test scripts like test_example.py.
• Fixtures & Hooks: In conftest.py, reusable setup and teardown code for tests.
• Application Code: In src/, the main code under test.
• Configuration: pyproject.toml holds pytest settings and dependencies.
• Utilities: Helper functions or modules can be added under tests/utils/ or src/utils/.

Configuration Patterns

The pyproject.toml file centralizes pytest configuration and dependencies.

[tool.pytest.ini_options]
minversion = "7.0"
addopts = "-ra -q"
testpaths = ["tests"]
markers = [
  "smoke: quick smoke tests",
  "slow: slow running tests"
]

[tool.poetry.dependencies]
python = ">=3.12"

[tool.poetry.dev-dependencies]
pytest = "^7.0"
pytest-cov = "^4.0"

This setup defines minimum pytest version, test folder, custom markers, and dependencies.

Use environment variables or separate config files for sensitive data like credentials.

Test Reporting and CI/CD Integration

• Use pytest plugins like pytest-cov for coverage reports.
• Configure reports in pyproject.toml or via CLI options.
• Integrate with CI/CD pipelines (GitHub Actions, GitLab CI) to run tests automatically on code changes.
• Publish test results and coverage badges for team visibility.

Best Practices

• Centralize configuration: Keep pytest settings in pyproject.toml for easy maintenance.
• Use markers: Define test categories to run subsets easily.
• Version control dependencies: Manage pytest and plugins versions explicitly.
• Separate sensitive data: Avoid hardcoding credentials in config files.
• Keep folder structure clean: Separate tests, source code, and utilities clearly.

Self Check

Where in this framework structure would you add a new fixture to initialize a database connection for tests?

Key Result

Use pyproject.toml to centralize pytest configuration, dependencies, and test settings for a clean, maintainable test framework.

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