Easier API testing

Tavern is a pytest plugin, command-line tool and Python 3 library for automated testing of APIs, with a simple, concise and flexible YAML-based syntax. It’s very simple to get started, and highly customisable for complex tests. Tavern supports testing RESTful APIs as well as MQTT based APIs.

The best way to use Tavern is with pytest. Tavern comes with a pytest plugin so that literally all you have to do is install pytest and Tavern, write your tests in .tavern.yaml files and run pytest. This means you get access to all of the pytest ecosystem and allows you to do all sorts of things like regularly run your tests against a test server and report failures or generate HTML reports.

You can also integrate Tavern into your own test framework or continuous integration setup using the Python library, or use the command line tool, tavern-ci with bash scripts and cron jobs.

To learn more, check out the examples or the complete documentation. If you’re interested in contributing to the project take a look at the GitHub repo.


$ pip install tavern
# minimal_test.tavern.yaml

# Every test file has one or more tests...
test_name: Get some fake data from the JSON placeholder API

# ...and each test has one or more stages (e.g. an HTTP request)
  - name: Make sure we have the right ID

    # Define the request to be made...
      url: https://jsonplaceholder.typicode.com/posts/1
      method: GET

    # ...and the expected response code and body
      status_code: 200
        id: 1
$ tavern-ci --stdout minimal_test.tavern.yaml
2017-11-08 16:17:00,152 [INFO]: (tavern.core:55) Running test : Get some fake data from the JSON placeholder API
2017-11-08 16:17:00,153 [INFO]: (tavern.core:69) Running stage : Make sure we have the right ID
2017-11-08 16:17:00,239 [INFO]: (tavern.core:73) Response: '<Response [200]>' ({
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
2017-11-08 16:17:00,239 [INFO]: (tavern.printer:9) PASSED: Make sure we have the right ID [200]

Why not Postman, Insomnia or pyresttest etc?

Tavern is a focused tool which does one thing well: automated testing of APIs.

Postman and Insomnia are excellent tools which cover a wide range of use-cases for RESTful APIs, and indeed we use Tavern alongside Postman. However, specifically with regards to automated testing, Tavern has several advantages over Postman:

Tavern does not do many of the things Postman and Insomnia do. For example, Tavern does not have a GUI nor does it do API monitoring or mock servers. On the other hand, Tavern is free and open-source and is a more powerful tool for developers to automate tests.

pyresttest is a similar tool to Tavern for testing RESTful APIs, but is no longer actively developed. On top of MQTT testing, Tavern has several other advantages over PyRestTest which overall add up to a better developer experience:

Hacking on Tavern

If you want to add a feature to Tavern or just play around with it locally, it’s a good plan to first create a local development environment (this page has a good primer for working with development environments with Python). After you’ve created your development environment, just pip install tox and run tox to run the unit tests. If you want to run the integration tests, make sure you have docker installed and run tox -c tox-integraton.ini. It’s that simple!

If you want to add a feature to get merged back into mainline Tavern, then simply add the feature and some tests (probably just unit tests - adding integration tests is a bit more involved as it requires implementing the behaviour you’re testing) and open a pull request. Note that Tavern supports Python 2.7 (for the time being), so any code you add has to be compatible with it. We currently use the future library to provide backwards compatibility.


Tavern makes use of several excellent open-source projects:

Developed and maintained by Overlock

Overlock helps developers quickly find and fix bugs in distributed systems such as IoT deployments by gathering together exception information from end devices, gateways or servers. We’re currently in beta - find out more at overlock.io