Document testrunner with some example usage

Author: codeinthehole

.gitignore

@@ -27,6 +27,7 @@ TODO
 
 # Test files
 .coverage
+.noseids
 coverage.xml
 violations.txt
 nosetests.xml

runtests.py

@@ -1,4 +1,35 @@
 #!/usr/bin/env python
+"""
+Custom test runner
+
+If args or options, we run the testsuite as quickly as possible.
+
+If args but no options, we default to using the spec plugin and aborting on
+first error/failure.
+
+If options, we ignore defaults and pass options onto Nose.
+
+Examples:
+
+Run all tests (as fast as possible)
+$ ./runtests.py
+
+Run all unit tests (using spec output)
+$ ./runtests.py tests/unit
+
+Run all checkout unit tests (using spec output)
+$ ./runtests.py tests/unit/checkout
+
+Run all tests relating to shipping
+$ ./runtests.py --attr=shipping
+
+Re-run failing tests (needs to be run twice to first build the index)
+$ ./runtests.py ... --failed
+
+Drop into pdb when a test fails
+$ ./runtests.py ... --pdb-failures
+"""
+
 import sys
 import logging