testtools: Update to latest upstream version.

[kai/samba.git] / lib / testtools / doc / for-framework-folk.rst

diff --git a/lib/testtools/doc/for-framework-folk.rst b/lib/testtools/doc/for-framework-folk.rst
index ff9e71e71ea235b5f76bf01ac765aaac0902287d..ecc11f38e9a4c1837e77507717900b44f6bcee79 100644 (file)
--- a/lib/testtools/doc/for-framework-folk.rst
+++ b/lib/testtools/doc/for-framework-folk.rst
@@ -222,6 +222,17 @@ A test suite that sets up a fixture_ before running any tests, and then tears
 it down after all of the tests are run. The fixture is *not* made available to
 any of the tests.
 
+sorted_tests
+------------
+
+Given the composite structure of TestSuite / TestCase, sorting tests is
+problematic - you can't tell what functionality is embedded into custom Suite
+implementations. In order to deliver consistent test orders when using test
+discovery (see http://bugs.python.org/issue16709), testtools flattens and
+sorts tests that have the standard TestSuite, defines a new method sort_tests,
+which can be used by non-standard TestSuites to know when they should sort
+their tests.
+
 .. _`testtools API docs`: http://mumak.net/testtools/apidocs/
 .. _unittest: http://docs.python.org/library/unittest.html
 .. _fixture: http://pypi.python.org/pypi/fixtures