New module for twisted support code

* Move tests to import that module
* Update API docs to refer to that module
* Make sure that new matchers are exported from that module and included
  in API reference documentation
* Update NEWS

NEWS

@@ -27,6 +27,13 @@ Improvements
 * A failing ``expectThat`` now fails tests run with
   ``AsynchronousDeferredRunTest``.  (Jonathan Lange, #1532452)
 
+* New ``testtools.twistedsupport`` module that collects all of our Twisted
+  support code in one place, including that currently available under
+  ``testtools.deferredruntest``.  (Jonathan Lange)
+
+* New matchers for testing ``Deferred`` code: ``failed``, ``successful``, and
+  ``NO_RESULT``.  (Jonathan Lange, Tristan Seligmann, #1369134)
+
 
 Changes
 -------

doc/api.rst

@@ -18,16 +18,17 @@ testtools
 .. automodule:: testtools
    :members:
 
-
-testtools.deferredruntest
--------------------------
-
-.. automodule:: testtools.deferredruntest
-   :members:
-
-
 testtools.matchers
 ------------------
 
 .. automodule:: testtools.matchers
    :members:
+
+
+testtools.twistedsupport
+-------------------------
+
+.. automodule:: testtools.twistedsupport
+   :members:
+
+   .. autodata:: NO_RESULT

doc/twisted-support.rst

@@ -25,12 +25,14 @@ they fire with.
 
 See also `Testing Deferreds without the reactor`_ and the `Deferred howto`_.
 
-.. autofunction:: testtools._deferredmatchers.successful
+.. autofunction:: testtools.twistedsupport.successful
+   :noindex:
 
-.. autofunction:: testtools._deferredmatchers.failed
-
-.. autodata:: testtools._deferredmatchers.NO_RESULT
+.. autofunction:: testtools.twistedsupport.failed
+   :noindex:
 
+.. autodata:: testtools.twistedsupport.NO_RESULT
+   :noindex:
 
 
 Running tests in the reactor
@@ -43,7 +45,7 @@ until it fires and its callback chain is completed.
 Here's how to use it::
 
   from testtools import TestCase
-  from testtools.deferredruntest import AsynchronousDeferredRunTest
+  from testtools.twistedsupport import AsynchronousDeferredRunTest
 
   class MyTwistedTests(TestCase):
 
@@ -74,7 +76,7 @@ test runner::
 Converting Trial tests to testtools tests
 -----------------------------------------
 
-* Use the :py:class:`testtools.deferredruntest.AsynchronousDeferredRunTest` runner
+* Use the :py:class:`~testtools.twistedsupport.AsynchronousDeferredRunTest` runner
 * Make sure to upcall to :py:meth:`.TestCase.setUp` and
   :py:meth:`.TestCase.tearDown`
 * Don't use ``setUpClass`` or ``tearDownClass``
@@ -83,13 +85,13 @@ Converting Trial tests to testtools tests
 * Replace
   :py:meth:`twisted.trial.unittest.SynchronousTestCase.flushLoggedErrors`
   with
-  :py:func:`testtools.deferredruntest.flush_logged_errors`
+  :py:func:`~testtools.twistedsupport.flush_logged_errors`
 * Replace :py:meth:`twisted.trial.unittest.TestCase.assertFailure` with
-  :py:func:`testtools.deferredruntest.assert_fails_with`
+  :py:func:`~testtools.twistedsupport.assert_fails_with`
 * Trial spins the reactor a couple of times before cleaning it up,
-  :py:class:`testtools.deferredruntest.AsynchronousDeferredRunTest` does not. If
+  :py:class:`~testtools.twistedsupport.AsynchronousDeferredRunTest` does not. If
   you rely on this behavior, use
-  :py:class:`testtools.deferredruntest.AsynchronousDeferredRunTestForBrokenTwisted`.
+  :py:class:`~testtools.twistedsupport.AsynchronousDeferredRunTestForBrokenTwisted`.
 
 
 .. _Deferred Howto: http://twistedmatrix.com/documents/current/core/howto/defer.html

testtools/deferredruntest.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2010 testtools developers. See LICENSE for details.
+# Copyright (c) 2010-2016 testtools developers. See LICENSE for details.
 
 """Individual test case execution for tests that return Deferreds.
 
@@ -365,6 +365,23 @@ def assert_fails_with(d, *exc_types, **kwargs):
 
 
 def flush_logged_errors(*error_types):
+    """Flush errors of the given types from the global Twisted log.
+
+    Any errors logged during a test will be bubbled up to the test result,
+    marking the test as erroring. Use this function to declare that logged
+    errors were expected behavior.
+
+    For example::
+
+        try:
+            1/0
+        except ZeroDivisionError:
+            log.err()
+        # Prevent logged ZeroDivisionError from failing the test.
+        flush_logged_errors(ZeroDivisionError)
+
+    :param error_types: A variable argument list of exception types.
+    """
     return _log_observer.flushErrors(*error_types)
 
 

testtools/tests/test_deferredmatchers.py

@@ -6,11 +6,6 @@ from extras import try_import
 
 from testtools.compat import _u
 from testtools.content import TracebackContent
-from testtools._deferredmatchers import (
-    NO_RESULT,
-    failed,
-    successful,
-)
 from testtools.matchers import (
     AfterPreprocessing,
     Equals,
@@ -18,6 +13,11 @@ from testtools.matchers import (
     MatchesDict,
 )
 from testtools.tests.test_spinner import NeedsTwistedTestCase
+from testtools.twistedsupport import (
+    NO_RESULT,
+    failed,
+    successful,
+)
 
 
 defer = try_import('twisted.internet.defer')

testtools/tests/test_deferredruntest.py

@@ -1,4 +1,4 @@
-# Copyright (c) 2010-2011 testtools developers. See LICENSE for details.
+# Copyright (c) 2010-2016 testtools developers. See LICENSE for details.
 
 """Tests for the DeferredRunTest single test execution logic."""
 

testtools/twistedsupport.py

@@ -0,0 +1,31 @@
+# Copyright (c) testtools developers. See LICENSE for details.
+
+"""Support for testing code that uses Twisted."""
+
+__all__ = [
+    # Matchers
+    'successful',
+    'failed',
+    'NO_RESULT',
+
+    # Running tests
+    'AsynchronousDeferredRunTest',
+    'AsynchronousDeferredRunTestForBrokenTwisted',
+    'SynchronousDeferredRunTest',
+    'assert_fails_with',
+    'flush_logged_errors',
+]
+
+from ._deferredmatchers import (
+    successful,
+    failed,
+    NO_RESULT,
+)
+
+from .deferredruntest import (
+    AsynchronousDeferredRunTest,
+    AsynchronousDeferredRunTestForBrokenTwisted,
+    SynchronousDeferredRunTest,
+    assert_fails_with,
+    flush_logged_errors,
+)