Flask-Testing

The Flask-Testing extension provides unit testing utilities for Flask.

Source code and issue tracking at Bitbucket.

Installing Flask-Testing

Install with pip and easy_install:

pip install Flask-Testing

or download the latest version from Bitbucket:

hg clone http://bitbucket.org/danjac/flask-testing

cd flask-testing

python setup.py develop

If you are using virtualenv, it is assumed that you are installing Flask-Testing in the same virtualenv as your Flask application(s).

Writing unit tests

Simply subclass the TestCase class:

from flaskext.testing import TestCase

class MyTest(TestCase):

    pass

You must specify the create_app method, which should return a Flask instance:

from flaskext.testing import TestCase

class MyTest(TestCase):

    def create_app(self):

        app = Flask(__name__)
        app.config['TESTING'] = True
        return app

If you don’t define create_app a NotImplementedError will be raised.

Testing JSON responses

If you are testing a view that returns a JSON response, you can test the output using a special json attribute appended to the Response object:

@app.route("/ajax/")
def some_json():
    return jsonify(success=True)

class TestViews(TestCase):
    def test_some_json(self):
        response = self.client.get("/ajax/")
        self.assertEquals(response.json, dict(success=True))

Using with Twill

Twill is a simple language for browing the Web through a command line interface. You can use it in conjunction with TwillTestCase to write functional tests for your views.

TwillTestCase is a subclass of TestCase. It sets up Twill for use with your test cases. See the API below for details.

Testing with SQLAlchemy

This covers a couple of points if you are using Flask-Testing with SQLAlchemy. It is assumed that you are using the Flask-SQLAlchemy extension, but if not the examples should not be too difficult to adapt to your own particular setup.

First, ensure you set the database URI to something other than your production database ! Second, it’s usually a good idea to create and drop your tables with each test run, to ensure clean tests:

from flaskext.testing import TestCase

from myapp import create_app, db

class MyTest(TestCase):

    SQLALCHEMY_DATABASE_URI = "sqlite://"
    TESTING = True

    def create_app(self):

        # pass in test configuration
        return create_app(self)

    def setUp(self):

        db.create_all()

    def tearDown(self):

        db.session.remove()
        db.drop_all()

Notice also that db.session.remove() is called at the end of each test, to ensure the SQLAlchemy session is properly removed and that a new session is started with each test run - this is a common “gotcha”.

Also notice that for this example the SQLite in-memory database is used : while it is faster for tests, if you have database-specific code (e.g. for MySQL or PostgreSQL) it may not be applicable.

You may also want to add a set of instances for your database inside of a setUp() once your database tables have been created. If you want to work with larger sets of data, look at Fixture which includes support for SQLAlchemy.

API

class flaskext.testing.TestCase(methodName='runTest')
assert200(response)

Checks if response status code is 200

Parameters:
  • response – Flask response
assert403(response)

Checks if response status code is 403

Versionadded :

0.2

Parameters:
  • response – Flask response
assert404(response)

Checks if response status code is 404

Parameters:
  • response – Flask response
assert405(response)

Checks if response status code is 405

Versionadded :

0.2

Parameters:
  • response – Flask response
assertContext(name, value)

Checks if given name exists in the template context and equals the given value.

Versionadded :

0.2

Parameters:
  • name – name of context variable
  • value – value to check against
assertRedirects(response, location)

Checks if response is an HTTP redirect to the given location.

Parameters:
  • response – Flask response
  • location – relative URL (i.e. without http://localhost)
assertStatus(response, status_code)

Helper method to check matching response status.

Parameters:
  • response – Flask response
  • status_code – response status code (e.g. 200)
assertTemplateUsed(name)

Checks if a given template is used in the request. Only works if your version of Flask has signals support (0.6+) and blinker is installed.

Versionadded :

0.2

Parameters:
  • name – template name
assert_200(response)

Checks if response status code is 200

Parameters:
  • response – Flask response
assert_403(response)

Checks if response status code is 403

Versionadded :

0.2

Parameters:
  • response – Flask response
assert_404(response)

Checks if response status code is 404

Parameters:
  • response – Flask response
assert_405(response)

Checks if response status code is 405

Versionadded :

0.2

Parameters:
  • response – Flask response
assert_context(name, value)

Checks if given name exists in the template context and equals the given value.

Versionadded :

0.2

Parameters:
  • name – name of context variable
  • value – value to check against
assert_redirects(response, location)

Checks if response is an HTTP redirect to the given location.

Parameters:
  • response – Flask response
  • location – relative URL (i.e. without http://localhost)
assert_status(response, status_code)

Helper method to check matching response status.

Parameters:
  • response – Flask response
  • status_code – response status code (e.g. 200)
assert_template_used(name)

Checks if a given template is used in the request. Only works if your version of Flask has signals support (0.6+) and blinker is installed.

Versionadded :

0.2

Parameters:
  • name – template name
create_app()

Create your Flask app here, with any configuration you need.

get_context_variable(name)

Returns a variable from the context passed to the template. Only works if your version of Flask has signals support (0.6+) and blinker is installed.

Raises a ContextVariableDoesNotExist exception if does not exist in context.

Versionadded :

0.2

Parameters:
  • name – name of variable
class flaskext.testing.TwillTestCase(methodName='runTest')

TestCase with Twill helper methods.

Creates a Twill browser instance and handles WSGI intercept.

make_twill_url(url)

Makes complete URL based on host, port and scheme Twill settings.

Parameters:
  • url – relative URL