From 5e319f5194656849f1660c5d6ff2df695ed13c75 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Mon, 11 Oct 2010 13:18:00 +0000
Subject: [PATCH] Refs #12991 -- Added extra docs for the unittest2 changes
 made in r14139.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14140 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/internals/deprecation.txt |  6 ++++
 docs/topics/testing.txt        | 55 ++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index edd3a1d2ec..f4ebadd6f4 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -108,6 +108,12 @@ their deprecation, as per the :ref:`Django deprecation policy
           :attr:`~django.test.client.Response.templates` attribute should be
           used instead.
 
+        * The features of the :class:`django.test.simple.DjangoTestRunner`
+          (including fail-fast and Ctrl-C test termination) can now be provided
+          by the unittest-native :class:`TextTestRunner`. The
+          :class:`~django.test.simple.DjangoTestRunner` will be removed in
+          favor of using the unittest-native class.
+
     * 2.0
         * ``django.views.defaults.shortcut()``. This function has been moved
           to ``django.contrib.contenttypes.views.shortcut()`` as part of the
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index 5ecf1f032a..904e7070db 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -1431,6 +1431,61 @@ manually, assign the empty list to ``mail.outbox``::
     # Empty the test outbox
     mail.outbox = []
 
+Skipping tests
+--------------
+
+.. versionadded:: 1.3
+
+The unittest library provides the ``@skipIf`` and ``@skipUnless``
+decorators to allow you to skip tests if you know ahead of time that
+those tests are going to fail under certain conditions.
+
+For example, if your test requires a particular optional library in
+order to succeed, you could decorate the test case with ``@skipIf``.
+Then, the test runner will report that the test wasn't executed and
+why, instead of failing the test or omitting the test altogether.
+
+To supplement these test skipping behaviors, Django provides two
+additional skip decorators. Instead of testing a generic boolean,
+these decorators check the capabilities of the database, and skip the
+test if the database doesn't support a specific named feature.
+
+The decorators use a string identifier to describe database features.
+This string corresponds to attributes of the database connection
+features class. See :class:`~django.db.backends.BaseDatabaseFeatures`
+class for a full list of database features that can be used as a basis
+for skipping tests.
+
+skipIfDBFeature
+~~~~~~~~~~~~~~~
+
+Skip the decorated test if the named database feature is supported.
+
+For example, the following test will not be executed if the database
+supports transactions (e.g., it would *not* run under PostgreSQL, but
+it would under MySQL with MyISAM tables)::
+
+    class MyTests(TestCase):
+        @skipIfDBFeature('supports_transactions')
+        def test_transaction_behavior(self):
+            # ... conditional test code
+
+skipUnlessDBFeature
+~~~~~~~~~~~~~~~~~~~
+
+Skip the decorated test if the named database feature is *not*
+supported.
+
+For example, the following test will not be executed if the database
+supports transactions (e.g., it would run under PostgreSQL, but *not*
+under MySQL with MyISAM tables)::
+
+    class MyTests(TestCase):
+        @skipUnlessDBFeature('supports_transactions')
+        def test_transaction_behavior(self):
+            # ... conditional test code
+
+
 Using different testing frameworks
 ==================================