[Python-checkins] devguide: Start a doc on running and writing unit tests.

[brett.cannon]

brett.cannon pushed 2c77eaf7f589 to devguide:

http://hg.python.org/devguide/rev/2c77eaf7f589
changeset:   29:2c77eaf7f589
user:        Brett Cannon <brett at python.org>
date:        Wed Jan 05 13:44:39 2011 -0800
summary:
  Start a doc on running and writing unit tests.

files:
  index.rst
  runtests.rst

diff --git a/index.rst b/index.rst
--- a/index.rst
+++ b/index.rst
@@ -6,6 +6,7 @@
 
    setup
    patch
+   runtests
 
 
 .. todolist::
diff --git a/runtests.rst b/runtests.rst
new file mode 100644
--- /dev/null
+++ b/runtests.rst
@@ -0,0 +1,49 @@
+.. _runtests:
+
+Running & Writing Tests
+=======================
+
+.. note::
+    This document assumes you are working with the in-development version of
+    Python. If you are not then some things presented here may not work as they
+    may depend on new features not available in released versions of Python.
+
+Running
+-------
+
+The shortest, simplest way of running the test suite is::
+
+    ./python -m test
+
+That will run the entire standard test suite (i.e., all tests that do not
+consume a lot of resources) using the ``test.regrtest`` module (Python's test
+runner which you can execute directly if you prefer).
+To run **all** tests, you need to specify what
+resources you are willing to have consumed. For those flags (and others which
+can help debug various issues such as reference leaks), read the help text::
+
+    ./python -m test -h
+
+If you want to run a single test, simply specify the test name as an argument::
+
+    ./python -m test test_abc
+
+Finally, if you want to run tests under a more strenuous set of settings, you
+can run test as::
+
+    ./python -bb -E -Wd -m test -j2 -r -w
+
+The various extra flags passed to Python cause it to be much stricter about
+various things (the ``-Wd`` flag should be ``-We`` at some point, but the test
+suite has not reached a point where all warnings have been dealt with and so we
+cannot guarantee that a bug-free Python will properly complete a test run with
+``-We``). The flags to the test runner cause it to run faster but also
+more randomly which is also a stricter way to run tests thanks to possible
+assumptions in test order or state that may have been made. It also causes
+failures to run again to see if it a transient failure or a consistent one.
+
+
+Writing
+-------
+
+XXX

--
Repository URL: http://hg.python.org/devguide