yieldfixture.rst

Overview

This documentation file covers the concept and usage of "yield_fixture" functions in the pytest testing framework. It explains the purpose and functionality of yield fixtures, which allow users to define setup and teardown behavior in test fixtures using Python's `yield` statement.

The key focus is on the historical context and current best practice regarding yield fixtures in pytest:

Prior to pytest 3.0, @pytest.yield_fixture was the decorator used to create fixtures that yield a value and then execute teardown code after the test.
Since pytest 3.0, the standard @pytest.fixture decorator supports the yield statement natively, making @pytest.yield_fixture deprecated.
This file documents this transition and encourages users to adopt the modern @pytest.fixture with yield syntax instead of the deprecated yield_fixture.

This file is part of the pytest documentation and helps users understand how to write fixtures with setup and teardown phases using the `yield` statement.

Detailed Explanations

Concept: Yield Fixtures in pytest

A *fixture* in pytest provides a fixed baseline upon which tests can reliably and repeatedly execute. Fixtures often involve setup steps (e.g., creating test data or opening resources) and teardown steps (e.g., closing connections or cleaning up files).

A *yield fixture* is a fixture function that uses Python's `yield` statement instead of `return`:

The code before the yield acts as the setup.
The value yielded is provided to the test function.
After the test function completes, the code after the yield executes as teardown.

Historical Usage

Before pytest 3.0:

import pytest

@pytest.yield_fixture
def resource():
    # Setup code
    setup_resource = acquire_resource()
    yield setup_resource
    # Teardown code
    release_resource(setup_resource)

@pytest.yield_fixture decorator was required.
The fixture yielded a resource for the test.
After the test, teardown code executed.

Current Recommended Usage (pytest 3.0+)

Now, the `yield` statement is fully supported inside `@pytest.fixture`, so the same fixture is written as:

import pytest

@pytest.fixture
def resource():
    # Setup code
    setup_resource = acquire_resource()
    yield setup_resource
    # Teardown code
    release_resource(setup_resource)

@pytest.fixture decorator is used.
The yield statement still handles setup and teardown.
The @pytest.yield_fixture decorator is deprecated and should not be used in new code.

Parameters and Return Values

Fixture functions using yield do not take parameters beyond what any fixture can take (e.g., other fixtures as arguments).
The value yielded is passed to the test function as the fixture value.
The fixture function does not return a value using return—it uses yield to provide the test resource.

Usage Examples

Below is an example of a modern yield fixture:

import pytest

@pytest.fixture
def db_connection():
    # Setup: open db connection
    connection = open_database()
    yield connection
    # Teardown: close db connection
    connection.close()

def test_query(db_connection):
    result = db_connection.query("SELECT * FROM users")
    assert result is not None

Important Implementation Details

The yield statement splits fixture execution into two phases: setup before yield, teardown after.
If an exception occurs during the test, the teardown code still executes, ensuring cleanup.
The deprecation of @pytest.yield_fixture simplifies the fixture API, reducing confusion.

Interaction with Other Parts of the System

This feature is integral to pytest's fixture system.
It interacts with pytest’s test discovery, setup/teardown management, and test execution engine.
Yield fixtures enable clean resource management and reusable test setup logic.
This documentation file assists users migrating from older pytest versions or learning fixture best practices.

Mermaid Diagram

The following class diagram illustrates the high-level structure of yield fixture usage, focusing on the fixture function lifecycle phases:

flowchart TD
    A[Fixture Function] --> B[Setup Code (before yield)]
    B --> C[Yielded Value to Test]
    C --> D[Test Function Executes]
    D --> E[Teardown Code (after yield)]
    E --> F[Fixture Cleanup Complete]

This flowchart shows the linear lifecycle:

Setup code runs first.
Fixture yields a value to the test.
Test runs using the fixture value.
After test completion, teardown code runs.
Fixture finishes cleanup.

Summary

yield_fixture was the original pytest decorator to create fixtures with setup/teardown using yield.
Since pytest 3.0, @pytest.fixture fully supports yield, rendering yield_fixture obsolete.
When writing new pytest fixtures with setup and teardown phases, use @pytest.fixture with yield.
This documentation aids understanding and transitioning from deprecated practices to modern pytest usage.

*End of yieldfixture.rst*