tmp_path and tmp_path_factory in PyTest - Deep Dive

Overview - tmp_path and tmp_path_factory

What is it?

tmp_path and tmp_path_factory are features in pytest that help create temporary directories for tests. tmp_path provides a fresh temporary directory for each test function. tmp_path_factory allows creating multiple temporary directories or customizing their creation. These tools help tests run in isolation without affecting real files.

Why it matters

Tests often need to create or modify files, but doing this in real folders can cause conflicts or leftover files. tmp_path and tmp_path_factory solve this by giving each test a clean, temporary space that disappears after the test finishes. Without them, tests could interfere with each other or leave clutter, making debugging and maintenance harder.

Where it fits

Before learning tmp_path and tmp_path_factory, you should understand basic pytest test functions and fixtures. After mastering these, you can explore more advanced pytest fixtures, mocking file systems, and test isolation techniques.

Mental Model

Core Idea

tmp_path and tmp_path_factory provide safe, temporary folders that tests can use to read and write files without risk of side effects or leftover data.

Think of it like...

It's like having a disposable workbench for each project: you build and test your parts there, then throw the bench away, so your real workspace stays clean and organized.

┌───────────────┐
│ Test Function │
└──────┬────────┘
       │ uses
       ▼
┌───────────────┐       ┌─────────────────────┐
│   tmp_path    │──────▶│ Temporary Directory │
│ (one per test)│       │  (isolated, clean)  │
└───────────────┘       └─────────────────────┘

┌───────────────────────┐
│  tmp_path_factory     │
│ (creates multiple or  │
│ customized tmp_paths) │
└───────────────┬───────┘
                │
                ▼
       ┌─────────────────────┐
       │ Temporary Directories│
       │  (multiple, custom)  │
       └─────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding pytest fixtures

Concept: Learn what pytest fixtures are and how they provide resources to tests.

Pytest fixtures are functions that prepare something your test needs, like data or a setup step. You write a fixture with @pytest.fixture and then add its name as a parameter to your test function. Pytest runs the fixture first and passes its result to your test.

Result

You can reuse setup code easily and keep tests clean.

Understanding fixtures is key because tmp_path and tmp_path_factory are special fixtures that provide temporary directories.

2

Foundation

Using tmp_path for temporary directories

Concept: tmp_path is a built-in pytest fixture that gives each test a unique temporary directory as a pathlib.Path object.

In your test, add tmp_path as a parameter. Pytest creates a new folder for that test and passes its path. You can create files or folders inside it using normal pathlib methods. After the test ends, pytest deletes this folder automatically.

Result

Each test gets a clean folder to work with, isolated from others.

Knowing tmp_path gives you a safe place to create files without polluting your real file system or other tests.

3

Intermediate

Creating multiple temp directories with tmp_path_factory

🤔Before reading on: do you think tmp_path_factory creates one or multiple temporary directories? Commit to your answer.

Concept: tmp_path_factory is a fixture that lets you create multiple temporary directories during a test or fixture setup.

Instead of just one folder, tmp_path_factory has a method mktemp(name) that creates a new temporary directory with the given name. You can call this multiple times to get several folders. This is useful when your test needs more than one isolated folder.

Result

You can manage multiple temporary folders in one test, each isolated and cleaned up after tests.

Understanding tmp_path_factory expands your ability to organize complex tests that need several temporary spaces.

4

Intermediate

Difference between tmp_path and tmp_path_factory

🤔Before reading on: do you think tmp_path is built using tmp_path_factory or are they unrelated? Commit to your answer.

Concept: tmp_path is a shortcut fixture that uses tmp_path_factory internally to create one temporary directory per test.

tmp_path_factory is the underlying tool that manages temporary directories. tmp_path is a convenience fixture that calls tmp_path_factory.mktemp with a unique name for each test. So tmp_path is like a ready-made single temp folder, while tmp_path_factory gives you more control.

Result

You know when to use the simple tmp_path and when to use tmp_path_factory for advanced needs.

Knowing this relationship helps you choose the right fixture and understand pytest's design.

5

Advanced

Customizing temporary directory names

