From 9844baa7d435855af4e29fa33606154d33c75df2 Mon Sep 17 00:00:00 2001 From: Jonathan Lange Date: Sun, 10 Jan 2016 10:45:49 +0000 Subject: [PATCH] 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 | 7 ++++++ doc/api.rst | 17 +++++++------ doc/twisted-support.rst | 22 +++++++++-------- testtools/deferredruntest.py | 19 ++++++++++++++- testtools/tests/test_deferredmatchers.py | 10 ++++---- testtools/tests/test_deferredruntest.py | 2 +- testtools/twistedsupport.py | 31 ++++++++++++++++++++++++ 7 files changed, 83 insertions(+), 25 deletions(-) create mode 100644 testtools/twistedsupport.py diff --git a/NEWS b/NEWS index 53daad7..180838c 100644 --- a/NEWS +++ b/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 ------- diff --git a/doc/api.rst b/doc/api.rst index 71f7759..ad00d7b 100644 --- a/doc/api.rst +++ b/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 diff --git a/doc/twisted-support.rst b/doc/twisted-support.rst index fc0c1c3..c212649 100644 --- a/doc/twisted-support.rst +++ b/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 diff --git a/testtools/deferredruntest.py b/testtools/deferredruntest.py index 9dc8eea..45db13b 100644 --- a/testtools/deferredruntest.py +++ b/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) diff --git a/testtools/tests/test_deferredmatchers.py b/testtools/tests/test_deferredmatchers.py index e43dafe..a5da3c6 100644 --- a/testtools/tests/test_deferredmatchers.py +++ b/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') diff --git a/testtools/tests/test_deferredruntest.py b/testtools/tests/test_deferredruntest.py index 34586a8..8d00e9e 100644 --- a/testtools/tests/test_deferredruntest.py +++ b/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.""" diff --git a/testtools/twistedsupport.py b/testtools/twistedsupport.py new file mode 100644 index 0000000..f938c7e --- /dev/null +++ b/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, +)