1Basic test configuration 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 py.test -h # prints options _and_ config file settings 11 12This will display command line and configuration file settings 13which were registered by installed plugins. 14 15.. _rootdir: 16.. _inifiles: 17 18initialization: determining rootdir and inifile 19----------------------------------------------- 20 21.. versionadded:: 2.7 22 23pytest determines a "rootdir" for each test run which depends on 24the command line arguments (specified test files, paths) and on 25the existence of inifiles. The determined rootdir and ini-file are 26printed as part of the pytest header. The rootdir is used for constructing 27"nodeids" during collection and may also be used by plugins to store 28project/testrun-specific information. 29 30Here is the algorithm which finds the rootdir from ``args``: 31 32- determine the common ancestor directory for the specified ``args``. 33 34- look for ``pytest.ini``, ``tox.ini`` and ``setup.cfg`` files in the 35 ancestor directory and upwards. If one is matched, it becomes the 36 ini-file and its directory becomes the rootdir. An existing 37 ``pytest.ini`` file will always be considered a match whereas 38 ``tox.ini`` and ``setup.cfg`` will only match if they contain 39 a ``[pytest]`` section. 40 41- if no ini-file was found, look for ``setup.py`` upwards from 42 the common ancestor directory to determine the ``rootdir``. 43 44- if no ini-file and no ``setup.py`` was found, use the already 45 determined common ancestor as root directory. This allows to 46 work with pytest in structures that are not part of a package 47 and don't have any particular ini-file configuration. 48 49Note that options from multiple ini-files candidates are never merged, 50the first one wins (``pytest.ini`` always wins even if it does not 51contain a ``[pytest]`` section). 52 53The ``config`` object will subsequently carry these attributes: 54 55- ``config.rootdir``: the determined root directory, guaranteed to exist. 56 57- ``config.inifile``: the determined ini-file, may be ``None``. 58 59The rootdir is used a reference directory for constructing test 60addresses ("nodeids") and can be used also by plugins for storing 61per-testrun information. 62 63Example:: 64 65 py.test path/to/testdir path/other/ 66 67will determine the common ancestor as ``path`` and then 68check for ini-files as follows:: 69 70 # first look for pytest.ini files 71 path/pytest.ini 72 path/setup.cfg # must also contain [pytest] section to match 73 path/tox.ini # must also contain [pytest] section to match 74 pytest.ini 75 ... # all the way down to the root 76 77 # now look for setup.py 78 path/setup.py 79 setup.py 80 ... # all the way down to the root 81 82 83.. _`how to change command line options defaults`: 84.. _`adding default options`: 85 86How to change command line options defaults 87------------------------------------------------ 88 89It can be tedious to type the same series of command line options 90every time you use ``pytest``. For example, if you always want to see 91detailed info on skipped and xfailed tests, as well as have terser "dot" 92progress output, you can write it into a configuration file: 93 94.. code-block:: ini 95 96 # content of pytest.ini 97 # (or tox.ini or setup.cfg) 98 [pytest] 99 addopts = -rsxX -q 100 101Alternatively, you can set a PYTEST_ADDOPTS environment variable to add command 102line options while the environment is in use:: 103 104 export PYTEST_ADDOPTS="-rsxX -q" 105 106From now on, running ``pytest`` will add the specified options. 107 108 109 110Builtin configuration file options 111---------------------------------------------- 112 113.. confval:: minversion 114 115 Specifies a minimal pytest version required for running tests. 116 117 minversion = 2.1 # will fail if we run with pytest-2.0 118 119.. confval:: addopts 120 121 Add the specified ``OPTS`` to the set of command line arguments as if they 122 had been specified by the user. Example: if you have this ini file content: 123 124 .. code-block:: ini 125 126 [pytest] 127 addopts = --maxfail=2 -rf # exit after 2 failures, report fail info 128 129 issuing ``py.test test_hello.py`` actually means:: 130 131 py.test --maxfail=2 -rf test_hello.py 132 133 Default is to add no options. 134 135.. confval:: norecursedirs 136 137 Set the directory basename patterns to avoid when recursing 138 for test discovery. The individual (fnmatch-style) patterns are 139 applied to the basename of a directory to decide if to recurse into it. 140 Pattern matching characters:: 141 142 * matches everything 143 ? matches any single character 144 [seq] matches any character in seq 145 [!seq] matches any char not in seq 146 147 Default patterns are ``'.*', 'CVS', '_darcs', '{arch}', '*.egg'``. 148 Setting a ``norecursedirs`` replaces the default. Here is an example of 149 how to avoid certain directories: 150 151 .. code-block:: ini 152 153 # content of setup.cfg 154 [pytest] 155 norecursedirs = .svn _build tmp* 156 157 This would tell ``pytest`` to not look into typical subversion or 158 sphinx-build directories or into any ``tmp`` prefixed directory. 159 160.. confval:: testpaths 161 162 .. versionadded:: 2.8 163 164 Sets list of directories that should be searched for tests when 165 no specific directories, files or test ids are given in the command line when 166 executing pytest from the :ref:`rootdir <rootdir>` directory. 167 Useful when all project tests are in a known location to speed up 168 test collection and to avoid picking up undesired tests by accident. 169 170 .. code-block:: ini 171 172 # content of pytest.ini 173 [pytest] 174 testpaths = testing doc 175 176 This tells pytest to only look for tests in ``testing`` and ``doc`` 177 directories when executing from the root directory. 178 179.. confval:: python_files 180 181 One or more Glob-style file patterns determining which python files 182 are considered as test modules. 183 184.. confval:: python_classes 185 186 One or more name prefixes or glob-style patterns determining which classes 187 are considered for test collection. Here is an example of how to collect 188 tests from classes that end in ``Suite``: 189 190 .. code-block:: ini 191 192 # content of pytest.ini 193 [pytest] 194 python_classes = *Suite 195 196 Note that ``unittest.TestCase`` derived classes are always collected 197 regardless of this option, as ``unittest``'s own collection framework is used 198 to collect those tests. 199 200.. confval:: python_functions 201 202 One or more name prefixes or glob-patterns determining which test functions 203 and methods are considered tests. Here is an example of how 204 to collect test functions and methods that end in ``_test``: 205 206 .. code-block:: ini 207 208 # content of pytest.ini 209 [pytest] 210 python_functions = *_test 211 212 Note that this has no effect on methods that live on a ``unittest 213 .TestCase`` derived class, as ``unittest``'s own collection framework is used 214 to collect those tests. 215 216 See :ref:`change naming conventions` for more detailed examples. 217 218.. confval:: doctest_optionflags 219 220 One or more doctest flag names from the standard ``doctest`` module. 221 :doc:`See how py.test handles doctests <doctest>`. 222 223.. confval:: confcutdir 224 225 Sets a directory where search upwards for ``conftest.py`` files stops. 226 By default, pytest will stop searching for ``conftest.py`` files upwards 227 from ``pytest.ini``/``tox.ini``/``setup.cfg`` of the project if any, 228 or up to the file-system root. 229