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.
Initialization: determining rootdir and inifile¶
pytest determines a
rootdir for each test run which depends on
the command line arguments (specified test files, paths) and on
the existence of ini-files. The determined
rootdir and ini-file are
printed as part of the pytest header during startup.
Here’s a summary what
- Construct nodeids during collection; each test is assigned
a unique nodeid which is rooted at the
rootdirand takes in account 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
rootdirto store its cross-test run state.
Important to emphasize that
rootdir is NOT used to modify
influence how modules are imported. See pytest import mechanisms and sys.path/PYTHONPATH for more details.
--rootdir=path command-line option can be used to force a specific directory.
The directory passed may contain environment variables when it is used in conjunction
addopts in a
Here is the algorithm which finds the rootdir from
- determine the common ancestor directory for the specified
argsthat 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
setup.cfgfiles in the ancestor directory and upwards. If one is matched, it becomes the ini-file and its directory becomes the rootdir.
- if no ini-file was found, look for
setup.pyupwards from the common ancestor directory to determine the
- if no
setup.pywas found, look for
setup.cfgin each of the specified
argsand upwards. If one is matched, it becomes the ini-file and its directory becomes the rootdir.
- if no ini-file was found, 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 ini-file configuration.
args are given, pytest collects test below the current working
directory and also starts determining the rootdir from there.
|warning:||custom pytest plugin commandline arguments may include a path, as in
Note that an existing
pytest.ini file will always be considered a match,
setup.cfg will only match if they contain a
[tool:pytest] section, respectively. Options from multiple ini-files candidates are never
merged - the first one wins (
pytest.ini always wins, even if it does not
config object will subsequently carry these attributes:
config.rootdir: the determined root directory, guaranteed to exist.
config.inifile: the determined ini-file, may be
The rootdir is used as a reference directory for constructing test addresses (“nodeids”) and can be used also by plugins for storing per-testrun information.
pytest path/to/testdir path/other/
will determine the common ancestor as
path and then
check for ini-files as follows:
# first look for pytest.ini files path/pytest.ini path/tox.ini # must also contain [pytest] section to match path/setup.cfg # must also contain [tool:pytest] section to match pytest.ini ... # all the way down to the root # now look for setup.py path/setup.py setup.py ... # all the way down to the root
How to change command line options defaults¶
It can be tedious to type the same series of command line options
every time you use
pytest. For example, if you always want to see
detailed info on skipped and xfailed tests, as well as have terser “dot”
progress output, you can write it into a configuration file:
# content of pytest.ini or tox.ini [pytest] addopts = -ra -q # content of setup.cfg [tool:pytest] addopts = -ra -q
Alternatively, you can set a
PYTEST_ADDOPTS environment variable to add command
line options while the environment is in use:
Here’s how the command-line is built in the presence of
addopts or the environment variable:
<pytest.ini:addopts> $PYTEST_ADDOPTS <extra command-line arguments>
So if the user executes in the command-line:
pytest -m slow
The actual command line executed is:
pytest -ra -q -v -m slow
Note that as usual for other command-line applications, in case of conflicting options the last one wins, so the example
above will show verbose output because