1Configuration
2=============
3
4Command line options and configuration file settings
5-----------------------------------------------------------------
6
7You can get help on command line options and values in INI-style
8configurations files by using the general help option:
9
10.. code-block:: bash
11
12    pytest -h   # prints options _and_ config file settings
13
14This will display command line and configuration file settings
15which were registered by installed plugins.
16
17.. _`config file formats`:
18
19Configuration file formats
20--------------------------
21
22Many :ref:`pytest settings <ini options ref>` can be set in a *configuration file*, which
23by convention resides on the root of your repository or in your
24tests folder.
25
26A quick example of the configuration files supported by pytest:
27
28pytest.ini
29~~~~~~~~~~
30
31``pytest.ini`` files take precedence over other files, even when empty.
32
33.. code-block:: ini
34
35    # pytest.ini
36    [pytest]
37    minversion = 6.0
38    addopts = -ra -q
39    testpaths =
40        tests
41        integration
42
43
44pyproject.toml
45~~~~~~~~~~~~~~
46
47.. versionadded:: 6.0
48
49``pyproject.toml`` are considered for configuration when they contain a ``tool.pytest.ini_options`` table.
50
51.. code-block:: toml
52
53    # pyproject.toml
54    [tool.pytest.ini_options]
55    minversion = "6.0"
56    addopts = "-ra -q"
57    testpaths = [
58        "tests",
59        "integration",
60    ]
61
62.. note::
63
64    One might wonder why ``[tool.pytest.ini_options]`` instead of ``[tool.pytest]`` as is the
65    case with other tools.
66
67    The reason is that the pytest team intends to fully utilize the rich TOML data format
68    for configuration in the future, reserving the ``[tool.pytest]`` table for that.
69    The ``ini_options`` table is being used, for now, as a bridge between the existing
70    ``.ini`` configuration system and the future configuration format.
71
72tox.ini
73~~~~~~~
74
75``tox.ini`` files are the configuration files of the `tox <https://tox.readthedocs.io>`__ project,
76and can also be used to hold pytest configuration if they have a ``[pytest]`` section.
77
78.. code-block:: ini
79
80    # tox.ini
81    [pytest]
82    minversion = 6.0
83    addopts = -ra -q
84    testpaths =
85        tests
86        integration
87
88
89setup.cfg
90~~~~~~~~~
91
92``setup.cfg`` files are general purpose configuration files, used originally by `distutils <https://docs.python.org/3/distutils/configfile.html>`__, and can also be used to hold pytest configuration
93if they have a ``[tool:pytest]`` section.
94
95.. code-block:: ini
96
97    # setup.cfg
98    [tool:pytest]
99    minversion = 6.0
100    addopts = -ra -q
101    testpaths =
102        tests
103        integration
104
105.. warning::
106
107    Usage of ``setup.cfg`` is not recommended unless for very simple use cases. ``.cfg``
108    files use a different parser than ``pytest.ini`` and ``tox.ini`` which might cause hard to track
109    down problems.
110    When possible, it is recommended to use the latter files, or ``pyproject.toml``, to hold your
111    pytest configuration.
112
113
114.. _rootdir:
115.. _configfiles:
116
117Initialization: determining rootdir and configfile
118--------------------------------------------------
119
120pytest determines a ``rootdir`` for each test run which depends on
121the command line arguments (specified test files, paths) and on
122the existence of configuration files.  The determined ``rootdir`` and ``configfile`` are
123printed as part of the pytest header during startup.
124
125Here's a summary what ``pytest`` uses ``rootdir`` for:
126
127* Construct *nodeids* during collection; each test is assigned
128  a unique *nodeid* which is rooted at the ``rootdir`` and takes into account
129  the full path, class name, function name and parametrization (if any).
130
131* Is used by plugins as a stable location to store project/test run specific information;
132  for example, the internal :ref:`cache <cache>` plugin creates a ``.pytest_cache`` subdirectory
133  in ``rootdir`` to store its cross-test run state.
134
135``rootdir`` is **NOT** used to modify ``sys.path``/``PYTHONPATH`` or
136influence how modules are imported. See :ref:`pythonpath` for more details.
137
138The ``--rootdir=path`` command-line option can be used to force a specific directory.
139Note that contrary to other command-line options, ``--rootdir`` cannot be used with
140:confval:`addopts` inside ``pytest.ini`` because the ``rootdir`` is used to *find* ``pytest.ini``
141already.
142
143Finding the ``rootdir``
144~~~~~~~~~~~~~~~~~~~~~~~
145
146Here is the algorithm which finds the rootdir from ``args``:
147
148- Determine the common ancestor directory for the specified ``args`` that are
149  recognised as paths that exist in the file system. If no such paths are
150  found, the common ancestor directory is set to the current working directory.
151
152- Look for ``pytest.ini``, ``pyproject.toml``, ``tox.ini``, and ``setup.cfg`` files in the ancestor
153  directory and upwards.  If one is matched, it becomes the ``configfile`` and its
154  directory becomes the ``rootdir``.
155
156- If no configuration file was found, look for ``setup.py`` upwards from the common
157  ancestor directory to determine the ``rootdir``.
158
159- If no ``setup.py`` was found, look for ``pytest.ini``, ``pyproject.toml``, ``tox.ini``, and
160  ``setup.cfg`` in each of the specified ``args`` and upwards. If one is
161  matched, it becomes the ``configfile`` and its directory becomes the ``rootdir``.
162
163- If no ``configfile`` was found, use the already determined common ancestor as root
164  directory. This allows the use of pytest in structures that are not part of
165  a package and don't have any particular configuration file.
166
167If no ``args`` are given, pytest collects test below the current working
168directory and also starts determining the ``rootdir`` from there.
169
170Files will only be matched for configuration if:
171
172* ``pytest.ini``: will always match and take precedence, even if empty.
173* ``pyproject.toml``: contains a ``[tool.pytest.ini_options]`` table.
174* ``tox.ini``: contains a ``[pytest]`` section.
175* ``setup.cfg``: contains a ``[tool:pytest]`` section.
176
177The files are considered in the order above. Options from multiple ``configfiles`` candidates
178are never merged - the first match wins.
179
180The internal :class:`Config <_pytest.config.Config>` object (accessible via hooks or through the :fixture:`pytestconfig` fixture)
181will subsequently carry these attributes:
182
183- :attr:`config.rootpath <_pytest.config.Config.rootpath>`: the determined root directory, guaranteed to exist.
184
185- :attr:`config.inipath <_pytest.config.Config.inipath>`: the determined ``configfile``, may be ``None``
186  (it is named ``inipath`` for historical reasons).
187
188.. versionadded:: 6.1
189    The ``config.rootpath`` and ``config.inipath`` properties. They are :class:`pathlib.Path`
190    versions of the older ``config.rootdir`` and ``config.inifile``, which have type
191    ``py.path.local``, and still exist for backward compatibility.
192
193The ``rootdir`` is used as a reference directory for constructing test
194addresses ("nodeids") and can be used also by plugins for storing
195per-testrun information.
196
197Example:
198
199.. code-block:: bash
200
201    pytest path/to/testdir path/other/
202
203will determine the common ancestor as ``path`` and then
204check for configuration files as follows:
205
206.. code-block:: text
207
208    # first look for pytest.ini files
209    path/pytest.ini
210    path/pyproject.toml  # must contain a [tool.pytest.ini_options] table to match
211    path/tox.ini         # must contain [pytest] section to match
212    path/setup.cfg       # must contain [tool:pytest] section to match
213    pytest.ini
214    ... # all the way up to the root
215
216    # now look for setup.py
217    path/setup.py
218    setup.py
219    ... # all the way up to the root
220
221
222.. warning::
223
224    Custom pytest plugin commandline arguments may include a path, as in
225    ``pytest --log-output ../../test.log args``. Then ``args`` is mandatory,
226    otherwise pytest uses the folder of test.log for rootdir determination
227    (see also `issue 1435 <https://github.com/pytest-dev/pytest/issues/1435>`_).
228    A dot ``.`` for referencing to the current working directory is also
229    possible.
230
231
232.. _`how to change command line options defaults`:
233.. _`adding default options`:
234
235
236Builtin configuration file options
237----------------------------------------------
238
239For the full list of options consult the :ref:`reference documentation <ini options ref>`.
240