Merge pull request #13852 from bluetech/strict-good-practice

doc: add "Use pytest's strict mode" to good practices

Author: bluetech

changelog/13823.feature.rst

@@ -1,10 +1,18 @@
 Added a :confval:`strict` configuration option to enable all strictness-related options.
 
-When set to ``True``, the :confval:`strict` option currently enables :confval:`strict_config`,
-:confval:`strict_markers`, :confval:`strict_xfail`, and :confval:`strict_parametrization_ids`.
+When set to ``true``, the :confval:`strict` option currently enables
+
+* :confval:`strict_config`
+* :confval:`strict_markers`
+* :confval:`strict_parametrization_ids`
+* :confval:`strict_xfail`
 
 The individual strictness options can be explicitly set to override the global :confval:`strict` setting.
 
-If new strictness options are added in the future, they will also be automatically enabled by :confval:`strict`.
-Therefore, we only recommend setting ``strict=True`` if you're using a locked version of pytest,
+The previously-deprecated ``--strict`` command-line flag now enables strict mode.
+
+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.
+
+See :ref:`strict mode` for more details.

doc/en/explanation/goodpractices.rst

@@ -329,3 +329,75 @@ A list of the lints detected by flake8-pytest-style can be found on its `PyPI pa
 .. note::
 
     flake8-pytest-style is not an official pytest project. Some of the rules enforce certain style choices, such as using `@pytest.fixture()` over `@pytest.fixture`, but you can configure the plugin to fit your preferred style.
+
+.. _`strict mode`:
+
+Using pytest's strict mode
+--------------------------
+
+.. versionadded:: 9.0
+
+Pytest contains a set of configuration options that make it more strict.
+The options are off by default for compatibility or other reasons,
+but you should enable them if you can.
+
+You can enable all of the strictness options at once by setting the :confval:`strict` configuration option:
+
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        strict = true
+
+.. tab:: ini
+
+    .. code-block:: ini
+
+        [pytest]
+        strict = true
+
+See the :confval:`strict` documentation for the options it enables and their effect.
+
+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.
+If you don't want to automatically pick up new options, you can enable options individually::
+
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        strict_config = true
+        strict_markers = true
+        strict_parametrization_ids = true
+        strict_xfail = true
+
+.. tab:: ini
+
+    .. code-block:: ini
+
+        [pytest]
+        strict_config = true
+        strict_markers = true
+        strict_parametrization_ids = true
+        strict_xfail = true
+
+If you want to use strict mode but having trouble with a specific option, you can turn it off individually::
+
+.. tab:: toml
+
+    .. code-block:: toml
+
+        [pytest]
+        strict = true
+        strict_parametrization_ids = false
+
+.. tab:: ini
+
+    .. code-block:: ini
+
+        [pytest]
+        strict = true
+        strict_parametrization_ids = false

doc/en/reference/reference.rst

@@ -2474,7 +2474,7 @@ passed multiple times. The expected format is ``name=value``. For example::
 
 .. confval:: strict
 
-    If set to ``true``, enables all strictness options:
+    If set to ``true``, enable "strict mode", which enables the following options:
 
     * :confval:`strict_config`
     * :confval:`strict_markers`
@@ -2486,16 +2486,16 @@ passed multiple times. The expected format is ``name=value``. For example::
     If you explicitly set an individual strictness option, it takes precedence over ``strict``.
 
     .. note::
-        If new strictness options are added to pytest in the future, they will also be enabled by ``strict``.
-        We therefore only recommend using this option when using a locked version of pytest,
+        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]
-            xfail_strict = true
+            strict = true
 
     .. tab:: ini