testtools-dev team mailing list archive

[Jonathan Lange <jml@xxxxxxxxx>]

Jonathan Lange has proposed merging lp:~jml/testtools/docs-update into lp:testtools.

Requested reviews:
  testtools committers (testtools-committers)

For more details, see:
https://code.launchpad.net/~jml/testtools/docs-update/+merge/70868

Adds docs for two things that people might not otherwise find: ErrorHolder and PlaceHolder.
-- 
https://code.launchpad.net/~jml/testtools/docs-update/+merge/70868
Your team testtools developers is subscribed to branch lp:testtools.

=== modified file 'NEWS'
--- NEWS	2011-08-08 11:16:01 +0000
+++ NEWS	2011-08-09 12:42:34 +0000
@@ -40,9 +40,14 @@
 * Correctly display non-ASCII unicode output on terminals that claim to have a
   unicode encoding. (Martin [gz], #804122)
 
+<<<<<<< TREE
 * ``DocTestMatches`` correctly handles unicode output from examples, rather
   than raising an error. (Martin [gz], #764170)
 
+=======
+* ``ErrorHolder`` and ``PlaceHolder`` added to docs. (Jonathan Lange, #816597)
+
+>>>>>>> MERGE-SOURCE
 * ``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 12:42:34 +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
 ========================