Merged in rouge8/pytest/issue499 (pull request #157)

fix issue499: document selecting tests by node ID

doc/en/example/markers.txt

@@ -21,6 +21,9 @@ You can "mark" a test function with custom metadata like this::
         pass
     def test_another():
         pass
+    class TestClass:
+        def test_method(self):
+            pass
 
 .. versionadded:: 2.2
 
@@ -29,25 +32,82 @@ You can then restrict a test run to only run tests marked with ``webtest``::
     $ py.test -v -m webtest
     =========================== test session starts ============================
     platform linux2 -- Python 2.7.3 -- py-1.4.20 -- pytest-2.5.2 -- /home/hpk/p/pytest/.tox/regen/bin/python
-    collecting ... collected 3 items
+    collecting ... collected 4 items
     
     test_server.py:3: test_send_http PASSED
     
-    =================== 2 tests deselected by "-m 'webtest'" ===================
+    =================== 3 tests deselected by "-m 'webtest'" ===================
-    ================== 1 passed, 2 deselected in 0.01 seconds ==================
+    ================== 1 passed, 3 deselected in 0.01 seconds ==================
 
 Or the inverse, running all tests except the webtest ones::
 
     $ py.test -v -m "not webtest"
     =========================== test session starts ============================
     platform linux2 -- Python 2.7.3 -- py-1.4.20 -- pytest-2.5.2 -- /home/hpk/p/pytest/.tox/regen/bin/python
-    collecting ... collected 3 items
+    collecting ... collected 4 items
     
     test_server.py:6: test_something_quick PASSED
     test_server.py:8: test_another PASSED
+    test_server.py:11: TestClass.test_method PASSED
     
     ================= 1 tests deselected by "-m 'not webtest'" =================
-    ================== 2 passed, 1 deselected in 0.01 seconds ==================
+    ================== 3 passed, 1 deselected in 0.01 seconds ==================
+
+Selecing tests based on their node ID
+-------------------------------------
+
+You can provide one or more :ref:`node IDs <node-id>` as positional
+arguments to select only specified tests. This makes it easy to select
+tests based on their module, class, method, or function name::
+
+    $ py.test -v test_server.py::TestClass::test_method
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- py-1.4.20 -- pytest-2.5.2 -- /home/hpk/p/pytest/.tox/regen/bin/python
+    collecting ... collected 4 items
+
+    test_server.py:11: TestClass.test_method PASSED
+
+    ========================= 1 passed in 0.01 seconds =========================
+
+You can also select on the class::
+
+    $ py.test -v test_server.py::TestClass
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- py-1.4.20 -- pytest-2.5.2 -- /home/hpk/p/pytest/.tox/regen/bin/python
+    collecting ... collected 4 items
+
+    test_server.py:11: TestClass.test_method PASSED
+
+    ========================= 1 passed in 0.01 seconds =========================
+
+Or select multiple nodes::
+
+  $ py.test -v test_server.py::TestClass test_server.py::test_send_http
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- py-1.4.20 -- pytest-2.5.2 -- /home/hpk/p/pytest/.tox/regen/bin/python
+    collecting ... collected 8 items
+
+    test_server.py:11: TestClass.test_method PASSED
+    test_server.py:3: test_send_http PASSED
+
+    ========================= 2 passed in 0.01 seconds =========================
+
+
+.. _node-id:
+
+.. note::
+
+    Node IDs are of the form ``module.py::class::method`` or
+    ``module.py::function``.  Node IDs control which tests are
+    collected, so ``module.py::class`` will select all test methods
+    on the class.  Nodes are also created for each parameter of a
+    parametrized fixture or test, so selecting a parametrized test
+    must include the parameter value, e.g.
+    ``module.py::function[param]``.
+
+    Node IDs for failing tests are displayed in the test summary info
+    when running py.test with the ``-rf`` option.  You can also
+    construct Node IDs from the output of ``py.test --collectonly``.
 
 Using ``-k expr`` to select tests based on their name
 -------------------------------------------------------
@@ -62,38 +122,39 @@ select tests based on their names::
     $ py.test -v -k http  # running with the above defined example module
     =========================== test session starts ============================
     platform linux2 -- Python 2.7.3 -- py-1.4.20 -- pytest-2.5.2 -- /home/hpk/p/pytest/.tox/regen/bin/python
-    collecting ... collected 3 items
+    collecting ... collected 4 items
     
     test_server.py:3: test_send_http PASSED
     
-    ====================== 2 tests deselected by '-khttp' ======================
+    ====================== 3 tests deselected by '-khttp' ======================
-    ================== 1 passed, 2 deselected in 0.01 seconds ==================
+    ================== 1 passed, 3 deselected in 0.01 seconds ==================
 
 And you can also run all tests except the ones that match the keyword::
 
     $ py.test -k "not send_http" -v
     =========================== test session starts ============================
     platform linux2 -- Python 2.7.3 -- py-1.4.20 -- pytest-2.5.2 -- /home/hpk/p/pytest/.tox/regen/bin/python
-    collecting ... collected 3 items
+    collecting ... collected 4 items
     
     test_server.py:6: test_something_quick PASSED
     test_server.py:8: test_another PASSED
+    test_server.py:11: TestClass.test_method PASSED
     
     ================= 1 tests deselected by '-knot send_http' ==================
-    ================== 2 passed, 1 deselected in 0.01 seconds ==================
+    ================== 3 passed, 1 deselected in 0.01 seconds ==================
 
 Or to select "http" and "quick" tests::
 
     $ py.test -k "http or quick" -v
     =========================== test session starts ============================
     platform linux2 -- Python 2.7.3 -- py-1.4.20 -- pytest-2.5.2 -- /home/hpk/p/pytest/.tox/regen/bin/python
-    collecting ... collected 3 items
+    collecting ... collected 4 items
     
     test_server.py:3: test_send_http PASSED
     test_server.py:6: test_something_quick PASSED
     
-    ================= 1 tests deselected by '-khttp or quick' ==================
+    ================= 2 tests deselected by '-khttp or quick' ==================
-    ================== 2 passed, 1 deselected in 0.01 seconds ==================
+    ================== 2 passed, 2 deselected in 0.01 seconds ==================
 
 .. note::
 

doc/en/usage.txt

@@ -49,6 +49,9 @@ Several test run options::
                           # the "string expression", e.g. "MyClass and not method" 
                           # will select TestMyClass.test_something
                           # but not TestMyClass.test_method_simple
+    py.test test_mod.py::test_func  # only run tests that match the "node ID",
+                                    # e.g "test_mod.py::test_func" will select
+                                    # only test_func in test_mod.py
 
 Import 'pkg' and use its filesystem location to find and run tests::