config: add native TOML configuration

Add support for using native TOML configuration, while maintaining full
backwards compatibility with the existing INI-based configuration
system.

In pyproject.toml, the native configuration is under ``[pytest.tool]``.
Also add support for ``pytest.toml``/``.pytest.toml`` files.

`--override-ini` always uses "ini" mode for compatibility.

Author: bluetech

changelog/13743.feature.rst

@@ -0,0 +1,37 @@
+Added support for native TOML configuration files.
+
+While pytest, since version 6, supports configuration in ``pyproject.toml`` files under ``[tool.pytest.ini_options]``,
+it does so in an "INI compatibility mode", where all configuration values are treated as strings or list of strings.
+Now, pytest supports the native TOML data model.
+
+In ``pyproject.toml``, the native TOML configuration is under the ``[tool.pytest]`` table.
+
+.. code-block:: toml
+
+    # pyproject.toml
+    [tool.pytest]
+    minversion = "9.0"
+    addopts = ["-ra", "-q"]
+    testpaths = [
+        "tests",
+        "integration",
+    ]
+
+The ``[tool.pytest.ini_options]`` table remains supported, but both tables cannot be used at the same time.
+
+If you prefer to use a separate configuration file, or don't use ``pyproject.toml``, you can use ``pytest.toml`` or ``.pytest.toml``:
+
+.. code-block:: toml
+
+    # pytest.toml or .pytest.toml
+    [pytest]
+    minversion = "9.0"
+    addopts = ["-ra", "-q"]
+    testpaths = [
+        "tests",
+        "integration",
+    ]
+
+The documentation now shows configuration snippets in both TOML and INI formats, in a tabbed interface.
+
+See :ref:`config file formats` for full details.

doc/en/deprecations.rst

@@ -847,6 +847,13 @@ XML file supports it.
 
 To use the new format, update your configuration file:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        junit_family = "xunit2"
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -857,6 +864,13 @@ To use the new format, update your configuration file:
 If you discover that your tooling does not support the new format, and want to keep using the
 legacy version, set the option to ``legacy`` instead:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        junit_family = "legacy"
+
 .. tab:: ini
 
     .. code-block:: ini

doc/en/example/markers.rst

@@ -239,6 +239,13 @@ Registering markers
 
 Registering markers for your test suite is simple:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        markers = ["webtest: mark a test as a webtest.", "slow: mark test as slow."]
+
 .. tab:: ini
 
     .. code-block:: ini

doc/en/example/pythoncollection.rst

@@ -90,6 +90,13 @@ Changing directory recursion
 
 You can set the :confval:`norecursedirs` option in a configuration file:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        norecursedirs = [".svn", "_build", "tmp*"]
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -109,6 +116,16 @@ the :confval:`python_files`, :confval:`python_classes` and
 :confval:`python_functions` in your :ref:`configuration file <config file formats>`.
 Here is an example:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        # Example 1: have pytest look for "check" instead of "test"
+        [pytest]
+        python_files = ["check_*.py"]
+        python_classes = ["Check"]
+        python_functions = ["*_check"]
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -154,6 +171,14 @@ The test collection would look like this:
 
 You can check for multiple glob patterns by adding a space between the patterns:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        # Example 2: have pytest look for files with "test" and "example"
+        [pytest]
+        python_files = ["test_*.py", "example_*.py"]
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -184,6 +209,13 @@ which would run the respective test module.  Like with
 other options, through a configuration file and the :confval:`addopts` option you
 can make this change more permanently:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        addopts = ["--pyargs"]
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -228,6 +260,13 @@ Customizing test collection
 
 You can easily instruct ``pytest`` to discover tests from every Python file:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        python_files = ["*.py"]
+
 .. tab:: ini
 
     .. code-block:: ini

doc/en/example/simple.rst

@@ -11,6 +11,13 @@ 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:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        addopts = ["-ra", "-q"]
+
 .. tab:: ini
 
     .. code-block:: ini

doc/en/explanation/goodpractices.rst

@@ -96,6 +96,13 @@ For new projects, we recommend to use ``importlib`` :ref:`import mode <import-mo
 (see which-import-mode_ for a detailed explanation).
 To this end, add the following to your configuration file:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        addopts = ["--import-mode=importlib"]
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -128,6 +135,13 @@ which are better explained in this excellent `blog post`_ by Ionel Cristian Măr
     or in a permanent manner by using the :confval:`pythonpath` configuration variable and adding the
     following to your configuration file:
 
+    .. tab:: toml
+
+        .. code-block:: toml
+
+            [pytest]
+            pythonpath = ["src"]
+
     .. tab:: ini
 
         .. code-block:: ini

doc/en/how-to/capture-warnings.rst

@@ -85,6 +85,18 @@ The same option can be set in the configuration file using the
 user warnings and specific deprecation warnings matching a regex, but will transform
 all other warnings into errors.
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        filterwarnings = [
+            "error",
+            "ignore::UserWarning",
+            # note the use of single quote below to denote "raw" strings in TOML
+            'ignore:function ham\(\) is deprecated:DeprecationWarning',
+        ]
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -194,6 +206,13 @@ Disabling warning capture entirely
 
 This plugin is enabled by default but can be disabled entirely in your configuration file with:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        addopts = ["-p", "no:warnings"]
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -224,6 +243,15 @@ those warnings.
 
 For example:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        filterwarnings = [
+            'ignore:.*U.*mode is deprecated:DeprecationWarning',
+        ]
+
 .. tab:: ini
 
     .. code-block:: ini

doc/en/how-to/doctest.rst

@@ -70,6 +70,13 @@ and functions, including from test modules:
 You can make these changes permanent in your project by
 putting them into a configuration file like this:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        addopts = ["--doctest-modules"]
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -85,6 +92,13 @@ The default encoding is **UTF-8**, but you can specify the encoding
 that will be used for those doctest files using the
 :confval:`doctest_encoding` configuration option:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        doctest_encoding = "latin1"
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -104,6 +118,13 @@ configuration file.
 For example, to make pytest ignore trailing whitespaces and ignore
 lengthy exception stack traces you can just write:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        doctest_optionflags = ["NORMALIZE_WHITESPACE", "IGNORE_EXCEPTION_DETAIL"]
+
 .. tab:: ini
 
     .. code-block:: ini

doc/en/how-to/fixtures.rst

@@ -1738,6 +1738,13 @@ and you may specify fixture usage at the test module level using :globalvar:`pyt
 It is also possible to put fixtures required by all tests in your project
 into a configuration file:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        usefixtures = ["cleandir"]
+
 .. tab:: ini
 
     .. code-block:: ini

doc/en/how-to/logging.rst

@@ -49,6 +49,14 @@ Shows failed tests like so:
 
 These options can also be customized through a configuration file:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        log_format = "%(asctime)s %(levelname)s %(message)s"
+        log_date_format = "%Y-%m-%d %H:%M:%S"
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -270,6 +278,13 @@ has been dropped when this feature was introduced, so if for that reason you
 still need ``pytest-catchlog`` you can disable the internal feature by
 adding to your configuration file:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        addopts = ["-p", "no:logging"]
+
 .. tab:: ini
 
     .. code-block:: ini
@@ -300,6 +315,14 @@ made in ``3.4`` after community feedback:
 If you want to partially restore the logging behavior of version ``3.3``, you can add this options to your configuration
 file:
 
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        log_cli = true
+        log_level = "NOTSET"
+
 .. tab:: ini
 
     .. code-block:: ini