Configuration - pytest documentation (original) (raw)

Toggle table of contents sidebar

Command line options and configuration file settings¶

You can get help on command line options and values in INI-style configurations files by using the general help option:

pytest -h # prints options and config file settings

This will display command line and configuration file settings which were registered by installed plugins.

Configuration file formats¶

Many pytest settings can be set in a configuration file, which by convention resides in the root directory of your repository.

A quick example of the configuration files supported by pytest:

pytest.ini¶

pytest.ini files take precedence over other files, even when empty.

Alternatively, the hidden version .pytest.ini can be used.

pytest.ini or .pytest.ini

[pytest] minversion = 6.0 addopts = -ra -q testpaths = tests integration

pyproject.toml¶

Added in version 6.0.

pyproject.toml are considered for configuration when they contain a tool.pytest.ini_options table.

pyproject.toml

[tool.pytest.ini_options] minversion = "6.0" addopts = "-ra -q" testpaths = [ "tests", "integration", ]

Note

One might wonder why [tool.pytest.ini_options] instead of [tool.pytest] as is the case with other tools.

The reason is that the pytest team intends to fully utilize the rich TOML data format for configuration in the future, reserving the [tool.pytest] table for that. The ini_options table is being used, for now, as a bridge between the existing.ini configuration system and the future configuration format.

tox.ini¶

tox.ini files are the configuration files of the tox project, and can also be used to hold pytest configuration if they have a [pytest] section.

tox.ini

[pytest] minversion = 6.0 addopts = -ra -q testpaths = tests integration

setup.cfg¶

setup.cfg files are general purpose configuration files, used originally by distutils (now deprecated) and setuptools, and can also be used to hold pytest configuration if they have a [tool:pytest] section.

setup.cfg

[tool:pytest] minversion = 6.0 addopts = -ra -q testpaths = tests integration

Warning

Usage of setup.cfg is not recommended unless for very simple use cases. .cfgfiles use a different parser than pytest.ini and tox.ini which might cause hard to track down problems. When possible, it is recommended to use the latter files, or pyproject.toml, to hold your pytest configuration.

Initialization: determining rootdir and configfile¶

pytest determines a rootdir for each test run which depends on the command line arguments (specified test files, paths) and on the existence of configuration files. The determined rootdir and configfile are printed as part of the pytest header during startup.

Here’s a summary what pytest uses rootdir for:

Construct nodeids during collection; each test is assigned a unique nodeid which is rooted at the rootdir and takes into account the full path, class name, function name and parametrization (if any).
Is used by plugins as a stable location to store project/test run specific information; for example, the internal cache plugin creates a .pytest_cache subdirectory in rootdir to store its cross-test run state.

rootdir is NOT used to modify sys.path/PYTHONPATH or influence how modules are imported. See pytest import mechanisms and sys.path/PYTHONPATH for more details.

The --rootdir=path command-line option can be used to force a specific directory. Note that contrary to other command-line options, --rootdir cannot be used withaddopts inside pytest.ini because the rootdir is used to find pytest.inialready.

Finding the `rootdir`¶

Here is the algorithm which finds the rootdir from args:

If -c is passed in the command-line, use that as configuration file, and its directory as rootdir.
Determine the common ancestor directory for the specified args that are recognised as paths that exist in the file system. If no such paths are found, the common ancestor directory is set to the current working directory.
Look for pytest.ini, pyproject.toml, tox.ini, and setup.cfg files in the ancestor directory and upwards. If one is matched, it becomes the configfile and its directory becomes the rootdir.
If no configuration file was found, look for setup.py upwards from the common ancestor directory to determine the rootdir.
If no setup.py was found, look for pytest.ini, pyproject.toml, tox.ini, andsetup.cfg in each of the specified args and upwards. If one is matched, it becomes the configfile and its directory becomes the rootdir.
If no configfile was found and no configuration argument is passed, use the already determined common ancestor as root directory. This allows the use of pytest in structures that are not part of a package and don’t have any particular configuration file.

If no args are given, pytest collects test below the current working directory and also starts determining the rootdir from there.

Files will only be matched for configuration if:

pytest.ini: will always match and take precedence, even if empty.
pyproject.toml: contains a [tool.pytest.ini_options] table.
tox.ini: contains a [pytest] section.
setup.cfg: contains a [tool:pytest] section.

Finally, a pyproject.toml file will be considered the configfile if no other match was found, in this case even if it does not contain a [tool.pytest.ini_options] table (this was added in 8.1).

The files are considered in the order above. Options from multiple configfiles candidates are never merged - the first match wins.

The configuration file also determines the value of the rootpath.

The Config object (accessible via hooks or through the pytestconfig fixture) will subsequently carry these attributes:

config.rootpath: the determined root directory, guaranteed to exist. It is used as a reference directory for constructing test addresses (“nodeids”) and can be used also by plugins for storing per-testrun information.
config.inipath: the determined configfile, may be None(it is named inipath for historical reasons).

Added in version 6.1: The config.rootpath and config.inipath properties. They are pathlib.Pathversions of the older config.rootdir and config.inifile, which have typepy.path.local, and still exist for backward compatibility.

Example:

pytest path/to/testdir path/other/

will determine the common ancestor as path and then check for configuration files as follows:

first look for pytest.ini files

path/pytest.ini path/pyproject.toml # must contain a [tool.pytest.ini_options] table to match path/tox.ini # must contain [pytest] section to match path/setup.cfg # must contain [tool:pytest] section to match pytest.ini ... # all the way up to the root

now look for setup.py

path/setup.py setup.py ... # all the way up to the root