From 598d881c9c21e47c00755b9a40e66aca8eec17d1 Mon Sep 17 00:00:00 2001
From: lovetheguitar <entry.force.0p@icloud.com>
Date: Fri, 21 Jun 2024 15:57:13 +0200
Subject: [PATCH] docs: document keyword argument support in marker expressions

---
 doc/en/example/markers.rst | 24 ++++++++++++++++++++++++
 doc/en/how-to/usage.rst    | 10 +++++++++-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/doc/en/example/markers.rst b/doc/en/example/markers.rst
index c04d2a078..33c5cf95f 100644
--- a/doc/en/example/markers.rst
+++ b/doc/en/example/markers.rst
@@ -25,10 +25,12 @@ You can "mark" a test function with custom metadata like this:
         pass  # perform some webtest test for your app
 
 
+    @pytest.mark.device(serial="123")
     def test_something_quick():
         pass
 
 
+    @pytest.mark.device(serial="abc")
     def test_another():
         pass
 
@@ -71,6 +73,28 @@ Or the inverse, running all tests except the webtest ones:
 
     ===================== 3 passed, 1 deselected in 0.12s ======================
 
+.. _`marker_keyword_expression_example`:
+
+Additionally, you can restrict a test run to only run tests matching one or multiple marker
+keyword arguments, e.g. to run only tests marked with ``device`` and the specific ``serial="123"``:
+
+.. code-block:: pytest
+
+    $ pytest -v -m 'device(serial="123")'
+    =========================== test session starts ============================
+    platform linux -- Python 3.x.y, pytest-8.x.y, pluggy-1.x.y -- $PYTHON_PREFIX/bin/python
+    cachedir: .pytest_cache
+    rootdir: /home/sweet/project
+    collecting ... collected 4 items / 3 deselected / 1 selected
+
+    test_server.py::test_something_quick PASSED                          [100%]
+
+    ===================== 1 passed, 3 deselected in 0.12s ======================
+
+.. note:: Only keyword argument matching is supported in marker expressions.
+
+.. note:: Only ``int``, (unescaped) ``str``, ``bool`` & ``None`` values are supported in marker expressions.
+
 Selecting tests based on their node ID
 --------------------------------------
 
diff --git a/doc/en/how-to/usage.rst b/doc/en/how-to/usage.rst
index 705fa009e..05ee04600 100644
--- a/doc/en/how-to/usage.rst
+++ b/doc/en/how-to/usage.rst
@@ -76,11 +76,19 @@ Specifying a specific parametrization of a test:
 
 **Run tests by marker expressions**
 
+To run all tests which are decorated with the ``@pytest.mark.slow`` decorator:
+
 .. code-block:: bash
 
     pytest -m slow
 
-Will run all tests which are decorated with the ``@pytest.mark.slow`` decorator.
+
+To run all tests which are decorated with the annotated ``@pytest.mark.slow(phase=1)`` decorator,
+with the ``phase`` keyword argument set to ``1``:
+
+.. code-block:: bash
+
+    pytest -m slow(phase=1)
 
 For more information see :ref:`marks <mark>`.