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