🤔Before reading on: do you think you can control the exact folder name created by tmp_path? Commit to your answer.

Concept: tmp_path_factory.mktemp lets you specify the folder name prefix, giving you control over temporary directory names.

When you call tmp_path_factory.mktemp('myfolder'), pytest creates a temp directory with a name starting with 'myfolder' plus some unique suffix. This helps when you want meaningful folder names for debugging or organizing test outputs.

Result

Temporary folders have recognizable names, making test logs easier to understand.

Custom names improve test clarity and debugging without losing isolation.

6

Advanced

Scope and lifetime of tmp_path and tmp_path_factory

🤔Before reading on: do you think tmp_path directories persist after the test session ends? Commit to your answer.

Concept: tmp_path directories exist only during the test function and are deleted after. tmp_path_factory can create directories with different scopes if used in fixtures with broader scope.

tmp_path is function-scoped: each test gets a fresh directory that disappears after the test. tmp_path_factory can be used in fixtures with module or session scope to create temp directories that last longer, useful for sharing data between tests.

Result

You can manage temporary data lifetime precisely to fit your test needs.

Understanding scope prevents accidental data loss or pollution between tests.

7

Expert

How pytest cleans up temporary directories safely

🤔Before reading on: do you think pytest deletes temp directories immediately after test or waits until all tests finish? Commit to your answer.

Concept: Pytest tracks all temporary directories created and deletes them after the test or test session, handling errors and ensuring no leftovers remain.

When pytest creates a temp directory via tmp_path or tmp_path_factory, it registers it for cleanup. For function-scoped tmp_path, cleanup happens right after the test. For longer scopes, cleanup happens after the fixture scope ends. Pytest uses safe deletion methods to avoid errors if files are locked or in use.

Result

Your file system stays clean, and tests don't leave garbage even if they fail or crash.

Knowing pytest's cleanup mechanism helps you trust and debug test isolation and resource management.

Under the Hood

Pytest uses the built-in tempfile module to create temporary directories in the system's temp folder. tmp_path_factory manages a factory object that creates these directories with unique names. It tracks created directories and registers finalizers to delete them after the test or fixture scope ends. tmp_path is a fixture that calls tmp_path_factory.mktemp with a unique name per test function. The directories are pathlib.Path objects, allowing easy file operations.

Why designed this way?

The design ensures test isolation and automatic cleanup without burdening the test writer. Using pathlib.Path integrates with modern Python file handling. Separating tmp_path and tmp_path_factory gives a simple interface for common cases and a flexible tool for complex scenarios. This balances ease of use and power.

┌─────────────────────────────┐
│ pytest test session starts   │
└─────────────┬───────────────┘
              │
      ┌───────▼────────┐
      │ tmp_path_factory│
      │ creates temp dir│
      └───────┬────────┘
              │
      ┌───────▼────────┐
      │ tmp_path calls │
      │ mktemp()       │
      └───────┬────────┘
              │
      ┌───────▼────────┐
      │ test function  │
      │ uses tmp_path  │
      └───────┬────────┘
              │
      ┌───────▼────────┐
      │ test runs with │
      │ isolated folder│
      └───────┬────────┘
              │
      ┌───────▼────────┐
      │ pytest cleanup │
      │ deletes folder │
      └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does tmp_path create the same temporary directory for all tests or a new one each time? Commit to your answer.

Common Belief: tmp_path creates one temporary directory shared by all tests.

Reality: tmp_path creates a unique temporary directory for each test function, ensuring isolation.

Why it matters: If you assume tmp_path is shared, you might write tests that unintentionally interfere with each other, causing flaky or incorrect results.

Quick: Can tmp_path_factory create temporary files directly? Commit to your answer.

Common Belief: tmp_path_factory can create temporary files directly like tmp_path.

Reality: tmp_path_factory only creates temporary directories; you must create files inside those directories yourself.

Why it matters: Misunderstanding this leads to errors or confusion when trying to create files directly from tmp_path_factory.

Quick: Does pytest keep temporary directories after tests finish for debugging? Commit to your answer.

Common Belief: Pytest always deletes temporary directories immediately after tests finish.

