Python pytest Complete Guide | fixtures, parametrize & conftest.py Explained

pytest is the most widely used testing framework in Python — its simple syntax and powerful fixture system dramatically improve the efficiency of QA engineers’ test automation workflows.

In the test automation learning roadmap, pytest is one of the first frameworks to learn alongside Python itself. It’s almost always used in combination with tools like Playwright and Selenium, handling test execution, management, and report output all in one place. This article walks you through everything step by step — from installation to production-ready test structure.

What Is pytest? How It Differs from unittest

pytest is an open-source testing framework for Python. Compared to the standard library’s unittest, it requires less code, produces more readable error messages, and has a rich plugin ecosystem.

① Installation & Setup

Start by installing pytest. Python 3.8 or higher is required.

# Install pytest
pip install pytest

# Check version
pytest --version

# Install commonly used plugins all at once
pip install pytest pytest-html pytest-xdist

Example project structure:

my_project/
├── src/
│   └── calculator.py       # Source code under test
├── tests/
│   ├── conftest.py         # Shared fixtures
│   ├── test_calculator.py  # Test file
│   └── test_api.py
└── pytest.ini              # pytest configuration

② Writing Your First Tests

Start with a simple function to test.

# src/calculator.py

def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b

Now write the corresponding tests:

# tests/test_calculator.py
import pytest
from src.calculator import add, subtract, divide

# ✅ Basic test functions (must start with test_)
def test_add_normal():
    result = add(3, 5)
    assert result == 8

def test_subtract_normal():
    result = subtract(10, 4)
    assert result == 6

def test_divide_normal():
    result = divide(10, 2)
    assert result == 5.0

# ✅ Testing that an exception is raised
def test_divide_by_zero():
    with pytest.raises(ValueError) as exc_info:
        divide(10, 0)
    assert "Cannot divide by zero" in str(exc_info.value)

Running Tests

# Run all tests
pytest

# Run a specific file
pytest tests/test_calculator.py

# Verbose output (-v)
pytest -v

# Filter by test name (-k)
pytest -k "divide"

# Stop at first failure (-x)
pytest -x

Sample Output

========================= test session starts ==========================
platform win32 -- Python 3.11.0, pytest-7.4.0
collected 4 items

tests/test_calculator.py::test_add_normal        PASSED  [ 25%]
tests/test_calculator.py::test_subtract_normal   PASSED  [ 50%]
tests/test_calculator.py::test_divide_normal     PASSED  [ 75%]
tests/test_calculator.py::test_divide_by_zero    PASSED  [100%]

========================== 4 passed in 0.12s ===========================

③ How to Use Fixtures

Fixtures are the core feature of pytest for managing test setup, teardown, and shared data. They eliminate repetitive setup code and keep your tests clean.

# tests/test_user.py
import pytest

# --- Fixture definition ---
@pytest.fixture
def sample_user():
    """Fixture that returns test user data"""
    return {
        "id": 1,
        "name": "Test User",
        "email": "test@example.com",
        "role": "admin"
    }

@pytest.fixture
def empty_list():
    return []

# --- Tests using fixtures ---
def test_user_name(sample_user):
    assert sample_user["name"] == "Test User"

def test_user_role(sample_user):
    assert sample_user["role"] == "admin"

def test_empty_list_is_empty(empty_list):
    assert len(empty_list) == 0

Setup / Teardown with yield

Using yield, you can combine before- and after-test logic in a single fixture:

@pytest.fixture
def db_connection():
    # --- Setup (runs before test) ---
    print("\n[SETUP] Connecting to DB...")
    connection = {"status": "connected", "db": "test_db"}

    yield connection  # ← passed to the test here

    # --- Teardown (runs after test) ---
    print("\n[TEARDOWN] Closing DB connection")
    connection["status"] = "disconnected"

def test_db_is_connected(db_connection):
    assert db_connection["status"] == "connected"

Fixture Scope

# Example: launch browser only once per session (Playwright integration)
@pytest.fixture(scope="session")
def browser():
    from playwright.sync_api import sync_playwright
    with sync_playwright() as p:
        browser = p.chromium.launch()
        yield browser
        browser.close()

④ parametrize (Parameterized Tests)

@pytest.mark.parametrize lets you run the same test logic against multiple input patterns. It’s extremely useful for boundary value testing and covering both normal and error cases efficiently.

import pytest
from src.calculator import add, divide

# ✅ Basic parametrize
@pytest.mark.parametrize("a, b, expected", [
    (1, 2, 3),      # positive integers
    (-1, -2, -3),   # negative integers
    (0, 5, 5),      # includes zero
    (100, 200, 300) # large numbers
])
def test_add_parametrized(a, b, expected):
    assert add(a, b) == expected

# ✅ Multiple error cases in one test
@pytest.mark.parametrize("a, b", [
    (10, 0),
    (0, 0),
    (-5, 0),
])
def test_divide_by_zero_parametrized(a, b):
    with pytest.raises(ValueError):
        divide(a, b)

Each parameter set appears as an independent test in the output:

