Tavern: YAML API tests that run under pytest

A pytest plugin that happens to speak YAML

Tavern is a pytest plugin, a command line tool and a Python library for automated testing of APIs, with a simple, concise and flexible YAML-based syntax, and it supports RESTful APIs, MQTT based APIs and gRPC services.

The README is clear about which of those three faces to use. The best way to use Tavern is with pytest. Tavern comes with a pytest plugin, so all you have to do is install pytest and Tavern, write your tests in .tavern.yaml files, and run pytest. You get the whole pytest ecosystem as a consequence, which the README spells out: you can regularly run your tests against a test server, report failures, and generate HTML reports.

The other two faces exist for the cases where that does not work. You can integrate Tavern into your own test framework or continuous integration setup using the Python library, or you can use the command line tool, tavern-ci, with bash scripts and cron jobs.

That ordering matters when you evaluate the tool. Tavern is not a testing framework that happens to have a pytest adapter, it is a testing format that happens to run inside pytest, and the pytest integration is the reason it is pleasant to use rather than a bolt-on.

The project started in 2017, and the README describes it as still in active development and used by 100s of companies, with the documentation and a large set of examples hosted at taverntesting.github.io.

The test file format, which is the whole interface

A Tavern test is a YAML document with a name and a list of stages, and the minimal example in the README is short enough to see the entire model at once.

---
# 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)
stages:
  - name: Make sure we have the right ID

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

    # ...and the expected response code and body
    response:
      status_code: 200
      json:
        id: 1
        userId: 1
        title: "sunt aut facere repellat provident occaecati excepturi optio reprehenderit"

A file can have any name, but if you intend to use pytest with Tavern it will only pick up files called test_*.tavern.yaml.

The design decisions in that snippet are the ones worth copying into a team convention. The file is a list of stages rather than a list of assertions, so a multi-step flow, a login followed by a call followed by a check, reads in the order it runs. The request and the expected response are separate blocks, so the document states what was asked and what came back. And the expected body is given as structured data rather than a string comparison, which is what makes the failure messages readable.

The README's promise that you should not need the docs open all the time is a promise about this format, and the YAML anchors it mentions in the why section exist so that repeated request shapes can be defined once and reused across stages.

Two ways to run it, and why pytest is advised

Running through pytest is the recommended path, and the extra to install is the pytest plugin:

$ pip install tavern[pytest]
$ py.test test_minimal.tavern.yaml  -v

The README says it is strongly advised that you use Tavern with pytest, and gives the reason: not only does it have a lot of utility to control discovery and execution of tests, there are a huge amount of plugins to improve your development experience.

If you cannot use pytest for some reason, the fallback is the tavern-ci command line interface, which is installed with the plain package:

$ pip install tavern
$ tavern-ci --stdout test_minimal.tavern.yaml

The --stdout flag is what makes the difference in practice, because it prints the request and response for each stage as it runs, in a form you can read when a test fails in CI. The library route, using Tavern as a Python library inside an existing framework or CI setup, is the third option and the most flexible.

The three routes share the same YAML, which is the point. Whether the test runs in a local pytest session, in a CI job driven by bash and cron, or inside a bespoke Python harness, the test file is the same document, and that is what makes a shared test suite across teams possible.

Why the README argues against Postman and Insomnia

The section headed Why not Postman, Insomnia or pyresttest is the most argumentative part of the README, and also the most useful for an adopter.

The framing is that Tavern is a focused tool which does one thing well, automated testing of APIs. Postman and Insomnia are excellent tools covering a wide range of use cases, and the author says plainly that they use Tavern alongside Postman. The advantages listed for Tavern in the automated testing context are a full-featured Python environment for writing easily reusable custom validation functions, testing of MQTT based systems and gRPC services in tandem with RESTful APIs, integration with pytest to keep all your tests in one place, and a simpler, less verbose and clearer testing language.

Then the honest part. Tavern does not do many of the things Postman and Insomnia do. It has no GUI, it does not do API monitoring, and it does not do mock servers. The counterweight given is that Tavern is free and open source and a more powerful tool for developers to automate tests.

The pyresttest comparison is similar. That project is a similar tool for testing RESTful APIs but is no longer actively developed, and Tavern's advantages over it are a cleaner test syntax which is more intuitive especially for non-developers, more flexible and easier to use validation functions, and better explanations of why a test failed.

