diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index cb94ca40068..863e6900643 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -1532,11 +1532,14 @@ passed multiple times. The expected format is ``name=value``. For example:: enable_assertion_pass_hook = true -.. confval:: faulthandler_timeout +.. confval:: faulthandler_exit_on_timeout - Dumps the tracebacks of all threads if a test takes longer than ``X`` seconds to run (including - fixture setup and teardown). Implemented using the :func:`faulthandler.dump_traceback_later` function, - so all caveats there apply. + Exit the pytest process after the per-test timeout is reached by passing + `exit=True` to the :func:`faulthandler.dump_traceback_later` function. This + is particularly useful to avoid wasting CI resources for test suites that + are prone to putting the main Python interpreter into a deadlock state. + + This option is set to 'false' by default. .. tab:: toml @@ -1544,6 +1547,7 @@ passed multiple times. The expected format is ``name=value``. For example:: [pytest] faulthandler_timeout = 5 + faulthandler_exit_on_timeout = true .. tab:: ini @@ -1551,18 +1555,15 @@ passed multiple times. The expected format is ``name=value``. For example:: [pytest] faulthandler_timeout = 5 - - For more information please refer to :ref:`faulthandler`. + faulthandler_exit_on_timeout = true -.. confval:: faulthandler_exit_on_timeout - Exit the pytest process after the per-test timeout is reached by passing - `exit=True` to the :func:`faulthandler.dump_traceback_later` function. This - is particularly useful to avoid wasting CI resources for test suites that - are prone to putting the main Python interpreter into a deadlock state. +.. confval:: faulthandler_timeout - This option is set to 'false' by default. + Dumps the tracebacks of all threads if a test takes longer than ``X`` seconds to run (including + fixture setup and teardown). Implemented using the :func:`faulthandler.dump_traceback_later` function, + so all caveats there apply. .. tab:: toml @@ -1570,7 +1571,6 @@ passed multiple times. The expected format is ``name=value``. For example:: [pytest] faulthandler_timeout = 5 - faulthandler_exit_on_timeout = true .. tab:: ini @@ -1578,9 +1578,9 @@ passed multiple times. The expected format is ``name=value``. For example:: [pytest] faulthandler_timeout = 5 - faulthandler_exit_on_timeout = true For more information please refer to :ref:`faulthandler`. + For more information please refer to :ref:`faulthandler`. .. confval:: filterwarnings @@ -1660,56 +1660,56 @@ passed multiple times. The expected format is ``name=value``. For example:: junit_family = xunit2 -.. confval:: junit_logging - - .. versionadded:: 3.5 - .. versionchanged:: 5.4 - ``log``, ``all``, ``out-err`` options added. +.. confval:: junit_log_passing_tests - Configures if captured output should be written to the JUnit XML file. Valid values are: + .. versionadded:: 4.6 - * ``log``: write only ``logging`` captured output. - * ``system-out``: write captured ``stdout`` contents. - * ``system-err``: write captured ``stderr`` contents. - * ``out-err``: write both captured ``stdout`` and ``stderr`` contents. - * ``all``: write captured ``logging``, ``stdout`` and ``stderr`` contents. - * ``no`` (the default): no captured output is written. + If ``junit_logging != "no"``, configures if the captured output should be written + to the JUnit XML file for **passing** tests. Default is ``True``. .. tab:: toml .. code-block:: toml [pytest] - junit_logging = "system-out" + junit_log_passing_tests = false .. tab:: ini .. code-block:: ini [pytest] - junit_logging = system-out + junit_log_passing_tests = False -.. confval:: junit_log_passing_tests +.. confval:: junit_logging - .. versionadded:: 4.6 + .. versionadded:: 3.5 + .. versionchanged:: 5.4 + ``log``, ``all``, ``out-err`` options added. - If ``junit_logging != "no"``, configures if the captured output should be written - to the JUnit XML file for **passing** tests. Default is ``True``. + Configures if captured output should be written to the JUnit XML file. Valid values are: + + * ``log``: write only ``logging`` captured output. + * ``system-out``: write captured ``stdout`` contents. + * ``system-err``: write captured ``stderr`` contents. + * ``out-err``: write both captured ``stdout`` and ``stderr`` contents. + * ``all``: write captured ``logging``, ``stdout`` and ``stderr`` contents. + * ``no`` (the default): no captured output is written. .. tab:: toml .. code-block:: toml [pytest] - junit_log_passing_tests = false + junit_logging = "system-out" .. tab:: ini .. code-block:: ini [pytest] - junit_log_passing_tests = False + junit_logging = system-out .. confval:: junit_suite_name @@ -1897,92 +1897,92 @@ passed multiple times. The expected format is ``name=value``. For example:: For more information, see :ref:`logging`. -.. confval:: log_file_mode +.. confval:: log_file_date_format - Sets the mode that the logging file is opened with. - The options are ``"w"`` to recreate the file (the default) or ``"a"`` to append to the file. + + + Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for the logging file. .. tab:: toml .. code-block:: toml [pytest] - log_file_mode = "a" + log_file_date_format = "%Y-%m-%d %H:%M:%S" .. tab:: ini .. code-block:: ini [pytest] - log_file_mode = a + log_file_date_format = %Y-%m-%d %H:%M:%S For more information, see :ref:`logging`. - -.. confval:: log_file_date_format +.. confval:: log_file_format - Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for the logging file. + Sets a :py:mod:`logging`-compatible string used to format logging messages redirected to the logging file. .. tab:: toml .. code-block:: toml [pytest] - log_file_date_format = "%Y-%m-%d %H:%M:%S" + log_file_format = "%(asctime)s %(levelname)s %(message)s" .. tab:: ini .. code-block:: ini [pytest] - log_file_date_format = %Y-%m-%d %H:%M:%S + log_file_format = %(asctime)s %(levelname)s %(message)s For more information, see :ref:`logging`. -.. confval:: log_file_format +.. confval:: log_file_level - Sets a :py:mod:`logging`-compatible string used to format logging messages redirected to the logging file. + Sets the minimum log message level that should be captured for the logging file. The integer value or + the names of the levels can be used. .. tab:: toml .. code-block:: toml [pytest] - log_file_format = "%(asctime)s %(levelname)s %(message)s" + log_file_level = "INFO" .. tab:: ini .. code-block:: ini [pytest] - log_file_format = %(asctime)s %(levelname)s %(message)s + log_file_level = INFO For more information, see :ref:`logging`. -.. confval:: log_file_level - +.. confval:: log_file_mode - Sets the minimum log message level that should be captured for the logging file. The integer value or - the names of the levels can be used. + Sets the mode that the logging file is opened with. + The options are ``"w"`` to recreate the file (the default) or ``"a"`` to append to the file. .. tab:: toml .. code-block:: toml [pytest] - log_file_level = "INFO" + log_file_mode = "a" .. tab:: ini .. code-block:: ini [pytest] - log_file_level = INFO + log_file_mode = a For more information, see :ref:`logging`. @@ -2261,6 +2261,160 @@ passed multiple times. The expected format is ``name=value``. For example:: required_plugins = pytest-django>=3.0.0,<4.0.0 pytest-html pytest-xdist>=1.0.0 +.. confval:: strict + + If set to ``true``, enable "strict mode", which enables the following options: + + * :confval:`strict_config` + * :confval:`strict_markers` + * :confval:`strict_parametrization_ids` + * :confval:`strict_xfail` + + Plugins may also enable their own strictness options. + + If you explicitly set an individual strictness option, it takes precedence over ``strict``. + + .. note:: + If pytest adds new strictness options in the future, they will also be enabled in strict mode. + Therefore, you should only enable strict mode if you use a pinned/locked version of pytest, + or if you want to proactively adopt new strictness options as they are added. + + .. tab:: toml + + .. code-block:: toml + + [pytest] + strict = true + + .. tab:: ini + + .. code-block:: ini + + [pytest] + strict = true + + .. versionadded:: 9.0 + + +.. confval:: strict_config + + If set to ``true``, any warnings encountered while parsing the ``pytest`` section of the configuration file will raise errors. + + .. tab:: toml + + .. code-block:: toml + + [pytest] + strict_config = true + + .. tab:: ini + + .. code-block:: ini + + [pytest] + strict_config = true + + You can also enable this option via the :confval:`strict` option. + + +.. confval:: strict_markers + + If set to ``true``, markers not registered in the ``markers`` section of the configuration file will raise errors. + + .. tab:: toml + + .. code-block:: toml + + [pytest] + strict_markers = true + + .. tab:: ini + + .. code-block:: ini + + [pytest] + strict_markers = true + + You can also enable this option via the :confval:`strict` option. + + +.. confval:: strict_parametrization_ids + + If set to ``true``, pytest emits an error if it detects non-unique parameter set IDs. + + If not set (the default), pytest automatically handles this by adding `0`, `1`, ... to duplicate IDs, + making them unique. + + .. tab:: toml + + .. code-block:: toml + + [pytest] + strict_parametrization_ids = true + + .. tab:: ini + + .. code-block:: ini + + [pytest] + strict_parametrization_ids = true + + You can also enable this option via the :confval:`strict` option. + + For example, + + .. code-block:: python + + import pytest + + + @pytest.mark.parametrize("letter", ["a", "a"]) + def test_letter_is_ascii(letter): + assert letter.isascii() + + will emit an error because both cases (parameter sets) have the same auto-generated ID "a". + + To fix the error, if you decide to keep the duplicates, explicitly assign unique IDs: + + .. code-block:: python + + import pytest + + + @pytest.mark.parametrize("letter", ["a", "a"], ids=["a0", "a1"]) + def test_letter_is_ascii(letter): + assert letter.isascii() + + See :func:`parametrize ` and :func:`pytest.param` for other ways to set IDs. + + +.. confval:: strict_xfail + + If set to ``true``, tests marked with ``@pytest.mark.xfail`` that actually succeed will by default fail the + test suite. + For more information, see :ref:`xfail strict tutorial`. + + .. tab:: toml + + .. code-block:: toml + + [pytest] + strict_xfail = true + + .. tab:: ini + + .. code-block:: ini + + [pytest] + strict_xfail = true + + You can also enable this option via the :confval:`strict` option. + + .. versionchanged:: 9.0 + Renamed from ``xfail_strict`` to ``strict_xfail``. + ``xfail_strict`` is accepted as an alias for ``strict_xfail``. + + .. confval:: testpaths Sets list of directories that should be searched for tests when @@ -2472,159 +2626,6 @@ passed multiple times. The expected format is ``name=value``. For example:: "auto" can be used to explicitly use the global verbosity level. -.. confval:: strict - - If set to ``true``, enable "strict mode", which enables the following options: - - * :confval:`strict_config` - * :confval:`strict_markers` - * :confval:`strict_xfail` - * :confval:`strict_parametrization_ids` - - Plugins may also enable their own strictness options. - - If you explicitly set an individual strictness option, it takes precedence over ``strict``. - - .. note:: - If pytest adds new strictness options in the future, they will also be enabled in strict mode. - Therefore, you should only enable strict mode if you use a pinned/locked version of pytest, - or if you want to proactively adopt new strictness options as they are added. - - .. tab:: toml - - .. code-block:: toml - - [pytest] - strict = true - - .. tab:: ini - - .. code-block:: ini - - [pytest] - strict = true - - .. versionadded:: 9.0 - - -.. confval:: strict_xfail - - If set to ``true``, tests marked with ``@pytest.mark.xfail`` that actually succeed will by default fail the - test suite. - For more information, see :ref:`xfail strict tutorial`. - - .. tab:: toml - - .. code-block:: toml - - [pytest] - strict_xfail = true - - .. tab:: ini - - .. code-block:: ini - - [pytest] - strict_xfail = true - - You can also enable this option via the :confval:`strict` option. - - .. versionchanged:: 9.0 - Renamed from ``xfail_strict`` to ``strict_xfail``. - ``xfail_strict`` is accepted as an alias for ``strict_xfail``. - - -.. confval:: strict_config - - If set to ``true``, any warnings encountered while parsing the ``pytest`` section of the configuration file will raise errors. - - .. tab:: toml - - .. code-block:: toml - - [pytest] - strict_config = true - - .. tab:: ini - - .. code-block:: ini - - [pytest] - strict_config = true - - You can also enable this option via the :confval:`strict` option. - - -.. confval:: strict_markers - - If set to ``true``, markers not registered in the ``markers`` section of the configuration file will raise errors. - - .. tab:: toml - - .. code-block:: toml - - [pytest] - strict_markers = true - - .. tab:: ini - - .. code-block:: ini - - [pytest] - strict_markers = true - - You can also enable this option via the :confval:`strict` option. - -.. confval:: strict_parametrization_ids - - If set to ``true``, pytest emits an error if it detects non-unique parameter set IDs. - - If not set (the default), pytest automatically handles this by adding `0`, `1`, ... to duplicate IDs, - making them unique. - - .. tab:: toml - - .. code-block:: toml - - [pytest] - strict_parametrization_ids = true - - .. tab:: ini - - .. code-block:: ini - - [pytest] - strict_parametrization_ids = true - - You can also enable this option via the :confval:`strict` option. - - For example, - - .. code-block:: python - - import pytest - - - @pytest.mark.parametrize("letter", ["a", "a"]) - def test_letter_is_ascii(letter): - assert letter.isascii() - - will emit an error because both cases (parameter sets) have the same auto-generated ID "a". - - To fix the error, if you decide to keep the duplicates, explicitly assign unique IDs: - - .. code-block:: python - - import pytest - - - @pytest.mark.parametrize("letter", ["a", "a"], ids=["a0", "a1"]) - def test_letter_is_ascii(letter): - assert letter.isascii() - - See :func:`parametrize ` and :func:`pytest.param` for other ways to set IDs. - - .. _`command-line-flags`: Command-line Flags