From 8243900960b23e54623e2aaf2b8a3f7e529f6366 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Wed, 7 Mar 2018 20:45:41 -0300 Subject: [PATCH] Move definition of ini options to reference --- doc/en/customize.rst | 220 +----------------------------------------- doc/en/reference.rst | 224 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 225 insertions(+), 219 deletions(-) diff --git a/doc/en/customize.rst b/doc/en/customize.rst index 9fe094ba1..92c4e2119 100644 --- a/doc/en/customize.rst +++ b/doc/en/customize.rst @@ -152,222 +152,4 @@ above will show verbose output because ``-v`` overwrites ``-q``. Builtin configuration file options ---------------------------------------------- -Here is a list of builtin configuration options that may be written in a ``pytest.ini``, ``tox.ini`` or ``setup.cfg`` -file, usually located at the root of your repository. All options must be under a ``[pytest]`` section -(``[tool:pytest]`` for ``setup.cfg`` files). - -Configuration file options may be overwritten in the command-line by using ``-o/--override``, which can also be -passed multiple times. The expected format is ``name=value``. For example:: - - pytest -o console_output_style=classic -o cache_dir=/tmp/mycache - - -.. confval:: minversion - - Specifies a minimal pytest version required for running tests. - - .. code-block:: ini - - # content of pytest.ini - [pytest] - minversion = 3.0 # will fail if we run with pytest-2.8 - -.. 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: - - .. code-block:: ini - - # content of pytest.ini - [pytest] - addopts = --maxfail=2 -rf # exit after 2 failures, report fail info - - issuing ``pytest test_hello.py`` actually means:: - - pytest --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 ``'.*', 'build', 'dist', 'CVS', '_darcs', '{arch}', '*.egg', 'venv'``. - Setting a ``norecursedirs`` replaces the default. Here is an example of - how to avoid certain directories: - - .. code-block:: ini - - # content of pytest.ini - [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. - - Additionally, ``pytest`` will attempt to intelligently identify and ignore a - virtualenv by the presence of an activation script. Any directory deemed to - be the root of a virtual environment will not be considered during test - collection unless ``‑‑collect‑in‑virtualenv`` is given. Note also that - ``norecursedirs`` takes precedence over ``‑‑collect‑in‑virtualenv``; e.g. if - you intend to run tests in a virtualenv with a base directory that matches - ``'.*'`` you *must* override ``norecursedirs`` in addition to using the - ``‑‑collect‑in‑virtualenv`` flag. - -.. confval:: testpaths - - .. versionadded:: 2.8 - - Sets list of directories that should be searched for tests when - no specific directories, files or test ids are given in the command line when - executing pytest from the :ref:`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. - - .. code-block:: ini - - # 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. - -.. confval:: python_files - - One or more Glob-style file patterns determining which python files - are considered as test modules. By default, pytest will consider - any file matching with ``test_*.py`` and ``*_test.py`` globs as a test - module. - -.. confval:: python_classes - - One or more name prefixes or glob-style patterns determining which classes - are considered for test collection. By default, pytest will consider any - class prefixed with ``Test`` as a test collection. Here is an example of how - to collect tests from classes that end in ``Suite``: - - .. code-block:: ini - - # 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. By default, pytest will consider any - function prefixed with ``test`` as a test. Here is an example of how - to collect test functions and methods that end in ``_test``: - - .. code-block:: ini - - # 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 pytest handles doctests `. - -.. confval:: 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. - - -.. confval:: filterwarnings - - .. versionadded:: 3.1 - - Sets a list of filters and actions that should be taken for matched - warnings. By default all warnings emitted during the test session - will be displayed in a summary at the end of the test session. - - .. code-block:: ini - - # content of pytest.ini - [pytest] - filterwarnings = - error - ignore::DeprecationWarning - - This tells pytest to ignore deprecation warnings and turn all other warnings - into errors. For more information please refer to :ref:`warnings`. - -.. confval:: cache_dir - - .. versionadded:: 3.2 - - Sets a directory where stores content of cache plugin. Default directory is - ``.cache`` which is created in :ref:`rootdir `. Directory may be - relative or absolute path. If setting relative path, then directory is created - relative to :ref:`rootdir `. Additionally path may contain environment - variables, that will be expanded. For more information about cache plugin - please refer to :ref:`cache_provider`. - - -.. confval:: console_output_style - - .. versionadded:: 3.3 - - Sets the console output style while running tests: - - * ``classic``: classic pytest output. - * ``progress``: like classic pytest output, but with a progress indicator. - - The default is ``progress``, but you can fallback to ``classic`` if you prefer or - the new mode is causing unexpected problems: - - .. code-block:: ini - - # content of pytest.ini - [pytest] - console_output_style = classic - - -.. confval:: empty_parameter_set_mark - - .. versionadded:: 3.4 - - Allows to pick the action for empty parametersets in parameterization - - * ``skip`` skips tests with a empty parameterset (default) - * ``xfail`` marks tests with a empty parameterset as xfail(run=False) - - .. code-block:: ini - - # content of pytest.ini - [pytest] - empty_parameter_set_mark = xfail - - .. note:: - - The default value of this option is planned to change to ``xfail`` in future releases - as this is considered less error prone, see `#3155`_ for more details. - - - -.. _`#3155`: https://github.com/pytest-dev/pytest/issues/3155 +For the full list of options consult the :ref:`reference documentation `. diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 3086f9be7..a027d5c9e 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -814,3 +814,227 @@ This is not meant to be set by users, but is set by pytest internally with the n processes can inspect it, see :ref:`pytest current test env` for more information. +.. _`ini options ref`: + +Configuration Options +--------------------- + +Here is a list of builtin configuration options that may be written in a ``pytest.ini``, ``tox.ini`` or ``setup.cfg`` +file, usually located at the root of your repository. All options must be under a ``[pytest]`` section +(``[tool:pytest]`` for ``setup.cfg`` files). + +Configuration file options may be overwritten in the command-line by using ``-o/--override``, which can also be +passed multiple times. The expected format is ``name=value``. For example:: + + pytest -o console_output_style=classic -o cache_dir=/tmp/mycache + + +.. confval:: minversion + + Specifies a minimal pytest version required for running tests. + + .. code-block:: ini + + # content of pytest.ini + [pytest] + minversion = 3.0 # will fail if we run with pytest-2.8 + +.. 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: + + .. code-block:: ini + + # content of pytest.ini + [pytest] + addopts = --maxfail=2 -rf # exit after 2 failures, report fail info + + issuing ``pytest test_hello.py`` actually means:: + + pytest --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 ``'.*', 'build', 'dist', 'CVS', '_darcs', '{arch}', '*.egg', 'venv'``. + Setting a ``norecursedirs`` replaces the default. Here is an example of + how to avoid certain directories: + + .. code-block:: ini + + # content of pytest.ini + [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. + + Additionally, ``pytest`` will attempt to intelligently identify and ignore a + virtualenv by the presence of an activation script. Any directory deemed to + be the root of a virtual environment will not be considered during test + collection unless ``‑‑collect‑in‑virtualenv`` is given. Note also that + ``norecursedirs`` takes precedence over ``‑‑collect‑in‑virtualenv``; e.g. if + you intend to run tests in a virtualenv with a base directory that matches + ``'.*'`` you *must* override ``norecursedirs`` in addition to using the + ``‑‑collect‑in‑virtualenv`` flag. + +.. confval:: testpaths + + .. versionadded:: 2.8 + + Sets list of directories that should be searched for tests when + no specific directories, files or test ids are given in the command line when + executing pytest from the :ref:`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. + + .. code-block:: ini + + # 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. + +.. confval:: python_files + + One or more Glob-style file patterns determining which python files + are considered as test modules. By default, pytest will consider + any file matching with ``test_*.py`` and ``*_test.py`` globs as a test + module. + +.. confval:: python_classes + + One or more name prefixes or glob-style patterns determining which classes + are considered for test collection. By default, pytest will consider any + class prefixed with ``Test`` as a test collection. Here is an example of how + to collect tests from classes that end in ``Suite``: + + .. code-block:: ini + + # 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. By default, pytest will consider any + function prefixed with ``test`` as a test. Here is an example of how + to collect test functions and methods that end in ``_test``: + + .. code-block:: ini + + # 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 pytest handles doctests `. + +.. confval:: 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. + + +.. confval:: filterwarnings + + .. versionadded:: 3.1 + + Sets a list of filters and actions that should be taken for matched + warnings. By default all warnings emitted during the test session + will be displayed in a summary at the end of the test session. + + .. code-block:: ini + + # content of pytest.ini + [pytest] + filterwarnings = + error + ignore::DeprecationWarning + + This tells pytest to ignore deprecation warnings and turn all other warnings + into errors. For more information please refer to :ref:`warnings`. + +.. confval:: cache_dir + + .. versionadded:: 3.2 + + Sets a directory where stores content of cache plugin. Default directory is + ``.cache`` which is created in :ref:`rootdir `. Directory may be + relative or absolute path. If setting relative path, then directory is created + relative to :ref:`rootdir `. Additionally path may contain environment + variables, that will be expanded. For more information about cache plugin + please refer to :ref:`cache_provider`. + + +.. confval:: console_output_style + + .. versionadded:: 3.3 + + Sets the console output style while running tests: + + * ``classic``: classic pytest output. + * ``progress``: like classic pytest output, but with a progress indicator. + + The default is ``progress``, but you can fallback to ``classic`` if you prefer or + the new mode is causing unexpected problems: + + .. code-block:: ini + + # content of pytest.ini + [pytest] + console_output_style = classic + + +.. confval:: empty_parameter_set_mark + + .. versionadded:: 3.4 + + Allows to pick the action for empty parametersets in parameterization + + * ``skip`` skips tests with a empty parameterset (default) + * ``xfail`` marks tests with a empty parameterset as xfail(run=False) + + .. code-block:: ini + + # content of pytest.ini + [pytest] + empty_parameter_set_mark = xfail + + .. note:: + + The default value of this option is planned to change to ``xfail`` in future releases + as this is considered less error prone, see `#3155`_ for more details. + + + +.. _`#3155`: https://github.com/pytest-dev/pytest/issues/3155