The Complete Guide to pytest Fixtures — scope, yield, and autouse in Practice

Plenty of engineers have used pytest fixtures without ever nailing down when to use which scope, or when yield actually matters. This article is for anyone who already knows the basics of fixtures and wants to go deeper — scope (function/class/module/session), setup and teardown with yield fixtures, autouse, composing fixtures together, and the factory pattern — all grounded in situations that come up in real projects.

If your understanding of fixtures stops at “something that sets things up before a test,” you’ll hit a design wall as your test suite grows. Whether you know how to split scope and responsibility properly makes a real difference to how maintainable the whole suite stays.

Once you’ve got the basics of fixtures down, real projects tend to surface challenges like these:

• Every fixture is written at the default function scope, so launching a browser or connecting to a database happens over and over, and runtime creeps up
• You’re not sure where to put teardown logic — deleting files, rolling back a database transaction, and so on
• You have some setup you want to run for absolutely every test, but listing it as an argument everywhere feels tedious
• You need to create several pieces of test data with different names or conditions, all within one test

This article walks through the fixture features that address each of these, one at a time.

Where This Article Fits

This article assumes you already know the basics of fixtures and dives into fixtures themselves in depth. If you’d like a refresher on pytest fundamentals — fixtures, parametrize, and conftest.py — we recommend starting with an introductory article first.

① scope: Deciding How Widely a Fixture Gets Shared

The scope argument on a fixture controls how widely it gets reused. The default is function.

import pytest

@pytest.fixture(scope="function")  # same as omitting scope entirely
def user():
    return {"name": "Taro", "email": "taro@example.com"}

@pytest.fixture(scope="session")
def db_connection():
    conn = create_db_connection()
    yield conn
    conn.close()

② yield Fixtures: Setup and Teardown in One Place

Using yield instead of return lets you write setup (before the test) and teardown (after the test) naturally within a single fixture function.

import pytest
from playwright.sync_api import Browser, Page

@pytest.fixture
def page(browser: Browser):
    # --- Setup (before yield) ---
    # the browser fixture is provided by pytest-playwright out of the box
    page = browser.new_page()

    yield page  # this is the value handed to the test function

    # --- Teardown (after yield, runs once the test finishes) ---
    page.close()

def test_homepage_title(page: Page):
    page.goto("https://example.com")
    assert page.title() == "Example Domain"

③ autouse: Running Automatically Without Being Requested

Normally, a fixture only runs if you name it as an argument in your test function. Setting autouse=True makes it run automatically for every test within its scope, with no need to reference it explicitly.

import pytest

@pytest.fixture(autouse=True)
def reset_test_database():
    """Reset the test database to a clean state before every test."""
    reset_db()
    yield
    # add cleanup here if needed

# This test doesn't list reset_test_database as an argument, but it still runs automatically
def test_user_count_starts_at_zero():
    assert get_user_count() == 0

④ Composing Fixtures: One Fixture Using Another

A fixture can take another fixture as an argument. This lets you combine small fixtures into more specific preconditions.

import pytest
from playwright.sync_api import Page

@pytest.fixture
def base_url() -> str:
    return "https://staging.example.com"

@pytest.fixture
def logged_in_page(page: Page, base_url: str) -> Page:
    """Compose the built-in page fixture with base_url to arrive at a logged-in state."""
    page.goto(f"{base_url}/login")
    page.get_by_label("Email").fill("test@example.com")
    page.get_by_label("Password").fill("Password123")
    page.get_by_role("button", name="Log in").click()
    page.wait_for_url("**/dashboard")
    return page

# The test code doesn't need to think about the login step — it starts already logged in
def test_dashboard_shows_welcome_message(logged_in_page: Page):
    assert logged_in_page.get_by_text("Welcome").is_visible()

⑤ The Factory Pattern: Generating Data More Than Once Per Test

A normal fixture can only return one value per test. When you need to create several pieces of data with different conditions within the same test, you use the factory pattern — a fixture that returns a function instead of a value.

import pytest

@pytest.fixture
def make_user():
    """A factory fixture that returns a function for generating users."""
    created_users = []

    def _make_user(name: str = "Taro", email: str | None = None) -> dict:
        # Keep the email safe even for names with spaces, like "Alice Smith"
        safe_name = name.lower().replace(" ", ".")
        user = {
            "name": name,
            "email": email or f"{safe_name}@example.com",
        }
        created_users.append(user)
        return user

    yield _make_user

    # Clean up every user we created, once the test is done
    for user in created_users:
        delete_user(user["email"])

def test_transfer_between_two_users(make_user):
    # Create two users with different conditions, within a single test
    sender = make_user(name="Alice")
    receiver = make_user(name="Bob")

    transfer(sender, receiver, amount=1000)

    assert get_balance(receiver) == 1000

Common Mistakes Seen in Practice

FAQ

📋 Summary

Once you move past thinking of fixtures as “something that sets things up before a test,” they become a foundation that supports the design of your whole test suite. Take a look at the tests you’re writing right now — is there a scope worth revisiting, or a cleanup step you forgot to write?