From 5b482a96d0b2a96ff433e36ea71936295b255835 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gregor=20M=C3=BCllegger?= <gregor@muellegger.de>
Date: Thu, 23 May 2013 22:18:12 +0200
Subject: [PATCH] Adding docs for optional runtests.py arguments.

---
 docs/contributing.rst | 15 +++++++++++++++
 runtests.py           | 20 ++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/docs/contributing.rst b/docs/contributing.rst
index 5cfeec2..aeea640 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -142,6 +142,21 @@ For now, we use the Django Test framework (based on unittest).
 
 Also, keep your tests as simple as possible. Complex tests end up requiring their own tests. We would rather see duplicated assertions across test methods then cunning utility methods that magically determine which assertions are needed at a particular stage. Remember: `Explicit is better than implicit`.
 
+You don't need to run the whole test suite during development in order to make
+the test cycles a bit faster. Just pass in the specific tests you want to run
+to ``runtests.py`` as you would do with the ``django-admin.py test`` command.
+Examples::
+
+    # only run the tests from application ``blog``
+    python runtests.py blog
+
+    # only run testcase class ``Admin2Test`` from app ``djadmin2``
+    python runtests.py djadmin2.Admin2Test
+
+    # run all tests from application ``blog`` and the test named
+    # ``test_register`` on the ``djadmin2.Admin2Test`` testcase.
+    python runtests.py djadmin2.Admin2Test.test_register blog
+
 Don't mix code changes with whitespace cleanup
 ----------------------------------------------
 
diff --git a/runtests.py b/runtests.py
index 9598f89..6e2cf3f 100755
--- a/runtests.py
+++ b/runtests.py
@@ -11,6 +11,26 @@ from django.conf import settings
 
 
 def runtests(tests=('blog', 'djadmin2',)):
+    '''
+    Takes a list as first argument, enumerating the apps and specific testcases
+    that should be executed. The syntax is the same as for what you would pass
+    to the ``django-admin.py test`` command.
+
+    Examples::
+
+        # run the default test suite
+        runtests()
+
+        # only run the tests from application ``blog``
+        runtests(['blog'])
+
+        # only run testcase class ``Admin2Test`` from app ``djadmin2``
+        runtests(['djadmin2.Admin2Test'])
+
+        # run all tests from application ``blog`` and the test named
+        # ``test_register`` on the ``djadmin2.Admin2Test`` testcase.
+        runtests(['djadmin2.Admin2Test.test_register', 'blog'])
+    '''
     TestRunner = get_runner(settings)
     test_runner = TestRunner(verbosity=1, interactive=True)
     failures = test_runner.run_tests(tests)