That last point is the one that decides it for many teams. A test framework is judged as much by its failure output as by its assertions, and a YAML document with structured expectations has more to say about a failure than a recorded HTTP session does.

What the dependency list reveals

The package metadata is a good summary of what Tavern is. The build backend is flit-core, the project name is tavern with the description Simple testing of RESTful APIs, the author is Michael Boulton, and the licence is MIT.

The runtime dependencies are short and each one tells you a feature. PyYAML is the format itself. jmespath is the query language used to pick values out of a response. jsonschema validates response bodies against a schema. pydantic handles the typed models. pyjwt is there for tokens, and pykwalify is a schema validation library. pytest is a hard dependency, at 8 or newer, which is the clearest statement of the design. python-box gives dictionary access with attribute style, requests is the HTTP client, simpleeval is the expression evaluator used for templating values into requests, and stevedore provides the command line entry point plumbing.

The classifiers say Development Status 5 - Production/Stable, Framework :: Pytest, and Python 3.11 to 3.13, with requires-python of 3.11 or newer. The Python floor is the thing to check first, since it is higher than the version in the README's own example output, which shows a Python 3.5 environment from the era when the project started.

The repository layout matches the three protocol stories, with example/ directories for allure reporting, a custom backend, generating tests from an OpenAPI description, GraphQL, gRPC, HTTP and MQTT, plus a tests/ directory, a docs/ tree with a MyST configuration, tox and tox-integration configurations, a pre-commit configuration and an AGENTS.md.

Where Tavern is the wrong tool

The first wrong-tool case is a team that needs a graphical client or API monitoring. The README says Tavern has no GUI, does not do API monitoring and does not do mock servers, and it is not trying to. A team that wants to poke at an API by hand while developing, and record the interaction, is looking for Postman or Insomnia, and a team that wants to watch production traffic is looking for something else entirely.

The second is a team that does not write Python. Every escape hatch in Tavern is a Python escape hatch, since the README says that for everything else it is straightforward to drop into Python or pytest to extend, using fixtures, hooks, and things you already know. The YAML is the friendly surface and Python is the floor underneath it, and a team without Python fluency is choosing a tool whose worst case is writing Python.

The third is a codebase whose API tests are mostly one request and one status code. Tavern's value is in multi-stage flows with shared validation and readable failure output, and a suite that only checks status codes would be better served by a few lines in whatever test framework the project already has.

There is also a governance point for teams that take testing seriously. A YAML test suite has no static type checking, and a validation function written in Python inside a YAML file is code that no type checker sees. A team with strict static analysis requirements should look at how the Python escape hatch is used before committing to the format.

MIT, a stable classifier and an unversioned release channel

The project is licensed MIT, with the LICENSE file at the repository root, and the default branch is master. The repository is not archived, and the last push was on 2026-10-13.

There are no GitHub releases, which is a bit surprising for a package that has been distributed since 2017 and is on PyPI with a version badge. The packaging instead derives the version dynamically, with the version declared dynamic in the project metadata, and the CHANGELOG.md at the root is the history. For a library whose whole value is that it sits in the middle of a pytest pipeline, where the version is rarely the thing that breaks, that is a defensible arrangement rather than an oversight.

The classifiers are the more interesting signal. Development Status 5 - Production/Stable, Framework :: Pytest, Intended Audience Developers, and the topic Software Development :: Testing. A tool that calls itself production stable while also saying it is in active development is describing something real, because the format is stable and the ecosystem around it is still growing.

The community signals are also good. There is a Discord, a Gitter channel in the badges, an issue tracker, a contributing guide, and a documentation site with a separate examples site, which is the shape of a project that has been maintained by the same small group for a long time.

Editorial conclusion

Adopt Tavern if your team already lives in pytest and wants API tests as reviewable YAML in the same repository as the code, especially if you also need to test MQTT or gRPC services alongside REST. Do not adopt it if you need a graphical client, API monitoring or a mock server, since the README is explicit that Tavern does none of those, and do not adopt it if your team does not write Python, since the escape hatch for anything unusual is dropping into Python and pytest. Before you commit, read the comparison with Postman and pyresttest in the README, because the choice of a focused tool over a general one is a real trade, and check the Python version requirement, since the package needs 3.11 or newer.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. taverntesting/tavern on GitHub