From 91e2b232588c5ff1c3dea550b9649df523e66728 Mon Sep 17 00:00:00 2001
From: "david@mcbf.net" <david@mcbf.net>
Date: Sat, 26 Jul 2014 18:10:32 +0200
Subject: [PATCH] Update documentation

--HG--
branch : xfail-cause
---
 doc/en/assert.txt            | 16 ++++++++++++++++
 doc/en/example/xfail_demo.py |  5 +++++
 doc/en/skipping.txt          |  5 +++++
 3 files changed, 26 insertions(+)

diff --git a/doc/en/assert.txt b/doc/en/assert.txt
index 6d9f60448..1dd7ba0c0 100644
--- a/doc/en/assert.txt
+++ b/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
diff --git a/doc/en/example/xfail_demo.py b/doc/en/example/xfail_demo.py
index 75cb7bea1..79752680a 100644
--- a/doc/en/example/xfail_demo.py
+++ b/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
diff --git a/doc/en/skipping.txt b/doc/en/skipping.txt
index c896d404d..ab6c838ba 100644
--- a/doc/en/skipping.txt
+++ b/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: