pytest

name	pytest
description	Comprehensive pytest testing framework skill for Python. Use when working with pytest tests, fixtures, parametrization, markers, assertions, configuration, plugins, or test discovery. Covers pytest 9.x with full API reference, how-to guides, best practices, and examples for writing, running, and debugging Python tests.

pytest Testing Framework

pytest is a mature, full-featured Python testing framework that makes it easy to write small, readable tests that can scale to support complex functional testing.

Quick Start

Installation

pip install -U pytest
pytest --version

Basic Test

# test_sample.py
def inc(x):
    return x + 1

def test_answer():
    assert inc(3) == 5

Run with pytest - it auto-discovers test_*.py and *_test.py files.

Test Discovery Rules

• Files: test_*.py or *_test.py
• Functions: test_ prefix outside classes
• Classes: Test prefix (no __init__)
• Methods: test_ prefix in Test classes

Core Concepts

Fixtures

Fixtures provide fixed baseline for tests:

import pytest

@pytest.fixture
def smtp_connection():
    return smtplib.SMTP("smtp.gmail.com", 587, timeout=5)

def test_ehlo(smtp_connection):
    response, msg = smtp_connection.ehlo()
    assert response == 250

Scopes: function (default), class, module, package, session

Parametrization

Run same test with multiple inputs:

@pytest.mark.parametrize("input,expected", [
    ("3+5", 8),
    ("2+4", 6),
    pytest.param("6*9", 42, marks=pytest.mark.xfail),
])
def test_eval(input, expected):
    assert eval(input) == expected

Markers

@pytest.mark.skip(reason="not implemented")
@pytest.mark.skipif(sys.platform == "win32", reason="linux only")
@pytest.mark.xfail(reason="known bug")
@pytest.mark.slow  # custom marker
def test_something():
    pass

Run by marker: pytest -m slow

Assertions

# Basic assert with introspection
assert func(3) == 5

# Exception testing
with pytest.raises(ValueError, match="invalid"):
    raise ValueError("invalid input")

# Floating point comparison
assert 0.1 + 0.2 == pytest.approx(0.3)

# Warnings
with pytest.warns(UserWarning):
    warnings.warn("hello", UserWarning)

CLI Reference

pytest                           # run all tests
pytest test_mod.py               # specific file
pytest tests/                    # directory
pytest -k "MyClass and not method"  # keyword filter
pytest -m slow                   # by marker
pytest -x                        # stop on first failure
pytest -v                        # verbose
pytest -s                        # show stdout
pytest --tb=short                # shorter traceback
pytest --fixtures                # list fixtures
pytest --collect-only            # show tests without running
pytest -n 4                      # parallel (needs pytest-xdist)

Documentation Index

Getting Started

• getting-started.md - Installation, first test, grouping tests, temporary directories

How-To Guides

Testing Basics:

• how-to/usage.md - Invoking pytest, selecting tests, CLI options
• how-to/assert.md - Assertions, exceptions, warnings, approx comparisons
• how-to/fixtures.md - Complete fixture guide: scopes, teardown, parametrization, factories
• how-to/parametrize.md - Parametrizing tests and fixtures
• how-to/mark.md - Custom markers, registering marks
• how-to/skipping.md - skip, skipif, xfail markers

Test Organization:

• how-to/tmp_path.md - Temporary directories and files
• how-to/monkeypatch.md - Monkeypatching for testing
• how-to/cache.md - Caching values across test runs
• how-to/doctest.md - Running doctests with pytest

Output & Capture:

• how-to/capture-stdout-stderr.md - Capturing output
• how-to/capture-warnings.md - Capturing warnings
• how-to/logging.md - Logging during tests
• how-to/output.md - Managing test output
• how-to/failures.md - Handling test failures

Integration:

• how-to/unittest.md - Running unittest tests
• how-to/existingtestsuite.md - Migrating existing test suites
• how-to/xunit_setup.md - xUnit-style setup/teardown
• how-to/subtests.md - Subtest support

Plugins:

• how-to/plugins.md - Using pytest plugins
• how-to/writing_plugins.md - Writing plugins
• how-to/writing_hook_functions.md - Hook functions

Other:

• how-to/bash-completion.md - Bash completion setup

Reference

• reference/reference.md - Complete API reference
• reference/fixtures.md - Built-in fixtures reference
• reference/customize.md - Configuration and customization
• reference/exit-codes.md - Exit codes reference
• reference/plugin_list.md - Plugin list

Explanation

• explanation/fixtures.md - Fixture concepts explained
• explanation/anatomy.md - Anatomy of a test
• explanation/goodpractices.md - Best practices, project layout, import modes
• explanation/flaky.md - Dealing with flaky tests
• explanation/ci.md - CI integration
• explanation/pythonpath.md - Python path handling
• explanation/types.md - Type annotations in pytest

Examples

• example/simple.md - Simple test examples
• example/parametrize.md - Parametrization examples
• example/markers.md - Marker examples
• example/pythoncollection.md - Collection examples
• example/customdirectory.md - Custom directory layouts
• example/nonpython.md - Non-Python tests
• example/reportingdemo.md - Reporting demonstration
• example/special.md - Special use cases

Common Patterns

conftest.py

Share fixtures across test files:

# tests/conftest.py
import pytest

@pytest.fixture
def database():
    db = Database()
    yield db
    db.close()

Yield Fixture (Teardown)

@pytest.fixture
def resource():
    r = acquire_resource()
    yield r
    release_resource(r)  # teardown

Fixture Factories

@pytest.fixture
def make_customer():
    created = []
    def _make(name):
        c = Customer(name)
        created.append(c)
        return c
    yield _make
    for c in created:
        c.delete()

Autouse Fixtures

@pytest.fixture(autouse=True)
def clean_db(db):
    yield
    db.rollback()

Configuration

pyproject.toml

[pytest]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = "-v --tb=short"
markers = [
    "slow: marks tests as slow",
    "integration: integration tests",
]

pytest.ini

[pytest]
testpaths = tests
addopts = -v

Official Resources

• Documentation: https://docs.pytest.org/
• PyPI: https://pypi.org/project/pytest/
• GitHub: https://github.com/pytest-dev/pytest/