Merge pull request #3353 from nicoddemus/fixture-param-marks-docs

Add docs about using pytest.param in parametrized fixtures

Author: RonnyPfannschmidt

_pytest/mark/__init__.py

@@ -20,7 +20,8 @@ class MarkerError(Exception):
 
 
 def param(*values, **kw):
-    """Specify a parameter in a `pytest.mark.parametrize`_ call.
+    """Specify a parameter in `pytest.mark.parametrize`_ calls or
+    :ref:`parametrized fixtures <fixture-parametrize-marks>`.
 
     .. code-block:: python
 

doc/en/example/reportingdemo.rst

@@ -358,7 +358,7 @@ get on the terminal - we are working on that)::
     >   int(s)
     E   ValueError: invalid literal for int() with base 10: 'qwe'
     
-    <0-codegen $PYTHON_PREFIX/lib/python3.5/site-packages/_pytest/python_api.py:609>:1: ValueError
+    <0-codegen $PYTHON_PREFIX/lib/python3.5/site-packages/_pytest/python_api.py:613>:1: ValueError
     ______________________ TestRaises.test_raises_doesnt _______________________
     
     self = <failure_demo.TestRaises object at 0xdeadbeef>

doc/en/fixture.rst

@@ -623,6 +623,40 @@ Running the above tests results in the following test IDs being used::
    
    ======================= no tests ran in 0.12 seconds =======================
 
+.. _`fixture-parametrize-marks`:
+
+Using marks with parametrized fixtures
+--------------------------------------
+
+:func:`pytest.param` can be used to apply marks in values sets of parametrized fixtures in the same way
+that they can be used with :ref:`@pytest.mark.parametrize <@pytest.mark.parametrize>`.
+
+Example::
+
+    # content of test_fixture_marks.py
+    import pytest
+    @pytest.fixture(params=[0, 1, pytest.param(2, marks=pytest.mark.skip)])
+    def data_set(request):
+        return request.param
+
+    def test_data(data_set):
+        pass
+
+Running this test will *skip* the invocation of ``data_set`` with value ``2``::
+
+    $ pytest test_fixture_marks.py -v
+    =========================== test session starts ============================
+    platform linux -- Python 3.x.y, pytest-3.x.y, py-1.x.y, pluggy-0.x.y -- $PYTHON_PREFIX/bin/python3.5
+    cachedir: .pytest_cache
+    rootdir: $REGENDOC_TMPDIR, inifile:
+    collecting ... collected 3 items
+    
+    test_fixture_marks.py::test_data[0] PASSED                           [ 33%]
+    test_fixture_marks.py::test_data[1] PASSED                           [ 66%]
+    test_fixture_marks.py::test_data[2] SKIPPED                          [100%]
+    
+    =================== 2 passed, 1 skipped in 0.12 seconds ====================
+
 .. _`interdependent fixtures`:
 
 Modularity: using fixtures from a fixture function

doc/en/warnings.rst

@@ -25,14 +25,14 @@ Running pytest now produces this output::
     platform linux -- Python 3.x.y, pytest-3.x.y, py-1.x.y, pluggy-0.x.y
     rootdir: $REGENDOC_TMPDIR, inifile:
     collected 1 item
-
+    
     test_show_warnings.py .                                              [100%]
-
+    
     ============================= warnings summary =============================
     test_show_warnings.py::test_one
       $REGENDOC_TMPDIR/test_show_warnings.py:4: UserWarning: api v1, should use functions from v2
         warnings.warn(UserWarning("api v1, should use functions from v2"))
-
+    
     -- Docs: http://doc.pytest.org/en/latest/warnings.html
     =================== 1 passed, 1 warnings in 0.12 seconds ===================
 
@@ -45,17 +45,17 @@ them into errors::
     F                                                                    [100%]
     ================================= FAILURES =================================
     _________________________________ test_one _________________________________
-
+    
         def test_one():
     >       assert api_v1() == 1
-
-    test_show_warnings.py:8:
-    _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
-
+    
+    test_show_warnings.py:8: 
+    _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
+    
         def api_v1():
     >       warnings.warn(UserWarning("api v1, should use functions from v2"))
     E       UserWarning: api v1, should use functions from v2
-
+    
     test_show_warnings.py:4: UserWarning
     1 failed in 0.12 seconds