Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Documentation Status Coverage Status Requirements Status

Dead simple descriptive testing for Python. No custom decorators, no context managers, no .feature files, no fuss.

Contexts is a 'Context-Specification'-style test framework for Python 3.3 and above, inspired by C#'s Machine.Specifications. It aims to be flexible and extensible, and is appropriate for unit, integration and acceptance testing. Read more at the Huddle Dev Blog.

Test written with Contexts resemble the grammar of 'Given/When/Then'-style specifications. Writing tests which read like user-centric sentences can encourage you to focus on the behaviour, not the implementation, of your code. Contexts takes cues from Behaviour Driven Development, but it aims to be useful for more than just acceptance testing (unlike Cucumber or FitNesse).

Cool features

  • Give your tests descriptive names so you can tell what's gone wrong when they fail!
  • Run all the assertions for each test case, even when one fails!
  • Practice 'Example-Driven-Development' with parametrised tests!
  • Extend Contexts by writing your own plugins!
  • Use the assert statement and still get helpful failure messages!
  • Test all the things!


Contexts is on the Cheese Shop, so you can install it the easy way:

pip install contexts

If you want the bleeding-edge version, you can install it the geeky way:

git clone
cd Contexts
python install

Contexts has no compulsory external dependencies. There is an optional dependency - if you like red and green colours in the output from your test runner (and who doesn't!), you need to install Colorama.

Quick start

Here's an example of a test case that the authors of Requests might have written, if they were using Contexts. See the documentation for details and more examples.

import requests
# no need to import contexts!

class WhenRequestingAResourceThatDoesNotExist:
    def given_that_we_are_asking_for_a_made_up_resource(self):
        self.uri = ""
        self.session = requests.Session()

    def because_we_make_a_request(self):
        self.response = self.session.get(self.uri)

    def the_response_should_have_a_status_code_of_404(self):
        assert self.response.status_code == 404

    def the_response_should_have_an_HTML_content_type(self):
        assert self.response.headers['content-type'] == 'text/html'

    def cleanup_the_session(self):

Running your tests

Type run-contexts at the command line to discover and run test files and folders in your working directory.


All the documentation is stored on readthedocs.


Descriptive testing for Python




You can’t perform that action at this time.