23. UNIT, INTEGRATION, AND FUNCTIONAL TESTING
23.1.1 What?
Thread local data structures are always a bit confusing, especially when they’re used by frameworks. Sorry. So here’s a rule of thumb: if you don’t know whether you’re calling code that uses the get_current_registry() or get_current_request() functions, or you don’t care about any of this, but you still want to write test code, just always call pyramid.testing.setUp() in your test’s setUp method and pyramid.testing.tearDown() in your tests’ tearDown method. This won’t really hurt anything if the application you’re testing does not call any get_current* function.
23.2Using the Configurator and pyramid.testing APIs in Unit Tests
The Configurator API and the pyramid.testing module provide a number of functions which can be used during unit testing. These functions make configuration declaration calls to the current application registry, but typically register a “stub” or “dummy” feature in place of the “real” feature that the code would call if it was being run normally.
For example, let’s imagine you want to unit test a Pyramid view function.
1
2
3
4
5
6
7
from pyramid.security import has_permission from pyramid.httpexceptions import HTTPForbidden
def view_fn(request):
if not has_permission(’edit’, request.context, request): raise HTTPForbidden
return {’greeting’:’hello’}
Without doing anything special during a unit test, the call to has_permission() in this view function will always return a True value. When a Pyramid application starts normally, it will populate a application registry using configuration declaration calls made against a Configurator. But if this application registry is not created and populated (e.g. by initializing the configurator with an authorization policy), like when you invoke application code via a unit test, Pyramid API functions will tend to either fail or return default results. So how do you test the branch of the code in this view function that raises
HTTPForbidden?
The testing API provided by Pyramid allows you to simulate various application registry registrations for use under a unit testing framework without needing to invoke the actual application configuration implied by its main function. For example, if you wanted to test the above view_fn (assuming it lived in the package named my.package), you could write a unittest.TestCase that used the testing API.
256
|
23.2. USING THE CONFIGURATOR AND PYRAMID.TESTING APIS IN UNIT TESTS |
|
|
1 |
import unittest |
2 |
from pyramid import testing |
3 |
|
4 |
class MyTest(unittest.TestCase): |
5def setUp(self):
6self.config = testing.setUp()
7
8def tearDown(self):
9testing.tearDown()
10
11def test_view_fn_forbidden(self):
12from pyramid.httpexceptions import HTTPForbidden
13from my.package import view_fn
14self.config.testing_securitypolicy(userid=’hank’,
15 |
permissive=False) |
16request = testing.DummyRequest()
17request.context = testing.DummyResource()
18self.assertRaises(HTTPForbidden, view_fn, request)
19
20def test_view_fn_allowed(self):
21from my.package import view_fn
22self.config.testing_securitypolicy(userid=’hank’,
23 |
permissive=True) |
24request = testing.DummyRequest()
25request.context = testing.DummyResource()
26response = view_fn(request)
27self.assertEqual(response, {’greeting’:’hello’})
In the above example, we create a MyTest test case that inherits from unittest.TestCase. If it’s in our Pyramid application, it will be found when setup.py test is run. It has two test methods.
The first test method, test_view_fn_forbidden tests the view_fn when the authentication policy forbids the current user the edit permission. Its third line registers a “dummy” “non-permissive” authorization policy using the testing_securitypolicy() method, which is a special helper method for unit testing.
We then create a pyramid.testing.DummyRequest object which simulates a WebOb request object API. A pyramid.testing.DummyRequest is a request object that requires less setup than a “real” Pyramid request. We call the function being tested with the manufactured request. When the function is called, pyramid.security.has_permission() will call the “dummy” authentication policy we’ve registered through testing_securitypolicy(), which denies access. We check that the view function raises a HTTPForbidden error.
The second test method, named test_view_fn_allowed tests the alternate case, where the authentication policy allows access. Notice that we pass different values to testing_securitypolicy() to obtain this result. We assert at the end of this that the view function returns a value.
257
23. UNIT, INTEGRATION, AND FUNCTIONAL TESTING
Note that the test calls the pyramid.testing.setUp() function in its setUp method and the pyramid.testing.tearDown() function in its tearDown method. We assign the result of pyramid.testing.setUp() as config on the unittest class. This is a Configurator object and all methods of the configurator can be called as necessary within tests. If you use any of the Configurator APIs during testing, be sure to use this pattern in your test case’s setUp and tearDown; these methods make sure you’re using a “fresh” application registry per test run.
See the pyramid.testing chapter for the entire Pyramid -specific testing API. This chapter describes APIs for registering a security policy, registering resources at paths, registering event listeners, registering views and view permissions, and classes representing “dummy” implementations of a request and a resource.
See also the various methods of the Configurator documented in pyramid.config that begin with the testing_ prefix.
23.3 Creating Integration Tests
In Pyramid, a unit test typically relies on “mock” or “dummy” implementations to give the code under test only enough context to run.
“Integration testing” implies another sort of testing. In the context of a Pyramid integration test, the test logic tests the functionality of some code and its integration with the rest of the Pyramid framework.
In Pyramid applications that are plugins to Pyramid, you can create an integration test by including its includeme function via pyramid.config.Configurator.include() in the test’s setup code. This causes the entire Pyramid environment to be set up and torn down as if your application was running “for real”. This is a heavy-hammer way of making sure that your tests have enough context to run properly, and it tests your code’s integration with the rest of Pyramid.
Let’s demonstrate this by showing an integration test for a view. The below test assumes that your application’s package name is myapp, and that there is a views module in the app with a function with the name my_view in it that returns the response ‘Welcome to this application’ after accessing some values that require a fully set up environment.
1 import unittest
2
3 from pyramid import testing
4
5 class ViewIntegrationTests(unittest.TestCase):
6def setUp(self):
7""" This sets up the application registry with the
8registrations your application declares in its ‘‘includeme‘‘
258
23.4. CREATING FUNCTIONAL TESTS
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
function.
"""
import myapp
self.config = testing.setUp() self.config.include(’myapp’)
def tearDown(self):
""" Clear out the application registry """
testing.tearDown()
def test_my_view(self):
from myapp.views import my_view request = testing.DummyRequest() result = my_view(request)
self.assertEqual(result.status, ’200 OK’) body = result.app_iter[0] self.failUnless(’Welcome to’ in body) self.assertEqual(len(result.headerlist), 2) self.assertEqual(result.headerlist[0],
(’Content-Type’, ’text/html; charset=UTF-8’)) self.assertEqual(result.headerlist[1], (’Content-Length’,
str(len(body))))
Unless you cannot avoid it, you should prefer writing unit tests that use the Configurator API to set up the right “mock” registrations rather than creating an integration test. Unit tests will run faster (because they do less for each test) and the result of a unit test is usually easier to make assertions about.
23.4 Creating Functional Tests
Functional tests test your literal application.
The below test assumes that your application’s package name is myapp, and that there is a view that returns an HTML body when the root URL is invoked. It further assumes that you’ve added a tests_require dependency on the WebTest package within your setup.py file. WebTest is a functional testing package written by Ian Bicking.
1
2
3
4
5
import unittest
class FunctionalTests(unittest.TestCase): def setUp(self):
from myapp import main
259
23. UNIT, INTEGRATION, AND FUNCTIONAL TESTING
6
7
8
9
10
11
12
app = main({})
from webtest import TestApp self.testapp = TestApp(app)
def test_root(self):
res = self.testapp.get(’/’, status=200) self.failUnless(’Pyramid’ in res.body)
When this test is run, each test creates a “real” WSGI application using the main function in your myapp.__init__ module and uses WebTest to wrap that WSGI application. It assigns the result to self.testapp. In the test named test_root, we use the testapp’s get method to invoke the root URL. We then assert that the returned HTML has the string Pyramid in it.
See the WebTest documentation for further information about the methods available to a webtest.TestApp instance.
260