Reality: By default, pytest deletes temp directories after tests, but you can configure it to keep them for debugging using command-line options.

Why it matters: Knowing this helps you debug test failures by inspecting temp files instead of losing them immediately.

Quick: Is tmp_path_factory only useful for creating one temporary directory? Commit to your answer.

Common Belief: tmp_path_factory is only for creating a single temporary directory per test.

Reality: tmp_path_factory is designed to create multiple temporary directories with custom names, useful for complex test setups.

Why it matters: Ignoring this limits your ability to write tests that need multiple isolated folders, reducing test flexibility.

Expert Zone

1

tmp_path_factory directories are created under a common base temporary directory, which can be customized via pytest configuration for better control over temp storage location.

2

Using tmp_path_factory in fixtures with module or session scope allows sharing temporary directories across multiple tests, balancing isolation and performance.

3

Pytest's cleanup mechanism uses finalizers and handles exceptions during deletion gracefully, preventing test crashes even if files are locked or in use.

When NOT to use

Avoid tmp_path and tmp_path_factory when you need persistent test data across multiple test runs or when testing code that requires real user directories. In such cases, consider using dedicated test data folders under version control or mocking file system calls with libraries like pyfakefs.

Production Patterns

In real-world projects, tmp_path is commonly used for simple file creation tests, while tmp_path_factory is used in fixtures that prepare complex directory structures shared by multiple tests. Teams often combine tmp_path_factory with parameterized tests to generate varied test environments dynamically.

Connections

Mocking

Builds-on

Understanding tmp_path helps when mocking file system operations, as both isolate tests from real files but tmp_path provides real temporary files while mocking simulates file behavior.

Continuous Integration (CI)

Supports

Using tmp_path ensures tests run cleanly and independently in CI pipelines, preventing flaky failures caused by leftover files or shared state.

Disposable Environments in Cloud Computing

Same pattern

Both tmp_path and disposable cloud environments provide isolated, temporary resources that are created fresh and destroyed after use, ensuring no side effects or pollution.

Common Pitfalls

#1 Reusing tmp_path across multiple tests expecting shared data.

Wrong approach:

def test_one(tmp_path):
file = tmp_path / 'data.txt'
file.write_text('hello')

def test_two(tmp_path):
content = (tmp_path / 'data.txt').read_text()
assert content == 'hello'

Correct approach:

def test_one(tmp_path):
file = tmp_path / 'data.txt'
file.write_text('hello')

def test_two(tmp_path):
# tmp_path is unique per test, so create needed files here
file = tmp_path / 'data.txt'
file.write_text('hello')
content = file.read_text()
assert content == 'hello'

Root cause:

Misunderstanding that tmp_path is unique per test and not shared causes tests to fail due to missing files.

#2 Trying to create files directly from tmp_path_factory without creating directories first.

Wrong approach:

def test_files(tmp_path_factory):
file = tmp_path_factory / 'file.txt'
file.write_text('data')

Correct approach:

def test_files(tmp_path_factory):
temp_dir = tmp_path_factory.mktemp('mydir')
file = temp_dir / 'file.txt'
file.write_text('data')

Root cause:

tmp_path_factory is not a Path object but a factory; you must first create a directory before creating files inside.

#3 Assuming temporary directories persist after test session for manual inspection.

Wrong approach:

# Run tests normally
pytest tests/
# Try to find temp directories after tests

Correct approach:

# Run tests with option to keep temp dirs
pytest --basetemp=/tmp/pytest-temp --keep-basetemp tests/

Root cause:

By default, pytest deletes temp directories after tests; without special options, you cannot inspect them later.

Key Takeaways

tmp_path provides a unique temporary directory for each test function, ensuring file system isolation.

tmp_path_factory is a flexible fixture that creates multiple temporary directories with custom names, useful for complex test setups.

Both fixtures use pathlib.Path objects, making file operations intuitive and Pythonic.

Pytest automatically cleans up temporary directories after tests, preventing leftover files and clutter.

Understanding the scope and lifecycle of these fixtures helps write reliable, maintainable tests that do not interfere with each other.