Pytest fixtures

6 minutes

Fixtures are pytest helper functions used to create modular, scalable, and maintainable tests. You use fixtures to set up preconditions for tests such as database connections, creating test data, or configuring a system state required before a test can run. They can also be used for cleanup after tests are done running.

Key characteristics of pytest fixtures include:

Scope control: Fixtures can be configured to have different scopes using the scope parameter (such as function, class, module, or session), which determine how often the fixture is called.
Handling of setup and teardown: Pytest manages the lifecycle of fixtures, automatically setting up and tearing down as required.
Dependency injection: Fixtures are injected into test functions as arguments, making it clear which tests rely on which fixtures.
Reusability and modularity: Fixtures can be defined in one place and used across multiple test functions, modules, or even projects.

Creating a temporary file fixture

When writing tests that interact with files, it's common to need temporary files that don't clutter the file system post-test. With pytest, we can create a fixture that sets up a temporary file. The fixture uses Python's tempfile module to generate temporary files safely, ensuring that they can be used and deleted without affecting the local environment. (In this initial version of our fixture, the file won't be automatically deleted because of the delete=False flag. We address file deletion later on.)

Here's what the fixture looks like:

import pytest
import tempfile

@pytest.fixture
def tmp_file():
    def create():
        # Create a named temporary file that persists beyond the function scope
        temp = tempfile.NamedTemporaryFile(delete=False)
        return temp.name
    return create

In this setup, tmp_file() acts as the fixture. The fixture's name is how tests reference it. Within the fixture, the nested function create() creates the file only when called, rather than upon fixture setup. This allows precise control over when the temporary file is created, which is useful in tests where timing and file state are critical.

Within the nested function create(), a temporary file is created and then returns the absolute path to it. Here's an example of how a test might use the fixture we wrote:

import os

def test_file(tmp_file):
    path = tmp_file()
    assert os.path.exists(path)

A test uses a fixture by specifying the name of the fixture as an argument. Our simple use case can be easily expanded by writing to the file or making modifications such as changing permissions or ownership.

Scope management

In pytest, managing the lifecycle of test resources through setup and teardown routines is crucial for maintaining clean and efficient test environments. You also want to safeguard the integrity of tests by ensuring that each test starts with a known, consistent state. By default, pytest fixtures operate with a function scope, which impacts behavior in two ways:

Lifecycle per test: The fixture's return value is recalculated for every test function that uses it, ensuring that each test operates with a fresh state.
Cleanup after each use: Any necessary cleanup operations are performed after each test that utilizes the fixture.

Pytest also allows fixtures to be scoped more broadly to optimize performance and resource usage. Scoping is particularly useful in situations like managing database state or when you have complex state setups that are time-consuming to establish. The four scopes available are:

function: Default scope, the fixture is executed once per test
class: The fixture runs once per test class.
module: Runs once for a module.
session: Runs once per test session. This scope is useful for expensive operations that need to persist throughout the entire test session, such as initializing a service or starting a database server.

In this case, running once means that the return value is cached. So a fixture that has a scope of "module" can get called several times in a test module, but the return value is that of the first test that called it.

Here's how the tmp_file() fixture would look with a module scope:

import pytest
import tempfile

@pytest.fixture(scope="module")
def tmp_file():
    def create():
        temp = tempfile.NamedTemporaryFile(delete=False)
        return temp.name
    return create

Cleanup management

The previous code specifying the tmp_file fixture creates a temporary file, but it doesn't automatically handle cleanup after tests are completed. To ensure that temporary files aren't left behind, you can use pytest's request fixture to register a cleanup function.

Here's how you can modify the tmp_file fixture to include automatic cleanup:

import pytest
import tempfile
import os

@pytest.fixture(scope="module")
def tmp_file(request):
    # Create a temporary file that persists beyond the function scope
    temp = tempfile.NamedTemporaryFile(delete=False)

    def create():
        # Returns the path of the temporary file
        return temp.name

    def cleanup():
        # Remove the file after the tests are done
        os.remove(temp.name)

    # Register the cleanup function to be called after the last test in the module
    request.addfinalizer(cleanup)

    return create

By using request.addfinalizer() and passing the nested cleanup() function, the cleanup gets called depending on the scope. In this case, the scope is module, so after all tests in a module pytest calls that cleanup function.

Using conftest.py

Instead of including your fixtures in your test files you can save them in a conftest.py file. All fixtures in conftest.py are automatically available to your tests in the same directory without having to explicitly import them.

Exploring built-in fixtures

Pytest has many built-in fixtures designed to streamline testing. These fixtures can handle setup and cleanup automatically, allowing you to focus on writing your test cases instead of test management.

Key built-in fixtures include:

cache: Used to create and manage test-level cache, which is useful for storing data between test sessions.
capsys: Captures and allows inspection of stderr and stdout, making it easy to inspect and test console outputs.
tmpdir: Provides a temporary directory for files that need to be created and used during tests.
monkeypatch: Provides a way to safely modify the behavior and values of objects, functions, and your os environment.

The role of monkeypatching in testing

Testing code that tightly integrates with external resources like databases or external APIs can be challenging due to the dependencies involved. A technique called monkey patching involves temporarily modifying your system during test runs, which allows for independence from external systems and lets you safely alter the state and behavior of your operating system environment during testing.

Here's an example of how to override the os.path.exists() function using the monkeypatch fixture:

import os

def test_os(monkeypatch):
    # Override os.path.exists to always return False
    monkeypatch.setattr('os.path.exists', lambda x: False)
    assert not os.path.exists('/')

Alternatively, you can use the setattr() method with direct reference to the object and attribute:

def test_os(monkeypatch):
    # Specify the object and attribute to override
    monkeypatch.setattr(os.path, 'exists', lambda x: False)
    assert not os.path.exists('/')

Aside from setting attributes and overriding methods, the monkeypatch fixture can set and delete environment variables, change dictionary values, and modify system paths. The monkeypatch fixture automatically reverts any changes after each test but care should still be taken when using the monkeypatch fixture. Here are some reasons to be careful when using it:

-Code clarity and maintenance: Overusing monkeypatch or using it in complex ways can make test harder to understand and maintain. When you read your test results, it might not be immediately clear how the components are supposed to behave normally vs. how they're modified for testing. -Test validity: Monkeypatching can sometimes lead to tests that pass under artificial conditions that are very different from the production environment. This can create a false sense of security, as the tests might pass because the test altered the system's behavior too dramatically. -Overdependence on implementation details: Tests that rely on monkeypatching might be tightly coupled to specific implementation details of the code they're testing. This can make tests brittle and susceptible to breaking with even minor changes to the underlying codebase. -Debugging complexity: Debugging tests that use monkeypatch can be more complex, especially if the patch changes fundamental aspects of the applications behavior. Understanding why a test is failing might require a deeper dive into how the components are being modified during the test.

While monkeypatch is a powerful tool for creating isolated and controlled test environments, it should be used judiciously and with a clear understanding of how it affects the test suite and the application's behavior.