174 lines
6.0 KiB
ReStructuredText
174 lines
6.0 KiB
ReStructuredText
Configuration
|
|
=============
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
pytest -h # prints options _and_ config file settings
|
|
|
|
This will display command line and configuration file settings
|
|
which were registered by installed plugins.
|
|
|
|
.. _rootdir:
|
|
.. _inifiles:
|
|
|
|
Initialization: determining rootdir and inifile
|
|
-----------------------------------------------
|
|
|
|
.. versionadded:: 2.7
|
|
|
|
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 ``pytest`` uses ``rootdir`` for:
|
|
|
|
* Construct *nodeids* during collection; each test is assigned
|
|
a unique *nodeid* which is rooted at the ``rootdir`` and 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 :ref:`cache <cache>` plugin creates a ``.pytest_cache`` subdirectory
|
|
in ``rootdir`` to store its cross-test run state.
|
|
|
|
Important to emphasize that ``rootdir`` is **NOT** used to modify ``sys.path``/``PYTHONPATH`` or
|
|
influence how modules are imported. See :ref:`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
|
|
with ``addopts`` in a ``pytest.ini`` file.
|
|
|
|
Finding the ``rootdir``
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Here is the algorithm which finds the rootdir from ``args``:
|
|
|
|
- determine the common ancestor directory for the specified ``args`` that 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 ``pytest.ini``, ``tox.ini`` and ``setup.cfg`` files 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.py`` upwards from the common
|
|
ancestor directory to determine the ``rootdir``.
|
|
|
|
- if no ``setup.py`` was found, look for ``pytest.ini``, ``tox.ini`` and
|
|
``setup.cfg`` in each of the specified ``args`` and 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.
|
|
|
|
If no ``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
|
|
``pytest --log-output ../../test.log args``. Then ``args`` is mandatory,
|
|
otherwise pytest uses the folder of test.log for rootdir determination
|
|
(see also `issue 1435 <https://github.com/pytest-dev/pytest/issues/1435>`_).
|
|
A dot ``.`` for referencing to the current working directory is also
|
|
possible.
|
|
|
|
Note that an existing ``pytest.ini`` file will always be considered a match,
|
|
whereas ``tox.ini`` and ``setup.cfg`` will only match if they contain a
|
|
``[pytest]`` or ``[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
|
|
contain a ``[pytest]`` section).
|
|
|
|
The ``config`` object will subsequently carry these attributes:
|
|
|
|
- ``config.rootdir``: the determined root directory, guaranteed to exist.
|
|
|
|
- ``config.inifile``: the determined ini-file, may be ``None``.
|
|
|
|
The rootdir is used a reference directory for constructing test
|
|
addresses ("nodeids") and can be used also by plugins for storing
|
|
per-testrun information.
|
|
|
|
Example:
|
|
|
|
.. code-block:: bash
|
|
|
|
pytest path/to/testdir path/other/
|
|
|
|
will determine the common ancestor as ``path`` and then
|
|
check for ini-files as follows:
|
|
|
|
.. code-block:: text
|
|
|
|
# first look for pytest.ini files
|
|
path/pytest.ini
|
|
path/setup.cfg # must also contain [tool:pytest] section to match
|
|
path/tox.ini # must also contain [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`:
|
|
.. _`adding default options`:
|
|
|
|
|
|
|
|
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:
|
|
|
|
.. code-block:: ini
|
|
|
|
# content of pytest.ini or tox.ini
|
|
# setup.cfg files should use [tool:pytest] section instead
|
|
[pytest]
|
|
addopts = -ra -q
|
|
|
|
Alternatively, you can set a ``PYTEST_ADDOPTS`` environment variable to add command
|
|
line options while the environment is in use:
|
|
|
|
.. code-block:: bash
|
|
|
|
export PYTEST_ADDOPTS="-v"
|
|
|
|
Here's how the command-line is built in the presence of ``addopts`` or the environment variable:
|
|
|
|
.. code-block:: text
|
|
|
|
<pytest.ini:addopts> $PYTEST_ADDOPTS <extra command-line arguments>
|
|
|
|
So if the user executes in the command-line:
|
|
|
|
.. code-block:: bash
|
|
|
|
pytest -m slow
|
|
|
|
The actual command line executed is:
|
|
|
|
.. code-block:: bash
|
|
|
|
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 ``-v`` overwrites ``-q``.
|
|
|
|
|
|
Builtin configuration file options
|
|
----------------------------------------------
|
|
|
|
For the full list of options consult the :ref:`reference documentation <ini options ref>`.
|