Basic test 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::

    py.test -h   # prints options _and_ config file settings

This will display command line and configuration file settings
which were registered by installed plugins.

.. _inifiles:

How test configuration is read from configuration INI-files
-------------------------------------------------------------

``pytest`` searches for the first matching ini-style configuration file
in the directories of command line argument and the directories above.
It looks for file basenames in this order::

    pytest.ini
    tox.ini
    setup.cfg

Searching stops when the first ``[pytest]`` section is found in any of
these files.  There is no merging of configuration values from multiple
files.  Example::

    py.test path/to/testdir

will look in the following dirs for a config file::

    path/to/testdir/pytest.ini
    path/to/testdir/tox.ini
    path/to/testdir/setup.cfg
    path/to/pytest.ini
    path/to/tox.ini
    path/to/setup.cfg
    ... # up until root of filesystem

If argument is provided to a ``pytest`` run, the current working directory
is used to start the search.

.. _`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::

    # content of pytest.ini
    # (or tox.ini or setup.cfg)
    [pytest]
    addopts = -rsxX -q

Alternatively, you can set a PYTEST_ADDOPTS environment variable to add command
line options while the environment is in use::

    export PYTEST_ADDOPTS="-rsxX -q"

From now on, running ``pytest`` will add the specified options.

Builtin configuration file options
----------------------------------------------

.. confval:: minversion

   Specifies a minimal pytest version required for running tests.

        minversion = 2.1  # will fail if we run with pytest-2.0

.. confval:: addopts

   Add the specified ``OPTS`` to the set of command line arguments as if they
   had been specified by the user. Example: if you have this ini file content::

       [pytest]
       addopts = --maxfail=2 -rf  # exit after 2 failures, report fail info

   issuing ``py.test test_hello.py`` actually means::

       py.test --maxfail=2 -rf test_hello.py

   Default is to add no options.

.. confval:: norecursedirs

   Set the directory basename patterns to avoid when recursing
   for test discovery.  The individual (fnmatch-style) patterns are
   applied to the basename of a directory to decide if to recurse into it.
   Pattern matching characters::

        *       matches everything
        ?       matches any single character
        [seq]   matches any character in seq
        [!seq]  matches any char not in seq

   Default patterns are ``'.*', 'CVS', '_darcs', '{arch}', '*.egg'``.
   Setting a ``norecursedirs`` replaces the default.  Here is an example of
   how to avoid certain directories::

    # content of setup.cfg
    [pytest]
    norecursedirs = .svn _build tmp*

   This would tell ``pytest`` to not look into typical subversion or
   sphinx-build directories or into any ``tmp`` prefixed directory.

.. confval:: python_files

   One or more Glob-style file patterns determining which python files
   are considered as test modules.

.. confval:: python_classes

   One or more name prefixes or glob-style patterns determining which classes
   are considered for test collection. Here is an example of how to collect
   tests from classes that end in ``Suite``::

    # content of pytest.ini
    [pytest]
    python_classes = *Suite

   Note that ``unittest.TestCase`` derived classes are always collected
   regardless of this option, as ``unittest``'s own collection framework is used
   to collect those tests.

.. confval:: python_functions

   One or more name prefixes or glob-patterns determining which test functions
   and methods are considered tests. Here is an example of how
   to collect test functions and methods that end in ``_test``::

    # content of pytest.ini
    [pytest]
    python_functions = *_test

   Note that this has no effect on methods that live on a ``unittest
   .TestCase`` derived class, as ``unittest``'s own collection framework is used
   to collect those tests.

   See :ref:`change naming conventions` for more detailed examples.

.. confval:: doctest_optionflags

   One or more doctest flag names from the standard ``doctest`` module.
   :doc:`See how py.test handles doctests <doctest>`.