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