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 ----------------------------------------------- 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 ` 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 `_). 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 as 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_ADDOPTS 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 `.