tests/test_calculator.py::test_add_parametrized[1-2-3]        PASSED
tests/test_calculator.py::test_add_parametrized[-1--2--3]     PASSED
tests/test_calculator.py::test_add_parametrized[0-5-5]        PASSED
tests/test_calculator.py::test_add_parametrized[100-200-300]  PASSED

⑤ Using conftest.py

conftest.py is a special file for sharing fixtures across multiple test files. Fixtures defined here are available to all tests without any import statement.

# tests/conftest.py

import pytest

@pytest.fixture(scope="session")
def base_url():
    """Base URL shared across all tests"""
    # Note: add http:// prefix in actual code (e.g. "http://localhost:8080")
    return "localhost:8080"

@pytest.fixture
def test_user_credentials():
    """Test login credentials"""
    return {
        "username": "standard_user",
        "password": "secret_sauce"
    }

@pytest.fixture(scope="session")
def api_headers():
    """Common headers for API tests"""
    return {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }

# tests/test_login.py
# ← No import needed! conftest.py fixtures are available automatically

def test_login_with_valid_credentials(test_user_credentials, base_url):
    username = test_user_credentials["username"]
    password = test_user_credentials["password"]
    # ... test logic

⑥ Using Marks

pytest’s mark feature makes it easy to skip tests or run them conditionally.

import pytest
import sys

# ✅ Skip a test
@pytest.mark.skip(reason="Not yet implemented")
def test_future_feature():
    assert some_future_function() == True

# ✅ Skip conditionally (e.g. skip on Windows)
@pytest.mark.skipif(sys.platform == "win32", reason="Not supported on Windows")
def test_linux_only():
    assert True

# ✅ Known failure (expected to fail)
@pytest.mark.xfail(reason="Waiting for bug fix: issue #123")
def test_known_bug():
    assert 1 + 1 == 3  # intentionally fails

# ✅ Custom marks (group tests for targeted runs)
@pytest.mark.smoke
def test_login_smoke():
    assert True

@pytest.mark.regression
def test_checkout_flow_regression():
    assert True

# Run only smoke tests
pytest -m smoke

# Run only regression tests
pytest -m regression

# Custom marks must be registered in pytest.ini
# pytest.ini:
# [pytest]
# markers =
#     smoke: Smoke tests
#     regression: Regression tests

⑦ pytest.ini Configuration

Place a pytest.ini file at the project root to customize pytest behavior globally:

# pytest.ini
[pytest]
# Test discovery path
testpaths = tests

# Default options (same as always passing -v --tb=short --html=... each time)
addopts = -v --tb=short --html=reports/report.html --self-contained-html

# Register custom marks (required to suppress warnings)
markers =
    smoke: Smoke tests (minimal sanity checks)
    regression: Regression tests
    slow: Tests that take a long time to run

# Log output settings
log_cli = true
log_cli_level = INFO

⑧ HTML Report Output

The pytest-html plugin outputs test results as an HTML file — very handy for sharing results in CI/CD or QA reports.

# Install
pip install pytest-html

# Generate HTML report
pytest --html=reports/report.html --self-contained-html

# Add to pytest.ini to generate automatically every time
# addopts = -v --html=reports/report.html --self-contained-html

Open reports/report.html in a browser to view test names, pass/fail status, execution time, and error details all in one place.

⑨ Playwright × pytest Integration Example

Combining pytest with Playwright lets you manage E2E tests in a clean, organized way. The easiest approach is to use the pytest-playwright plugin.

# Install
pip install pytest-playwright
playwright install chromium

# tests/test_saucedemo.py
import pytest
from playwright.sync_api import Page

# Just accept the page fixture provided by pytest-playwright
# Note: add http:// prefix in actual code (e.g. http://localhost:8080/)
def test_login_success(page: Page):
    page.goto("localhost:8080/")
    page.fill("#user-name", "standard_user")
    page.fill("#password", "secret_sauce")
    page.click("#login-button")
    assert page.url.endswith("/inventory.html")

def test_login_wrong_password(page: Page):
    page.goto("localhost:8080/")
    page.fill("#user-name", "standard_user")
    page.fill("#password", "wrong_password")
    page.click("#login-button")
    error_msg = page.locator(".error-message-container").text_content()
    assert "Epic sadface" in error_msg

# Run in headless mode (default)
pytest tests/test_saucedemo.py -v

# Run with visible browser (useful for debugging)
pytest tests/test_saucedemo.py --headed

# Specify browser
pytest tests/test_saucedemo.py --browser firefox

⑩ Useful Command Reference

FAQ

⚠️ 7 Common pytest Pitfalls

These are the most common stumbling blocks when starting out with pytest. Knowing them in advance can save you a lot of frustrating debugging time.

project/
├── src/
└── tests/
    ├── conftest.py   ← correct location (directly under tests/)
    └── test_api.py

# ❌ Wrong: running from inside the tests folder
cd tests
pytest

# ✅ Correct: always run from the project root
cd my_project
pytest

📋 Summary

Once you master pytest, you can build a solid test automation foundation in combination with Playwright and Selenium. Start simple with basic function tests, then level up step by step through fixtures, parametrize, and conftest.py.