basic test configuration
===================================

Command line options and configuration file settings
-----------------------------------------------------------------

You can get help on options and ini-config values by running::

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

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

how test configuration is read from setup/tox ini-files
--------------------------------------------------------

py.test searched for the first matching ini-style configuration file
in the directories of command line argument and the directories above.
It looks for filenames in this order::

    pytest.ini
    tox.ini
    setup.cfg

Searching stops when the first ``[pytest]`` section is found.
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 py.test run, the current working directory
is used to start the search.

builtin configuration file options
----------------------------------------------

.. confval:: minversion

   specifies a minimal pytest version needed 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 {args}``. Setting a ``norecurse``
   replaces the default.  Here is a customizing example for avoiding
   a different set of directories::

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

   This would tell py.test to not recurse into typical subversion or
   sphinx-build directories or into any ``tmp`` prefixed directory.