Update documentation

--HG--
branch : xfail-cause

doc/en/assert.txt

@@ -95,6 +95,22 @@ asserts that the given ``ExpectedException`` is raised.  The reporter will
 provide you with helpful output in case of failures such as *no
 exception* or *wrong exception*.
 
+Note that it is also possible to specify a "raises" argument to
+``pytest.mark.xfail``, which checks that the test is failing in a more
+specific way than just having any exception raised::
+
+    @pytest.mark.xfail(raises=IndexError)
+    def test_f():
+        f()
+
+Using ``pytest.raises`` is likely to be better for cases where you are testing
+exceptions your own code is deliberately raising, whereas using
+``@pytest.mark.xfail`` with a check function is probably better for something
+like documenting unfixed bugs (where the test describes what "should" happen)
+or bugs in dependencies.
+
+
+
 .. _newreport:
 
 Making use of context-sensitive comparisons

doc/en/example/xfail_demo.py

@@ -23,3 +23,8 @@ def test_hello5():
 
 def test_hello6():
     pytest.xfail("reason")
+
+@xfail(raises=IndexError)
+def test_hello7()
+    x = []
+    assert x[1] == 1

doc/en/skipping.txt

@@ -149,6 +149,11 @@ on a particular platform::
     def test_function():
         ...
 
+If you want to be more specific as to why the test is failing, you can specify
+a single exception, or a list of exceptions, in the ``raises`` argument. Then
+the test will be reported as a regular failure if it fails with an
+exception not mentioned in ``raises``.
+
 You can furthermore prevent the running of an "xfail" test or
 specify a reason such as a bug ID or similar.  Here is
 a simple test file with the several usages: