Navigation

Unit testing is, not surprisingly, the act of testing a “unit” in your
application. In this context, a “unit” is often a function or a method of a
class instance. The unit is also referred to as a “unit under test”.

The goal of a single unit test is to test only some permutation of the
“unit under test”. If you write a unit test that aims to verify the result
of a particular codepath through a Python function, you need only be
concerned about testing the code that lives in the function body itself.
If the function accepts a parameter that represents a complex application
“domain object” (such as a resource, a database connection, or an SMTP
server), the argument provided to this function during a unit test need not
be and likely should not be a “real” implementation object. For example,
although a particular function implementation may accept an argument that
represents an SMTP server object, and the function may call a method of this
object when the system is operating normally that would result in an email
being sent, a unit test of this codepath of the function does not need to
test that an email is actually sent. It just needs to make sure that the
function calls the method of the object provided as an argument that would
send an email if the argument happened to be the “real” implementation of an
SMTP server object.

An integration test, on the other hand, is a different form of testing in
which the interaction between two or more “units” is explicitly tested.
Integration tests verify that the components of your application work
together. You might make sure that an email was actually sent in an
integration test.

A functional test is a form of integration test in which the application is
run “literally”. You would have to make sure that an email was actually
sent in a functional test, because it tests your code end to end.

It is often considered best practice to write each type of tests for any
given codebase. Unit testing often provides the opportunity to obtain better
“coverage”: it’s usually possible to supply a unit under test with arguments
and/or an environment which causes all of its potential codepaths to be
executed. This is usually not as easy to do with a set of integration or
functional tests, but integration and functional testing provides a measure of
assurance that your “units” work together, as they will be expected to when
your application is run in production.

The suggested mechanism for unit and integration testing of a Pyramid
application is the Python unittest module. Although this module is
named unittest, it is actually capable of driving both unit and
integration tests. A good unittest tutorial is available within Dive
Into Python by Mark
Pilgrim.

Pyramid provides a number of facilities that make unit, integration,
and functional tests easier to write. The facilities become particularly
useful when your code calls into Pyramid -related framework functions.

Pyramid uses a “global” (actually thread local) data structure
to hold on to two items: the current request and the current
application registry. These data structures are available via the
pyramid.threadlocal.get_current_request() and
pyramid.threadlocal.get_current_registry() functions, respectively.
See Thread Locals for information about these functions and the
data structures they return.

If your code uses these get_current_* functions or calls Pyramid
code which uses get_current_* functions, you will need to call
pyramid.testing.setUp() in your test setup and you will need to call
pyramid.testing.tearDown() in your test teardown.
setUp() pushes a registry onto the thread
local stack, which makes the get_current_* functions work. It returns a
Configurator object which can be used to perform extra configuration
required by the code under test. tearDown() pops the
thread local stack.

Normally when a Configurator is used directly with the main block of
a Pyramid application, it defers performing any “real work” until its
.commit method is called (often implicitly by the
pyramid.config.Configurator.make_wsgi_app() method). The
Configurator returned by setUp() is an
autocommitting Configurator, however, which performs all actions
implied by methods called on it immediately. This is more convenient
for unit-testing purposes than needing to call
pyramid.config.Configurator.commit() in each test after adding
extra configuration statements.

The use of the setUp() and
tearDown() functions allows you to supply each unit
test method in a test case with an environment that has an isolated registry
and an isolated request for the duration of a single test. Here’s an example
of using this feature:

The above will make sure that
get_current_registry() called within a test
case method of MyTest will return the application registry
associated with the config Configurator instance. Each test case
method attached to MyTest will use an isolated registry.

The setUp() and tearDown()
functions accepts various arguments that influence the environment of the
test. See the pyramid.testing chapter for information about the extra
arguments supported by these functions.

If you also want to make get_current_request() return something
other than None during the course of a single test, you can pass a
request object into the pyramid.testing.setUp() within the
setUp method of your test:

If you pass a request object into pyramid.testing.setUp()
within your test case’s setUp, any test method attached to the
MyTest test case that directly or indirectly calls
get_current_request() will receive the request
object. Otherwise, during testing,
get_current_request() will return None.
We use a “dummy” request implementation supplied by
pyramid.testing.DummyRequest because it’s easier to construct
than a “real” Pyramid request object.

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.

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.

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.

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.pytest 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.

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.

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 it’s 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.

importunittestfrompyramidimporttestingclassViewIntegrationTests(unittest.TestCase):defsetUp(self):""" This sets up the application registry with the registrations your application declares in its ``includeme`` function. """importmyappself.config=testing.setUp()self.config.include('myapp')deftearDown(self):""" Clear out the application registry """testing.tearDown()deftest_my_view(self):frommyapp.viewsimportmy_viewrequest=testing.DummyRequest()result=my_view(request)self.assertEqual(result.status,'200 OK')body=result.app_iter[0]self.failUnless('Welcome to'inbody)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.

The below test assumes that your application’s package name is myapp, and
that there is 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.

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.