Pytest-Temporary directories and files

The tmp_path fixture

You can use the tmp_path fixture which will provide a temporary
directory unique to the test invocation, created in the [base temporary
directory](#base temporary directory).

tmp_path is a pathlib.Path object. Here is an example test usage:

# content of test_tmp_path.py
CONTENT = "content"


def test_create_file(tmp_path):
    d = tmp_path / "sub"
    d.mkdir()
    p = d / "hello.txt"
    p.write_text(CONTENT)
    assert 0

Running this would result in a passed test except for the last
assert 0 line which we use to look at values:

$ pytest test_tmp_path.py
platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-0.x.y
cachedir: $PYTHON_PREFIX/.pytest_cache
rootdir: $REGENDOC_TMPDIR
collected 1 item

test_tmp_path.py F                                                   [100%]

_____________________________ test_create_file _____________________________

tmp_path = PosixPath('PYTEST_TMPDIR/test_create_file0')

    def test_create_file(tmp_path):
        d = tmp_path / "sub"
        d.mkdir()
        p = d / "hello.txt"
        p.write_text(CONTENT)
>       assert 0
E       assert 0

test_tmp_path.py:13: AssertionError
FAILED test_tmp_path.py::test_create_file - assert 0

The tmp_path_factory fixture {#tmp_path_factory example}

The tmp_path_factory is a session-scoped fixture which can be used to
create arbitrary temporary directories from any other fixture or test.

It is intended to replace tmpdir_factory, and returns
pathlib.Path{.interpreted-text role=“class”} instances.

See
tmp_path_factory API <tmp_path_factory factory api>{.interpreted-text
role=“ref”} for details.

The ‘tmpdir’ fixture

You can use the tmpdir fixture which will provide a temporary
directory unique to the test invocation, created in the [base temporary
directory](#base temporary directory).

tmpdir is a
py.path.local object
which offers os.path methods and more. Here is an example test usage:

# content of test_tmpdir.py
def test_create_file(tmpdir):
    p = tmpdir.mkdir("sub").join("hello.txt")
    p.write("content")
    assert 0

Running this would result in a passed test except for the last
assert 0 line which we use to look at values:

$ pytest test_tmpdir.py
platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-0.x.y
cachedir: $PYTHON_PREFIX/.pytest_cache
rootdir: $REGENDOC_TMPDIR
collected 1 item

test_tmpdir.py F                                                     [100%]

_____________________________ test_create_file _____________________________

tmpdir = local('PYTEST_TMPDIR/test_create_file0')

    def test_create_file(tmpdir):
        p = tmpdir.mkdir("sub").join("hello.txt")
        p.write("content")
>       assert 0
E       assert 0

test_tmpdir.py:9: AssertionError
FAILED test_tmpdir.py::test_create_file - assert 0

The ‘tmpdir_factory’ fixture {#tmpdir factory example}

The tmpdir_factory is a session-scoped fixture which can be used to
create arbitrary temporary directories from any other fixture or test.

For example, suppose your test suite needs a large image on disk, which
is generated procedurally. Instead of computing the same image for each
test that uses it into its own tmpdir, you can generate it once
per-session to save time:

# contents of conftest.py
import pytest


@pytest.fixture(scope="session")
def image_file(tmpdir_factory):
    img = compute_expensive_image()
    fn = tmpdir_factory.mktemp("data").join("img.png")
    img.save(str(fn))
    return fn


# contents of test_image.py
def test_histogram(image_file):
    img = load_image(image_file)
    # compute and test histogram

See tmpdir_factory API <tmpdir factory api>{.interpreted-text
role=“ref”} for details.

The default base temporary directory {#base temporary directory}

Temporary directories are by default created as sub-directories of the
system temporary directory. The base name will be pytest-NUM where
NUM will be incremented with each test run. Moreover, entries older
than 3 temporary directories will be removed.

You can override the default temporary directory setting like this:

pytest --basetemp=mydir

::: {.warning}
::: {.title}
Warning
:::

The contents of mydir will be completely removed, so make sure to use
a directory for that purpose only.
:::

When distributing tests on the local machine using pytest-xdist, care
is taken to automatically configure a basetemp directory for the sub
processes such that all temporary data lands below a single per-test run
basetemp directory.