Navigation

Source code for tornado.testing

#!/usr/bin/env python"""Support classes for automated testing.This module contains three parts:* `AsyncTestCase`/`AsyncHTTPTestCase`: Subclasses of unittest.TestCase with additional support for testing asynchronous (IOLoop-based) code.* `LogTrapTestCase`: Subclass of unittest.TestCase that discards log output from tests that pass and only produces output for failing tests.* `main()`: A simple test runner (wrapper around unittest.main()) with support for the tornado.autoreload module to rerun the tests when code changes.These components may be used together or independently. In particular,it is safe to combine AsyncTestCase and LogTrapTestCase via multipleinheritance. See the docstrings for each class/function below for moreinformation."""from__future__importabsolute_import,division,with_statementfromcStringIOimportStringIOtry:fromtornado.httpclientimportAsyncHTTPClientfromtornado.httpserverimportHTTPServerfromtornado.simple_httpclientimportSimpleAsyncHTTPClientfromtornado.ioloopimportIOLoopexceptImportError:# These modules are not importable on app engine. Parts of this module# won't work, but e.g. LogTrapTestCase and main() will.AsyncHTTPClient=NoneHTTPServer=NoneIOLoop=NoneSimpleAsyncHTTPClient=Nonefromtornado.stack_contextimportStackContext,NullContextfromtornado.utilimportraise_exc_infoimportcontextlibimportloggingimportosimportsignalimportsysimporttimeimportunittest_next_port=10000

[docs]classAsyncTestCase(unittest.TestCase):"""TestCase subclass for testing IOLoop-based asynchronous code. The unittest framework is synchronous, so the test must be complete by the time the test method returns. This method provides the stop() and wait() methods for this purpose. The test method itself must call self.wait(), and asynchronous callbacks should call self.stop() to signal completion. By default, a new IOLoop is constructed for each test and is available as self.io_loop. This IOLoop should be used in the construction of HTTP clients/servers, etc. If the code being tested requires a global IOLoop, subclasses should override get_new_ioloop to return it. The IOLoop's start and stop methods should not be called directly. Instead, use self.stop self.wait. Arguments passed to self.stop are returned from self.wait. It is possible to have multiple wait/stop cycles in the same test. Example:: # This test uses an asynchronous style similar to most async # application code. class MyTestCase(AsyncTestCase): def test_http_fetch(self): client = AsyncHTTPClient(self.io_loop) client.fetch("http://www.tornadoweb.org/", self.handle_fetch) self.wait() def handle_fetch(self, response): # Test contents of response (failures and exceptions here # will cause self.wait() to throw an exception and end the # test). # Exceptions thrown here are magically propagated to # self.wait() in test_http_fetch() via stack_context. self.assertIn("FriendFeed", response.body) self.stop() # This test uses the argument passing between self.stop and self.wait # for a simpler, more synchronous style. # This style is recommended over the preceding example because it # keeps the assertions in the test method itself, and is therefore # less sensitive to the subtleties of stack_context. class MyTestCase2(AsyncTestCase): def test_http_fetch(self): client = AsyncHTTPClient(self.io_loop) client.fetch("http://www.tornadoweb.org/", self.stop) response = self.wait() # Test contents of response self.assertIn("FriendFeed", response.body) """def__init__(self,*args,**kwargs):super(AsyncTestCase,self).__init__(*args,**kwargs)self.__stopped=Falseself.__running=Falseself.__failure=Noneself.__stop_args=Noneself.__timeout=NonedefsetUp(self):super(AsyncTestCase,self).setUp()self.io_loop=self.get_new_ioloop()deftearDown(self):if(notIOLoop.initialized()orself.io_loopisnotIOLoop.instance()):# Try to clean up any file descriptors left open in the ioloop.# This avoids leaks, especially when tests are run repeatedly# in the same process with autoreload (because curl does not# set FD_CLOEXEC on its file descriptors)self.io_loop.close(all_fds=True)super(AsyncTestCase,self).tearDown()

[docs]defget_new_ioloop(self):'''Creates a new IOLoop for this test. May be overridden in subclasses for tests that require a specific IOLoop (usually the singleton). '''returnIOLoop()

