From af5e9238c895e51b583a6a8b4517355ce0dd7b85 Mon Sep 17 00:00:00 2001
From: Daw-Ran Liou <dawran6@gmail.com>
Date: Sat, 28 Oct 2017 14:14:37 -0700
Subject: [PATCH] Document pytest.param

Append example for pytest.param in the example/parametrize document.
---
 AUTHORS                        |  1 +
 changelog/2658.doc             |  1 +
 doc/en/example/parametrize.rst | 50 ++++++++++++++++++++++++++++++++++
 3 files changed, 52 insertions(+)
 create mode 100644 changelog/2658.doc

diff --git a/AUTHORS b/AUTHORS
index 6e341d64e..204e5150e 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -46,6 +46,7 @@ Dave Hunt
 David Díaz-Barquero
 David Mohr
 David Vierra
+Daw-Ran Liou
 Denis Kirisov
 Diego Russo
 Dmitry Dygalo
diff --git a/changelog/2658.doc b/changelog/2658.doc
new file mode 100644
index 000000000..2da7f3d6c
--- /dev/null
+++ b/changelog/2658.doc
@@ -0,0 +1 @@
+Append example for pytest.param in the example/parametrize document.
\ No newline at end of file
diff --git a/doc/en/example/parametrize.rst b/doc/en/example/parametrize.rst
index ffeb5a951..1a8de235a 100644
--- a/doc/en/example/parametrize.rst
+++ b/doc/en/example/parametrize.rst
@@ -485,4 +485,54 @@ of our ``test_func1`` was skipped.  A few notes:
   values as well.
 
 
+Set marks or test ID for individual parametrized test
+--------------------------------------------------------------------
 
+Use ``pytest.param`` to apply marks or set test ID to individual parametrized test.
+For example::
+
+    # content of test_pytest_param_example.py
+    import pytest
+    @pytest.mark.parametrize('test_input,expected', [
+        ('3+5', 8),
+        pytest.param('1+7', 8,
+                     marks=pytest.mark.basic),
+        pytest.param('2+4', 6,
+                     marks=pytest.mark.basic,
+                     id='basic_2+4'),
+        pytest.param('6*9', 42,
+                     marks=[pytest.mark.basic, pytest.mark.xfail],
+                     id='basic_6*9'),
+    ])
+    def test_eval(test_input, expected):
+        assert eval(test_input) == expected
+    
+In this example, we have 4 parametrized tests. Except for the first test,
+we mark the rest three parametrized tests with the custom marker ``basic``,
+and for the fourth test we also use the built-in mark ``xfail`` to indicate this 
+test is expected to fail. For explicitness, we set test ids for some tests.
+
+Then run ``pytest`` with verbose mode and with only the ``basic`` marker::
+
+    pytest -v -m basic
+    ============================================ test session starts =============================================
+    platform linux -- Python 3.x.y, pytest-3.x.y, py-1.x.y, pluggy-0.x.y
+    rootdir: $REGENDOC_TMPDIR, inifile:
+    collected 4 items
+
+    test_pytest_param_example.py::test_eval[1+7-8] PASSED
+    test_pytest_param_example.py::test_eval[basic_2+4] PASSED
+    test_pytest_param_example.py::test_eval[basic_6*9] xfail
+    ========================================== short test summary info ===========================================
+    XFAIL test_pytest_param_example.py::test_eval[basic_6*9]
+
+    ============================================= 1 tests deselected =============================================
+
+As the result:
+
+- Four tests were collected
+- One test was deselected because it doesn't have the ``basic`` mark.
+- Three tests with the ``basic`` mark was selected.
+- The test ``test_eval[1+7-8]`` passed, but the name is autogenerated and confusing.
+- The test ``test_eval[basic_2+4]`` passed.
+- The test ``test_eval[basic_6*9]`` was expected to fail and did fail.