From d4dc775620fc57e962165eab98a77264e3dd16b2 Mon Sep 17 00:00:00 2001
From: Jakub Paczkowski <jakub@paczkowski.eu>
Date: Sat, 7 Nov 2015 14:57:56 +0100
Subject: Fixed #25735 -- Added support for test tags to DiscoverRunner.

Thanks Carl Meyer, Claude Paroz, and Simon Charette for review.
---
 docs/ref/django-admin.txt     | 14 +++++++++++
 docs/releases/1.10.txt        |  4 ++++
 docs/topics/testing/tools.txt | 54 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 72 insertions(+)

(limited to 'docs')

diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 0fbad35bcf..87753b28bd 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -1348,6 +1348,20 @@ don't.
     in order to exchange them between processes. See
     :ref:`python:pickle-picklable` for details.
 
+.. option:: --tag TAGS
+
+.. versionadded:: 1.10
+
+Runs only tests :ref:`marked with the specified tags <topics-tagging-tests>`.
+May be specified multiple times and combined with :option:`test --exclude-tag`.
+
+.. option:: --exclude-tag EXCLUDE_TAGS
+
+.. versionadded:: 1.10
+
+Excludes tests :ref:`marked with the specified tags <topics-tagging-tests>`.
+May be specified multiple times and combined with :option:`test --tag`.
+
 ``testserver``
 --------------
 
diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index b3bd4b8afd..1154429f2b 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -336,6 +336,10 @@ Tests
 * To better catch bugs, :class:`~django.test.TestCase` now checks deferrable
   database constraints at the end of each test.
 
+* Tests and test cases can be :ref:`marked with tags <topics-tagging-tests>`
+  and run selectively with the new :option:`test --tag` and :option:`test
+  --exclude-tag` options.
+
 URLs
 ~~~~
 
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index 2bb53454cf..de008bd325 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -1622,6 +1622,60 @@ your test suite.
             Person.objects.create(name="Aaron")
             Person.objects.create(name="Daniel")
 
+.. _topics-tagging-tests:
+
+Tagging tests
+-------------
+
+.. versionadded:: 1.10
+
+You can tag your tests so you can easily run a particular subset. For example,
+you might label fast or slow tests::
+
+    from django.test.utils import tag
+
+    class SampleTestCase(TestCase):
+
+        @tag('fast')
+        def test_fast(self):
+            ...
+
+        @tag('slow')
+        def test_slow(self):
+            ...
+
+        @tag('slow', 'core')
+        def test_slow_but_core(self):
+            ...
+
+You can also tag a test case::
+
+    @tag('slow', 'core')
+    class SampleTestCase(TestCase):
+        ...
+
+Then you can choose which tests to run. For example, to run only fast tests:
+
+.. code-block:: console
+
+    $ ./manage.py test --tag=fast
+
+Or to run fast tests and the core one (even though it's slow):
+
+.. code-block:: console
+
+    $ ./manage.py test --tag=fast --tag=core
+
+You can also exclude tests by tag. To run core tests if they are not slow:
+
+.. code-block:: console
+
+    $ ./manage.py test --tag=core --exclude-tag=slow
+
+:option:`test --exclude-tag` has precedence over :option:`test --tag`, so if a
+test has two tags and you select one of them and exclude the other, the test
+won't be run.
+
 .. _topics-testing-email:
 
 Email services
-- 
cgit v1.3