pytest Fixtures: monkeypatch, tmp_path, caplog, and capsys
Learn how pytest's built-in monkeypatch, tmp_path, caplog, and capsys fixtures isolate tests, with examples for environment variables, files, logs, and stdout/stderr.

When a pytest test needs to control its environment rather than accept whatever the machine happens to provide, four built-in fixtures cover the majority of cases: monkeypatch for changing attributes and environment variables, tmp_path for an isolated filesystem, caplog for inspecting log records, and capsys for capturing output written to stdout and stderr. Each fixture is function-scoped by default, meaning every test gets a fresh instance, and none of them require plugins or external packages.
The following table summarizes what each fixture provides:
| Fixture | Purpose | Typical return value |
|---|---|---|
monkeypatch | Patch attributes, environment variables, and working directory | Object with setattr, setenv, delenv, chdir |
tmp_path | Unique temporary directory per test | pathlib.Path |
caplog | Capture logging records | Object with records, text, set_level |
capsys | Capture stdout and stderr | Object with readouterr() |
monkeypatch: Changing Attributes and Environment Safely
monkeypatch is the fixture you reach for when a test must replace a function, a class attribute, or an environment variable without leaving changes behind. All modifications are reverted automatically when the test finishes, which keeps tests independent of each other.
The most common operations are:
monkeypatch.setattr(target, name, value)— replace an attributemonkeypatch.setenv(name, value)— set an environment variablemonkeypatch.delenv(name, raising=False)— remove an environment variablemonkeypatch.chdir(path)— change the working directory
Consider a function that reads an API key from the environment:
import os
def get_api_key():
return os.environ.get("API_KEY", "default-key")A test that verifies the fallback behavior can control the environment directly:
def test_api_key_fallback(monkeypatch):
monkeypatch.delenv("API_KEY", raising=False)
assert get_api_key() == "default-key"
def test_api_key_from_environment(monkeypatch):
monkeypatch.setenv("API_KEY", "test-key-123")
assert get_api_key() == "test-key-123"The raising=False argument prevents a KeyError when the variable is not already set. Without it, the test would fail on machines where API_KEY happens to be absent.
Patching a module attribute follows the same pattern. If a module imports a client object that should not perform a network call during tests, replace the callable with a stub:
import payments
def test_charge_success(monkeypatch):
def fake_charge(card, amount):
return {"status": "ok", "amount": amount}
monkeypatch.setattr(payments, "charge", fake_charge)
result = run_checkout(card="4242", amount=50)
assert result["status"] == "ok"Because monkeypatch restores the original attribute after the test, the stub never leaks into other tests. This is the main reason to prefer it over manually assigning and restoring attributes in try/finally blocks.
tmp_path: A Fresh Directory for Every Test
tmp_path provides a pathlib.Path pointing to a directory that pytest creates for the test and removes afterward. The directory is unique per test, so tests that write files do not collide with each other even when they run in parallel.
A function that writes a configuration file can be tested without touching the real filesystem:
def write_config(directory, name, content):
path = directory / name
path.write_text(content)
return pathThe test creates the file inside tmp_path and asserts on its contents:
def test_write_config(tmp_path):
result = write_config(tmp_path, "app.conf", "debug=true")
assert result.exists()
assert result.read_text() == "debug=true"Because tmp_path is a Path, you can use the full pathlib API: mkdir, glob, read_text, write_bytes, and so on. For tests that need a specific subdirectory structure, create it explicitly:
def test_nested_output(tmp_path):
output_dir = tmp_path / "build" / "cache"
output_dir.mkdir(parents=True)
write_config(output_dir, "cache.json", "{}")
assert (output_dir / "cache.json").exists()The fixture is function-scoped, so each test receives its own directory. If a test needs the same prepared directory across multiple tests, a session-scoped fixture can build on tmp_path_factory instead, but for most unit tests the per-test isolation of tmp_path is exactly what you want.
caplog: Asserting on Log Records Instead of Printed Output
caplog captures records emitted through the standard logging module. It is the right tool when your code logs structured information and the test needs to verify that a specific message was emitted, at a specific level, possibly with specific fields.
The fixture exposes:
caplog.records— a list oflogging.LogRecordobjectscaplog.text— the formatted log output as a single stringcaplog.set_level(level, logger=...)— set the capture thresholdcaplog.at_level(level, logger=...)— context manager for temporary level changes
By default, caplog captures at the WARNING level. To capture INFO messages, set the capture level to logging.INFO first:
import logging
def process_order(order_id):
logging.info("Processing order %s", order_id)
return f"done-{order_id}"
def test_process_order_logs_info(caplog):
with caplog.at_level(logging.INFO):
result = process_order("ord-1")
assert result == "done-ord-1"
assert any(r.getMessage() == "Processing order ord-1" for r in caplog.records)caplog.text is convenient when you only care that a message appears anywhere in the output:
def test_process_order_logs_text(caplog):
with caplog.at_level(logging.INFO):
process_order("ord-2")
assert "Processing order ord-2" in caplog.textThe distinction between caplog and capsys matters: caplog sees logging records, while capsys sees what is written to stdout and stderr. A print() call does not create a log record, so caplog will not see it. Conversely, a logging call does not write to stdout or stderr unless a logging handler is configured to send it there, so capsys is not the right tool for verifying log records.
capsys: Capturing stdout and stderr
capsys captures everything a test writes to stdout and stderr, including output from the code under test and from third-party libraries. Call capsys.readouterr() to retrieve what has been captured so far; it returns a namedtuple with out and err fields.
A function that prints a report can be verified like this:
import sys
def print_report(title):
print(f"Report: {title}")
print("generated", file=sys.stderr)def test_print_report(capsys):
print_report("Q3")
captured = capsys.readouterr()
assert captured.out == "Report: Q3\n"
assert captured.err == "generated\n"Because readouterr() returns everything captured since the last call, you can call it multiple times within one test to inspect output produced at different stages:
def test_multiple_reads(capsys):
print("first")
first = capsys.readouterr().out
print("second")
second = capsys.readouterr().out
assert first == "first\n"
assert second == "second\n"One practical detail: capsys captures at the Python sys.stdout and sys.stderr level. If you need to capture output written directly to file descriptors 1 and 2 — for example, from a subprocess or a C extension that bypasses Python's stdout object — use capfd instead. capfd is the lower-level variant; capsys is the more common choice for pure Python code.
Combining the Fixtures in a Realistic Test
The four fixtures are designed to work together. A realistic test may patch an environment variable, write a temporary file, verify a log message, and confirm what was printed — all in one test.
Consider a function that loads a config file, logs the loaded settings, and prints a summary:
import json
import logging
import os
def load_and_report(config_dir, filename):
path = config_dir / filename
data = json.loads(path.read_text())
env = os.environ.get("APP_ENV", "development")
logging.info("Loaded config with %d keys in %s", len(data), env)
print(f"Loaded {len(data)} settings from {env}")
return dataA test that exercises all four fixtures:
def test_load_and_report(tmp_path, caplog, capsys, monkeypatch):
config_file = tmp_path / "settings.json"
config_file.write_text('{"debug": true, "retries": 3}')
monkeypatch.setenv("APP_ENV", "test")
with caplog.at_level(logging.INFO):
result = load_and_report(tmp_path, "settings.json")
captured = capsys.readouterr()
assert result == {"debug": True, "retries": 3}
assert "Loaded config with 2 keys in test" in caplog.text
assert captured.out == "Loaded 2 settings from test\n"Each fixture handles one concern: tmp_path provides the file to read, caplog verifies the log record, capsys verifies the printed output, and monkeypatch controls the environment variable. Because monkeypatch reverts the environment change at the end of the test, the test does not affect other tests that read APP_ENV.
Fixture Scope and Test Isolation Tradeoffs
All four fixtures are function-scoped by default, which is the right default for unit tests: each test starts from a clean state. The cost is that setup work repeated across many tests — for example, creating the same directory structure or preparing the same log level — is repeated as well.
When that repetition becomes noticeable, the usual move is to extract a helper fixture that composes the built-in ones:
import pytest
@pytest.fixture
def prepared_env(tmp_path, monkeypatch):
config_dir = tmp_path / "config"
config_dir.mkdir()
(config_dir / "app.conf").write_text("debug=true")
monkeypatch.setenv("APP_CONFIG_DIR", str(config_dir))
return config_dirTests can then request prepared_env instead of manually recreating the setup. The underlying tmp_path and monkeypatch fixtures still guarantee isolation; the helper only reduces duplication.
A caveat worth noting: monkeypatch itself is function-scoped, so it should not be used from a session-scoped fixture to set up a patch for the whole session. If you do need session-wide patching, apply the change in a session-scoped fixture and restore it in a finalizer, but be aware that the patch then affects every test in the session and can mask isolation problems. Prefer function-scoped patching unless you have a concrete reason to do otherwise.
Similarly, tmp_path is always function-scoped and cannot be shared across tests. If a large fixture file must be reused, create it once in a session-scoped fixture and copy it into tmp_path per test, rather than trying to share the writable directory itself. That keeps each test's filesystem isolated while avoiding repeated expensive generation.
The practical rule is: use the built-in fixtures at their default scope for individual tests, and only introduce custom fixtures when the setup is genuinely repeated and the isolation semantics remain clear.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.