pytest-mock Tutorial: A Beginner’s Guide to Mocking in Python

Setting Up pytest-mock

Creating a virtual environment for your project is a best practice to ensure dependencies are isolated. If you haven’t already set up a new environment, you can create a conda one using the following commands:

# create a conda environment
conda create --name yourenvname python=3.11
# activate conda environment
conda activate yourenvname

Installing pytest and pytest-mock

Install pytest and pytest-mock directly in your environment using pip or conda:

pip install pytest
pip install pytest-mock

Confirming installation

After installing pytest and pytest-mock, verify that the installation was successful by running the following command:

pytest --version

Basics of Mocking with pytest-mock

Mocking can be thought of as creating a "dummy" version of a component that mimics real behavior. 

It is especially helpful when you need to test how functions or classes interact with external components like databases or external APIs.

Introduction to mocking

A mock object simulates the behavior of a real object. It is often used in unit tests to isolate components and test their behavior without executing dependent code. 

For example, you might use a mock object to simulate a database call without actually connecting to the database.

Mocking is particularly useful when the real object:

• Is difficult to create or configure.
• Is time-consuming to use (e.g., accessing a remote database).
• Has side effects that should be avoided during testing (e.g., sending emails, incurring costs).

Using the mocker fixture

pytest-mock provides a mocker fixture, making creating and controlling mock objects easy. The mocker fixture is powerful and integrates into your pytest tests.

Let’s see an example:

def fetch_weather_data(api_client):
    response = api_client.get("https://api.weather.com/data")
    if response.status_code == 200:
        return response.json()
    else:
        return None

The fetch_weather_data  function depends on an external weather API to retrieve data, but calling the API during tests could incur unnecessary costs. 

To avoid this, you can use mocking to simulate the API's behavior in your tests, ensuring the application is tested without making external calls. Here's how mocking can help:

def test_fetch_weather_data(mocker):
    # Create a mock API client
    mock_api_client = mocker.Mock()

    # Mock the response of the API client
    mock_response = mocker.Mock()
    mock_response.status_code = 200
    mock_response.json.return_value = {"temperature": "20C", "condition": "Sunny"}

    # Set the mock API client to return the mocked response
    mock_api_client.get.return_value = mock_response

    # Call the function with the mock API client
    result = fetch_weather_data(mock_api_client)

    # Assert that the correct data is returned
    assert result == {"temperature": "20C", "condition": "Sunny"}

    mock_api_client.get.assert_called_once_with("https://api.weather.com/data")

In test_fetch_weather_data(), we use the mocker fixture to create a mock API client mock_api_client and a mock_response. The mock response is configured to mimic a real API call by returning a status code of 200 and JSON data containing weather information. 

The get method of the mock API client is set to return this mock response. When fetch_weather_data() is tested, it interacts with the mock API client rather than making an actual API call. 

This approach ensures the function behaves as expected while keeping the tests fast, cost-efficient, and independent of external systems. 

The assert statement at the end verifies that the returned data matches the expected output.

The last line, mock_api_client.get.assert_called_once_with("https://api.weather.com/data"), specifically checks that the get method of the mock API client was called exactly once and with the correct argument. This helps confirm that the function is interacting with the API in the expected way, adding an extra layer of validation to the test.

Common Use Cases for pytest-mock

Mocking is useful in various scenarios, including unit tests where you need to isolate specific functions or components. Let's look at some common use cases:

1. Mocking functions or class methods

You may need to test a function that depends on other functions or methods, but you want to control their behavior during testing. Mocking allows you to replace those dependencies with predefined behavior:

# production code
def calculate_discount(price, discount_provider):
    discount = discount_provider.get_discount()
    return price - (price * discount / 100)

# test code
def test_calculate_discount(mocker):
    # Mock the get_discount method
    mock_discount_provider = mocker.Mock()
    mock_discount_provider.get_discount.return_value = 10  # Mocked discount value
    # Call the function with the mocked dependency
    result = calculate_discount(100, mock_discount_provider)
    # Assert the calculated discount is correct
    assert result == 90
    mock_discount_provider.get_discount.assert_called_once()

In this test, the get_discount() method of the discount_provider is mocked to return a predefined value (10%). This isolates the calculate_discount() function from the actual implementation of discount_provider.

2. Mocking time-dependent code

When testing functions that involve time or delays, mocking time-related methods helps avoid waiting or manipulating real time:

# production code
import time
def long_running_task():
    time.sleep(5)  # Simulate a long delay
    return "Task Complete"

# test code
def test_long_running_task(mocker):
    # Mock the sleep function in the time module
    mocker.patch("time.sleep", return_value=None)
    # Call the function
    result = long_running_task()
    # Assert the result is correct
    assert result == "Task Complete"

