pecan/docs/source/testing.rst

Unit Testing

UnitTesting in Pecan is handled by WebTest. It creates a fake Pecan application that in turn allows you to make assertions on how those requests and responses are being handled without starting an HTTP server at all.

Tools

Pecan recommends using py.test. It is actually a project requirement when you install Pecan so you should already have it installed.

Structure

This guide assumes that you have all your tests in a tests directory. If you have created a project from the base project template that Pecan provides you should already have this directory with a few tests.

The template project uses UnitTest-type tests and some of those tests use WebTest. We will describe how they work in the next section.

This is how running those tests with py.test would look like:

$ py.test
============== test session starts =============
platform darwin -- Python 2.6.1 -- pytest-2.0.1
collected 11 items 

./tests/test_config.py .........
./tests/test_root.py ..

========== 11 passed in 0.30 seconds ===========

Configuration and Testing

When running tests, you would want to avoid as much as possible setting up test cases by creating a Pecan app on each instance. To avoid this, you need to create a proper test configuration file and load it at setup time.

To do this, you need to know the absolute path for your configuration file and then call set_config with it. A typical setUp method would look like:

def setUp(self):
    config_path = '/path/to/test_config.py'
    pecan.set_config(config_path)

    self.app = TestApp(
        make_app(
            config.app.root
            template_path   = config.app.template_path
        )
    )

As you can see, we are loading the configuration file into Pecan first and then creating a Pecan application with it. Any interaction after setUp will be exactly as if your application was really running via an HTTP server.

Using WebTest with a UnitTest

Once you have a setUp method with your Pecan configuration loaded you have a wealth of actions provided within the test class to interact with your Pecan application:

*  POST   => self.app.post
*  GET    => self.app.get
*  DELETE => self.app.delete
*  PUT    => self.app.put

For example, if I wanted to assert that I can get the root of my application, I would probably do something similar to this:

response = self.app.get('/') assert response.status_int == 200

If you are expecting error responses from your application, you should make sure that you pass the expect_errors flag and set it to True:

response = self.app.get('/url/does/not/exist', expect_errors=True)
assert response.status_int == 404

If you would like to dig in to more examples in how to test and verify more actions, make sure you take a look at the WebTest documentation