# 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.

## initialization: determining rootdir and inifile

New in version 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 inifiles. The determined rootdir and ini-file are printed as part of the pytest header. The rootdir is used for constructing “nodeids” during collection and may also be used by plugins to store project/testrun-specific information.

Here is the algorithm which finds the rootdir from `args`:

- determine the common ancestor directory for the specified `args`.
- 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. 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]` section.
- if no ini-file was found, look for `setup.py` upwards from the common ancestor directory to determine the `rootdir`.
- if no ini-file and no `setup.py` was found, use the already determined common ancestor as root directory. This allows to work with pytest in structures that are not part of a package and don’t have any particular ini-file configuration.

Note that 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:

    py.test path/to/testdir path/other/

will determine the common ancestor as `path` and then check for ini-files as follows:

    # first look for pytest.ini files
    path/pytest.ini
    path/setup.cfg  # must also contain [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

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

`minversion`

  Specifies a minimal pytest version required for running tests.

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

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

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

`testpaths`

  New in version 2.8.

  Sets list of directories that should be searched for tests when no specific directories or files are given in the command line when executing pytest from the rootdir directory. Useful when all project tests are in a known location to speed up test collection and to avoid picking up undesired tests by accident.

      # content of pytest.ini
      [pytest]
      testpaths = testing doc

  This tells pytest to only look for tests in `testing` and `doc` directories when executing from the root directory.

`python_files`

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

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

`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 Changing naming conventions for more detailed examples.

`doctest_optionflags`

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

`confcutdir`

  Sets a directory where search upwards for `conftest.py` files stops. By default, pytest will stop searching for `conftest.py` files upwards from `pytest.ini`/`tox.ini`/`setup.cfg` of the project if any, or up to the file-system root.