Here, time.sleep is patched to bypass the actual delay during testing. This ensures the test runs quickly without waiting for 5 seconds.

3. Mocking object attributes

Sometimes, you may want to mock the behavior of an object's attributes or properties to simulate different states during testing:

# production code
class User:
    def __init__(self, name, age):
        self.name = name
        self.age = age
    @property
    def is_adult(self):
        return self.age >= 18

# test code
def test_user_is_adult(mocker):
    # Create a User object
    user = User(name="Alice", age=17)
    # Mock the is_adult property
    mocker.patch.object(User, "is_adult", new_callable=mocker.PropertyMock, return_value=True)
    # Assert the mocked property value
    assert user.is_adult is True

In this example, the is_adult() property of the User class is mocked to return True, regardless of the actual age. This is useful for testing scenarios dependent on object states.

Advanced Mocking Techniques with pytest-mock

Once you're comfortable with basic mocking, pytest-mock offers advanced capabilities to handle more complex scenarios.

1. Mock side effects

Mocks can simulate more than just return values—they can also replicate behavior such as raising exceptions or dynamically changing return values. This is achieved by adding “side effects” to mocks:

import pytest

# production code
def process_payment(payment_gateway, amount):
    response = payment_gateway.charge(amount)
    if response == "Success":
        return "Payment processed successfully"
    else:
        raise ValueError("Payment failed")

# test code
def test_process_payment_with_side_effects(mocker):
    # Mock the charge method of the payment gateway
    mock_payment_gateway = mocker.Mock()
    # Add side effects: Success on first call, raise exception on second call
    mock_payment_gateway.charge.side_effect = ["Success", ValueError("Insufficient funds")]
    # Test successful payment
    assert process_payment(mock_payment_gateway, 100) == "Payment processed successfully"
    # Test payment failure
    with pytest.raises(ValueError, match="Insufficient funds"):
        process_payment(mock_payment_gateway, 200)
    # Verify the mock's behavior
    assert mock_payment_gateway.charge.call_count == 2

The side_effect property allows the mock to return different values or raise exceptions on subsequent calls. In this example, the first call to charge returns "Success", while the second call raises a ValueError. This is useful for testing various scenarios in a single test.

2. Spying on functions

Spying lets you track how a real function was called, including the number of calls and the arguments passed. It’s particularly useful when you want to ensure a function is called as expected while still executing its original logic:

# production code
def log_message(logger, message):
    logger.info(message)
    return f"Logged: {message}"

# test code
def test_log_message_with_spy(mocker):
    # Spy on the info method of the logger
    mock_logger = mocker.Mock()
    spy_info = mocker.spy(mock_logger, "info")
    # Call the function
    result = log_message(mock_logger, "Test message")
    # Assert the returned value
    assert result == "Logged: Test message"
    # Verify the spy behavior
    spy_info.assert_called_once_with("Test message")
    assert spy_info.call_count == 1

The spy() method keeps track of how a real method is called without altering its behavior. Here, we spy on the info method of the logger to ensure it is called with the correct message while still letting the method execute normally.

Best Practices for Using pytest-mock

Mocking is powerful, but using it carelessly can lead to issues in your tests. Here are some best practices I recommend following:

1. Avoid over-mocking

Using too many mocks can lead to brittle tests that break when internal code changes, even if external behavior does not. Strive to mock only what's necessary and rely on real implementations whenever possible.

Over-mocking can make your tests tightly coupled to the implementation details of your code, meaning that even minor refactoring can cause tests to fail unnecessarily. Instead, focus on mocking only those parts of the system that are external or have significant side effects.

2. Use clear naming conventions

When mocking objects, use descriptive names for your mocks. This makes your tests more readable and easier to maintain. For example, instead of using generic names like mock_function(), use something more descriptive, such as mock_api_response().

Clear naming conventions help others understand the purpose of each mock, reducing confusion and making it easier to maintain the test suite over time.

3. Keep tests simple and focused

Each test should focus on a single behavior or scenario. This simplifies debugging and keeps your tests easy to understand. A well-focused test is more likely to provide clear feedback when something goes wrong, making identifying and fixing issues easier.

Conclusion

In this blog, we explored the basics of mocking with pytest-mock and learned how to use it to improve our Python tests. We covered everything from basic mocking of functions and methods to more advanced techniques like adding side effects and spying on functions.

Mocking is an essential tool for creating reliable and maintainable tests, especially when working with complex systems or external dependencies. By incorporating pytest-mock in your projects, you can write more isolated, predictable, and easier-to-maintain tests.

To continue expanding your testing skills, I recommend checking out the Introduction to Testing in Python free course on Datacamp.