tavern-testing

Overview

Tavern is "a pytest plugin, command-line tool, and Python library for automated testing of APIs, with a simple, concise, and flexible YAML-based syntax" (tavern-docs (opens in new window)). Tests live in test_*.tavern.yaml files and are picked up automatically by pytest's discovery mechanism.

The integration shape: write YAML, run pytest, read JUnit XML. Tavern adds zero Python code to the test surface - the YAML IS the test. This is the closest thing to "code-less" API testing in the Python ecosystem.

When to use

• The project's primary test runner is pytest (Python) and the team wants API tests in the same harness as unit tests.
• The team prefers YAML over a fluent DSL - tests are reviewed by non-engineers (PMs, support engineers).
• The API surface includes non-HTTP protocols (MQTT, gRPC) - Tavern has first-party support for both.
• A pytest project already has fixtures (database setup, auth tokens) that the API tests should reuse.

If the team is already deep in REST Assured or Karate, switching to Tavern is rarely worthwhile. If the team is on Node, use postman-collections instead.

Install

pip install tavern[pytest]

(Per tavern-docs (opens in new window).)

For richer matchers, the optional extras include tavern[mqtt], tavern[grpc], and tavern[mocking]. Install only what the project needs.

File shape

tests/api/test_orders.tavern.yaml:

---
test_name: Get an order returns the expected fields

stages:
  - name: Authenticate
    request:
      url: https://staging.example.com/auth/login
      method: POST
      json:
        username: !env STAGING_USER
        password: !env STAGING_PASS
    response:
      status_code: 200
      save:
        json:
          access_token: access_token

  - name: Fetch order 42
    request:
      url: https://staging.example.com/orders/42
      method: GET
      headers:
        Authorization: 'Bearer {access_token}'
    response:
      status_code: 200
      json:
        order_id: 42
        status: !anything
        items:
          - sku: !anystr
            qty: !anyint

(Adapted from tavern-docs (opens in new window).)

Per tavern-docs (opens in new window):

• File name pattern: test_*.tavern.yaml. Pytest auto-discovers.
• Each YAML doc (--- separated) is one test.
• test_name is the visible test title in pytest output.
• stages: is an ordered list; each stage is one HTTP request + response check.

Request block

Each stage's request: accepts:

Variable interpolation uses Python's str.format style: '{access_token}'.

Response block

Each stage's response: accepts:

Built-in matchers

Per tavern-docs (opens in new window):

Variable saving

The save: block captures values for later stages. Two common forms:

response:
  status_code: 200
  save:
    json:
      # Save response.json()['access_token'] as variable `access_token`
      access_token: access_token
    headers:
      # Save the Location header as variable `created_url`
      created_url: location

Saved variables are interpolated in subsequent stages with '{access_token}'.

Authentication

For OAuth2 / token-based auth, the canonical pattern is a two-stage test where the first stage authenticates and save:s the token, the second stage uses it (see the worked example above).

For HTTP Basic Auth:

request:
  url: ...
  method: GET
  auth:
    - !env API_USER
    - !env API_PASS

For API key in header:

request:
  url: ...
  headers:
    X-API-KEY: !env API_KEY

!env VAR resolves the env var at run time; never put secrets in the YAML directly.

Global config

For shared base URLs, default headers, or strict-checking flags, create tavern-global-config.yaml:

variables:
  base_url: https://staging.example.com
  default_timeout: 5
strict:
  - json:on

Reference variables in any YAML test file: url: '{base_url}/orders/42'.

Running

# Run every Tavern YAML file
pytest tests/api/

# Run a specific YAML file
pytest tests/api/test_orders.tavern.yaml

# Run with verbose output (helpful for debugging stage failures)
pytest -v tests/api/

# Generate JUnit XML for CI ingestion
pytest tests/api/ --junitxml=results.xml

(Per tavern-docs (opens in new window).)

CI integration

# .github/workflows/api-tests.yml
name: api-tests

on:
  pull_request:
  push:
    branches: [main]

jobs:
  tavern:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install
        run: pip install -r requirements-test.txt   # contains 'tavern[pytest]'

      - name: Run Tavern suite
        env:
          STAGING_USER: ${{ secrets.STAGING_USER }}
          STAGING_PASS: ${{ secrets.STAGING_PASS }}
          API_KEY:      ${{ secrets.API_KEY }}
        run: |
          pytest tests/api/ \
            --junitxml=results.xml \
            --tavern-global-cfg=tavern-global-config.yaml

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: tavern-reports
          path: results.xml
          retention-days: 14

      - name: Surface JUnit results
        if: always()
        uses: dorny/test-reporter@v1
        with:
          name: Tavern API tests
          path: results.xml
          reporter: java-junit

Anti-patterns

Limitations

• Pytest-only. No standalone runner; the YAML files don't run outside pytest's discovery.
• Limited dynamic logic. Tavern is intentionally declarative; for branching, retries, or computed expectations, drop into a pytest fixture or a custom validator referenced via verify_response_with.
• Schema validation needs an extra dependency. For JSON Schema enforcement, install a separate matcher; built-in matchers cover shape but not full schema constraints.
• Variable interpolation can mask null bugs. A typo in '{accest_token}' (missing s) won't error - the literal string goes through. Watch for these in code review.

References

• tavern-docs (opens in new window) - canonical reference: install, file shape, request / response / save / matchers, pytest integration, global config.
• postman-collections - Node-stack alternative.
• restassured-testing - Java fluent-DSL alternative.
• schemathesis-fuzzing - Python-stack property-based fuzzing complement to Tavern's example-based tests.