diff options
Diffstat (limited to 'docs/source/testing.rst')
-rw-r--r-- | docs/source/testing.rst | 137 |
1 files changed, 0 insertions, 137 deletions
diff --git a/docs/source/testing.rst b/docs/source/testing.rst deleted file mode 100644 index 5253d6b..0000000 --- a/docs/source/testing.rst +++ /dev/null @@ -1,137 +0,0 @@ -.. _testing: - -Testing Pecan Applications -========================== -Tests can live anywhere in your Pecan project as long as the test runner can -discover them. Traditionally, they exist in a package named ``myapp.tests``. - -The suggested mechanism for unit and integration testing of a Pecan application -is the :mod:`unittest` module. - -Test Discovery and Other Tools ------------------------------- - -Tests for a Pecan project can be invoked as simply as ``python setup.py test``, -though it's possible to run your tests with different discovery and automation -tools. In particular, Pecan projects are known to work well with -`nose <http://pypi.python.org/pypi/nose/1.1.2>`_, `pytest -<http://pytest.org>`_, -and `tox <http://pypi.python.org/pypi/tox>`_. - -Writing Functional Tests with WebTest -------------------------------------- -A **unit test** typically relies on "mock" or "fake" objects to give the code -under test enough context to run. In this way, only an individual unit of -source code is tested. - -A healthy suite of tests combines **unit tests** with **functional tests**. In -the context of a Pecan application, functional tests can be written with the -help of the :mod:`webtest` library. In this way, it is possible to write tests -that verify the behavior of an HTTP request life cycle from the controller -routing down to the HTTP response. The following is an example that is -similar to the one included with Pecan's quickstart project. - -:: - - # myapp/myapp/tests/__init__.py - - import os - from unittest import TestCase - from pecan import set_config - from pecan.testing import load_test_app - - class FunctionalTest(TestCase): - """ - Used for functional tests where you need to test your - literal application and its integration with the framework. - """ - - def setUp(self): - self.app = load_test_app(os.path.join( - os.path.dirname(__file__), - 'config.py' - )) - - def tearDown(self): - set_config({}, overwrite=True) - -The testing utility included with Pecan, :func:`pecan.testing.load_test_app`, can -be passed a file path representing a Pecan configuration file, and will return -an instance of the application, wrapped in a :class:`~webtest.app.TestApp` -environment. - -From here, it's possible to extend the :class:`FunctionalTest` base class and write -tests that issue simulated HTTP requests. - -:: - - class TestIndex(FunctionalTest): - - def test_index(self): - resp = self.app.get('/') - assert resp.status_int == 200 - assert 'Hello, World' in resp.body - -.. seealso:: - - See the :mod:`webtest` documentation - for further information about the methods available to a - :class:`~webtest.app.TestApp` instance. - -Special Testing Variables -------------------------- - -Sometimes it's not enough to make assertions about the response body of certain -requests. To aid in inspection, Pecan applications provide a special set of -"testing variables" to any :class:`~webtest.response.TestResponse` object. - -Let's suppose that your Pecan applicaton had some controller which took a -``name`` as an optional argument in the URL. - -:: - - # myapp/myapp/controllers/root.py - from pecan import expose - - class RootController(object): - - @expose('index.html') - def index(self, name='Joe'): - """A request to / will access this controller""" - return dict(name=name) - -and rendered that name in it's template (and thus, the response body). - -:: - - # myapp/myapp/templates/index.html - Hello, ${name}! - -A functional test for this controller might look something like - -:: - - class TestIndex(FunctionalTest): - - def test_index(self): - resp = self.app.get('/') - assert resp.status_int == 200 - assert 'Hello, Joe!' in resp.body - -In addition to :attr:`webtest.TestResponse.body`, Pecan also provides -:attr:`webtest.TestResponse.namespace`, which represents the template namespace -returned from the controller, and :attr:`webtest.TestResponse.template_name`, which -contains the name of the template used. - -:: - - class TestIndex(FunctionalTest): - - def test_index(self): - resp = self.app.get('/') - assert resp.status_int == 200 - assert resp.namespace == {'name': 'Joe'} - assert resp.template_name == 'index.html' - -In this way, it's possible to test the return value and rendered template of -individual controllers. |