Merge lp:~jml/testtools/docs-update into lp:~testtools-committers/testtools/trunk

[Jonathan Lange]

Adds docs for two things that people might not otherwise find: ErrorHolder and PlaceHolder.

[lp:~jml/testtools/docs-update]

223. By Jonathan Lange on 2011-08-09

Merge trunk. Resolve conflicts.

=== modified file 'NEWS'
--- NEWS	2011-08-08 11:16:01 +0000
+++ NEWS	2011-08-09 13:15:20 +0000
@@ -43,6 +43,8 @@
 * ``DocTestMatches`` correctly handles unicode output from examples, rather
   than raising an error. (Martin [gz], #764170)
 
+* ``ErrorHolder`` and ``PlaceHolder`` added to docs. (Jonathan Lange, #816597)
+
 * ``ExpectedException`` now matches any exception of the given type by
   default, and also allows specifying a ``Matcher`` rather than a mere regular
   expression. (Jonathan Lange, #791889)

=== modified file 'doc/for-framework-folk.rst'
--- doc/for-framework-folk.rst	2011-07-20 12:53:13 +0000
+++ doc/for-framework-folk.rst	2011-08-09 13:15:20 +0000
@@ -79,6 +79,31 @@
 parameterization.
 
 
+Test placeholders
+=================
+
+Sometimes, it's useful to be able to add things to a test suite that are not
+actually tests.  For example, you might wish to represents import failures
+that occur during test discovery as tests, so that your test result object
+doesn't have to do special work to handle them nicely.
+
+testtools provides two such objects, called "placeholders": ``PlaceHolder``
+and ``ErrorHolder``.  ``PlaceHolder`` takes a test id and an optional
+description.  When it's run, it succeeds.  ``ErrorHolder`` takes a test id,
+and error and an optional short description.  When it's run, it reports that
+error.
+
+These placeholders are best used to log events that occur outside the test
+suite proper, but are still very relevant to its results.
+
+e.g.::
+
+  >>> suite = TestSuite()
+  >>> suite.add(PlaceHolder('I record an event'))
+  >>> suite.run(TextTestResult(verbose=True))
+  I record an event                                                   [OK]
+
+
 Extensions to TestResult
 ========================