@contextlib.contextmanagerdef_stack_context(self):try:yieldexceptException:self.__failure=sys.exc_info()self.stop()def__rethrow(self):ifself.__failureisnotNone:failure=self.__failureself.__failure=Noneraise_exc_info(failure)defrun(self,result=None):withStackContext(self._stack_context):super(AsyncTestCase,self).run(result)# In case an exception escaped super.run or the StackContext caught# an exception when there wasn't a wait() to re-raise it, do so here.self.__rethrow()

[docs]defstop(self,_arg=None,**kwargs):'''Stops the ioloop, causing one pending (or future) call to wait() to return. Keyword arguments or a single positional argument passed to stop() are saved and will be returned by wait(). '''assert_argisNoneornotkwargsself.__stop_args=kwargsor_argifself.__running:self.io_loop.stop()self.__running=Falseself.__stopped=True

[docs]defwait(self,condition=None,timeout=5):"""Runs the IOLoop until stop is called or timeout has passed. In the event of a timeout, an exception will be thrown. If condition is not None, the IOLoop will be restarted after stop() until condition() returns true. """ifnotself.__stopped:iftimeout:deftimeout_func():try:raiseself.failureException('Async operation timed out after %s seconds'%timeout)exceptException:self.__failure=sys.exc_info()self.stop()ifself.__timeoutisnotNone:self.io_loop.remove_timeout(self.__timeout)self.__timeout=self.io_loop.add_timeout(time.time()+timeout,timeout_func)whileTrue:self.__running=TruewithNullContext():# Wipe out the StackContext that was established in# self.run() so that all callbacks executed inside the# IOLoop will re-run it.self.io_loop.start()if(self.__failureisnotNoneorconditionisNoneorcondition()):breakassertself.__stoppedself.__stopped=Falseself.__rethrow()result=self.__stop_argsself.__stop_args=Nonereturnresult

[docs]classAsyncHTTPTestCase(AsyncTestCase):'''A test case that starts up an HTTP server. Subclasses must override get_app(), which returns the tornado.web.Application (or other HTTPServer callback) to be tested. Tests will typically use the provided self.http_client to fetch URLs from this server. Example:: class MyHTTPTest(AsyncHTTPTestCase): def get_app(self): return Application([('/', MyHandler)...]) def test_homepage(self): # The following two lines are equivalent to # response = self.fetch('/') # but are shown in full here to demonstrate explicit use # of self.stop and self.wait. self.http_client.fetch(self.get_url('/'), self.stop) response = self.wait() # test contents of response '''defsetUp(self):super(AsyncHTTPTestCase,self).setUp()self.__port=Noneself.http_client=self.get_http_client()self._app=self.get_app()self.http_server=self.get_http_server()self.http_server.listen(self.get_http_port(),address="127.0.0.1")defget_http_client(self):returnAsyncHTTPClient(io_loop=self.io_loop)defget_http_server(self):returnHTTPServer(self._app,io_loop=self.io_loop,**self.get_httpserver_options())

[docs]defget_app(self):"""Should be overridden by subclasses to return a tornado.web.Application or other HTTPServer callback. """raiseNotImplementedError()

[docs]deffetch(self,path,**kwargs):"""Convenience method to synchronously fetch a url. The given path will be appended to the local server's host and port. Any additional kwargs will be passed directly to AsyncHTTPClient.fetch (and so could be used to pass method="POST", body="...", etc). """self.http_client.fetch(self.get_url(path),self.stop,**kwargs)returnself.wait()

[docs]defget_httpserver_options(self):"""May be overridden by subclasses to return additional keyword arguments for the server. """return{}

[docs]defget_http_port(self):"""Returns the port used by the server. A new port is chosen for each test. """ifself.__portisNone:self.__port=get_unused_port()returnself.__port

defget_protocol(self):return'http'

[docs]defget_url(self,path):"""Returns an absolute url for the given path on the test server."""return'%s://localhost:%s%s'%(self.get_protocol(),self.get_http_port(),path)

[docs]classAsyncHTTPSTestCase(AsyncHTTPTestCase):"""A test case that starts an HTTPS server. Interface is generally the same as `AsyncHTTPTestCase`. """defget_http_client(self):# Some versions of libcurl have deadlock bugs with ssl,# so always run these tests with SimpleAsyncHTTPClient.returnSimpleAsyncHTTPClient(io_loop=self.io_loop,force_instance=True)defget_httpserver_options(self):returndict(ssl_options=self.get_ssl_options())

[docs]classLogTrapTestCase(unittest.TestCase):"""A test case that captures and discards all logging output if the test passes. Some libraries can produce a lot of logging output even when the test succeeds, so this class can be useful to minimize the noise. Simply use it as a base class for your test case. It is safe to combine with AsyncTestCase via multiple inheritance ("class MyTestCase(AsyncHTTPTestCase, LogTrapTestCase):") This class assumes that only one log handler is configured and that it is a StreamHandler. This is true for both logging.basicConfig and the "pretty logging" configured by tornado.options. """defrun(self,result=None):logger=logging.getLogger()iflen(logger.handlers)>1:# Multiple handlers have been defined. It gets messy to handle# this, especially since the handlers may have different# formatters. Just leave the logging alone in this case.super(LogTrapTestCase,self).run(result)returnifnotlogger.handlers:logging.basicConfig()self.assertEqual(len(logger.handlers),1)handler=logger.handlers[0]assertisinstance(handler,logging.StreamHandler)old_stream=handler.streamtry:handler.stream=StringIO()logging.info("RUNNING TEST: "+str(self))old_error_count=len(result.failures)+len(result.errors)super(LogTrapTestCase,self).run(result)new_error_count=len(result.failures)+len(result.errors)ifnew_error_count!=old_error_count:old_stream.write(handler.stream.getvalue())finally:handler.stream=old_stream

[docs]defmain(**kwargs):"""A simple test runner. This test runner is essentially equivalent to `unittest.main` from the standard library, but adds support for tornado-style option parsing and log formatting. The easiest way to run a test is via the command line:: python -m tornado.testing tornado.test.stack_context_test See the standard library unittest module for ways in which tests can be specified. Projects with many tests may wish to define a test script like tornado/test/runtests.py. This script should define a method all() which returns a test suite and then call tornado.testing.main(). Note that even when a test script is used, the all() test suite may be overridden by naming a single test on the command line:: # Runs all tests python -m tornado.test.runtests # Runs one test python -m tornado.test.runtests tornado.test.stack_context_test Additional keyword arguments passed through to ``unittest.main()``. For example, use ``tornado.testing.main(verbosity=2)`` to show many test details as they are run. See http://docs.python.org/library/unittest.html#unittest.main for full argument list. """fromtornado.optionsimportdefine,options,parse_command_linedefine('autoreload',type=bool,default=False,help="DEPRECATED: use tornado.autoreload.main instead")define('httpclient',type=str,default=None)define('exception_on_interrupt',type=bool,default=True,help=("If true (default), ctrl-c raises a KeyboardInterrupt ""exception. This prints a stack trace but cannot interrupt ""certain operations. If false, the process is more reliably ""killed, but does not print a stack trace."))argv=[sys.argv[0]]+parse_command_line(sys.argv)ifoptions.httpclient:fromtornado.httpclientimportAsyncHTTPClientAsyncHTTPClient.configure(options.httpclient)ifnotoptions.exception_on_interrupt:signal.signal(signal.SIGINT,signal.SIG_DFL)if__name__=='__main__'andlen(argv)==1:print>>sys.stderr,"No tests specified"sys.exit(1)try:# In order to be able to run tests by their fully-qualified name# on the command line without importing all tests here,# module must be set to None. Python 3.2's unittest.main ignores# defaultTest if no module is given (it tries to do its own# test discovery, which is incompatible with auto2to3), so don't# set module if we're not asking for a specific test.iflen(argv)>1:unittest.main(module=None,argv=argv,**kwargs)else:unittest.main(defaultTest="all",argv=argv,**kwargs)exceptSystemExit,e:ife.code==0:logging.info('PASS')else:logging.error('FAIL')ifnotoptions.autoreload:raiseifoptions.autoreload:importtornado.autoreloadtornado.autoreload.wait()