Merged in pfctdayelise/pytest/issue351 (pull request #161)

Fixes issue351: Add ability to specify parametrize ids as a
callable, to generate custom test ids. + tests, docs

Hg branch merge

doc/en/example/parametrize.txt

@@ -68,6 +68,81 @@ let's run the full monty::
 As expected when running the full range of ``param1`` values
 we'll get an error on the last one.
 
+
+Different options for test IDs
+------------------------------------
+
+pytest will build a string that is the test ID for each set of values in a
+parametrized test. These IDs can be used with ``-k`` to select specific cases
+to run, and they will also identify the specific case when one is failing.
+Running pytest with ``--collect-only`` will show the generated IDs.
+
+Numbers, strings, booleans and None will have their usual string representation
+used in the test ID. For other objects, pytest will make a string based on
+the argument name::
+
+    # contents of test_time.py
+
+    from datetime import datetime, timedelta
+
+    testdata = [(datetime(2001, 12, 12), datetime(2001, 12, 11), timedelta(1)),
+	       	(datetime(2001, 12, 11), datetime(2001, 12, 12), timedelta(-1)),
+		]
+
+
+    @pytest.mark.parametrize("a,b,expected", testdata)
+    def test_timedistance_v0(a, b, expected):
+	diff = a - b
+	assert diff == expected
+
+
+    @pytest.mark.parametrize("a,b,expected", testdata, ids=["forward", "backward"])
+    def test_timedistance_v1(a, b, expected):
+	diff = a - b
+	assert diff == expected
+
+
+    def idfn(val):
+	if isinstance(val, (datetime,)):
+	    # note this wouldn't show any hours/minutes/seconds
+	    return val.strftime('%Y%m%d')
+
+
+    @pytest.mark.parametrize("a,b,expected", testdata, ids=idfn)
+    def test_timedistance_v2(a, b, expected):
+	diff = a - b
+	assert diff == expected
+
+
+In ``test_timedistance_v0``, we let pytest generate the test IDs.
+
+In ``test_timedistance_v1``, we specified ``ids`` as a list of strings which were
+used as the test IDs. These are succinct, but can be a pain to maintain.
+
+In ``test_timedistance_v2``, we specified ``ids`` as a function that can generate a
+string representation to make part of the test ID. So our ``datetime`` values use the
+label generated by ``idfn``, but because we didn't generate a label for ``timedelta``
+objects, they are still using the default pytest representation::
+
+
+    $ py.test test_time.py --collect-only
+    ============================ test session starts =============================
+    platform linux2 -- Python 2.7.3 -- py-1.4.20 -- pytest-2.6.0.dev1
+    plugins: cache
+    collected 6 items
+    <Module 'test_time.py'>
+      <Function 'test_timedistance_v0[a0-b0-expected0]'>
+      <Function 'test_timedistance_v0[a1-b1-expected1]'>
+      <Function 'test_timedistance_v1[forward]'>
+      <Function 'test_timedistance_v1[backward]'>
+      <Function 'test_timedistance_v2[20011212-20011211-expected0]'>
+      <Function 'test_timedistance_v2[20011211-20011212-expected1]'>
+
+    ============================== in 0.04 seconds ===============================
+
+
+
+
 A quick port of "testscenarios"
 ------------------------------------
 

doc/en/fixture.txt

@@ -429,6 +429,61 @@ We see that our two test functions each ran twice, against the different
 connection the second test fails in ``test_ehlo`` because a
 different server string is expected than what arrived.
 
+pytest will build a string that is the test ID for each fixture value
+in a parametrized fixture, e.g. ``test_ehlo[merlinux.eu]`` and
+``test_ehlo[mail.python.org]`` in the above examples.  These IDs can
+be used with ``-k`` to select specific cases to run, and they will
+also identify the specific case when one is failing.  Running pytest
+with ``--collect-only`` will show the generated IDs.
+
+Numbers, strings, booleans and None will have their usual string
+representation used in the test ID. For other objects, pytest will
+make a string based on the argument name.  It is possible to customise
+the string used in a test ID for a certain fixture value by using the
+``ids`` keyword argument::
+
+   import pytest
+
+   @pytest.fixture(params=[0, 1], ids=["spam", "ham"])
+   def a(request):
+       return request.param
+
+   def test_a(a):
+       pass
+
+   def idfn(fixture_value):
+       if fixture_value == 0:
+           return "eggs"
+       else:
+           return None
+
+   @pytest.fixture(params=[0, 1], ids=idfn)
+   def b(request):
+       return request.param
+
+   def test_b(b):
+       pass
+
+The above shows how ``ids`` can be either a list of strings to use or
+a function which will be called with the fixture value and then
+has to return a string to use.  In the latter case if the function
+return ``None`` then pytest's auto-generated ID will be used.
+
+Running the above tests results in the following test IDs being used::
+
+   $ py.test --collect-only
+   ========================== test session starts ==========================
+   platform linux2 -- Python 2.7.6 -- py-1.4.25.dev2 -- pytest-2.6.0.dev1
+   plugins: xdist
+   collected 4 items
+   <Module 'test_ids.py'>
+     <Function 'test_a[spam]'>
+     <Function 'test_a[ham]'>
+     <Function 'test_b[eggs]'>
+     <Function 'test_b[1]'>
+
+   ===========================  in 0.05 seconds ============================
+
 
 .. _`interdependent fixtures`: