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

--HG--
branch : issue351

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"
 ------------------------------------