Install & Compatibility
Where this runs
tested against v2.17.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.902s · 37.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.5s · import 0.840s · 52MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
run
✓ from tavern.core import run
For programmatic execution of Tavern tests.
tavern
✓ import tavern
General import for accessing core Tavern functionalities, though specific modules are often preferred.
validate_jwt, validate_regex, validate_content, check_jmespath_match
✓ from tavern.helpers import validate_jwt, validate_regex, validate_content, check_jmespath_match
Common validation helper functions for responses.
BaseRequest, BaseResponse
✓ from tavern.request import BaseRequest
from tavern.response import BaseResponse
For implementing custom request or response handlers.
To quickly get started, define your API tests in a `.tavern.yaml` file and execute them using `pytest`. Tavern automatically discovers and runs tests defined in files matching the `test_*.tavern.yaml` pattern when pytest is invoked.
import pytest
import os
# Create a dummy test_example.tavern.yaml file
with open('test_example.tavern.yaml', 'w') as f:
f.write("""
---
test_name: Get some fake data from the JSON placeholder API
stages:
- name: Make sure we have the right ID
request:
url: https://jsonplaceholder.typicode.com/posts/1
method: GET
response:
status_code: 200
json:
id: 1
""")
# Run pytest (this assumes pytest is installed and finds the .tavern.yaml file)
# In a real scenario, you'd run 'pytest' from the command line.
# For programmatic execution, you would use tavern.core.run directly.
print("Created test_example.tavern.yaml. Run 'pytest -v test_example.tavern.yaml' in your terminal.")
# For demonstration, we'll simulate running it (actual pytest.main() might exit the interpreter)
# pytest.main(['-v', 'test_example.tavern.yaml'])
tavern --version
Errors
Common errors & fixes
Expected only one document in this file but found multiple
This error typically occurs when a `.tavern.yaml` file contains multiple top-level YAML documents (separated by `---`) but only one `test_name` is expected, or when `is_defaults: true` is misused.
fixEnsure each logical test or set of tests is correctly structured as separate documents if intended, or that `is_defaults: true` is correctly applied to a single defaults document at the top of the file. Each test needs its own `test_name`.
KeyError: 'test_name'
A test definition in a `.tavern.yaml` file is missing the required `test_name` key.
fixAdd a unique `test_name` string to each test definition in your YAML file, e.g., `test_name: My API Test`.
tavern.util.exceptions.MissingExtFunctionError: Could not find external function 'your_function' in any of [...]
Tavern cannot locate a Python function referenced using `!ext` in your YAML test file. This often means the Python file containing the function is not on the Python path or the function name is incorrect.
fixEnsure the directory containing your Python module with the external function is included in the `PYTHONPATH` environment variable. Double-check the function name and module path in your YAML file.
yaml.scanner.ScannerError: mapping values are not allowed here
This is a general YAML syntax error, usually caused by incorrect indentation, missing colons, or improper use of special characters in the `.tavern.yaml` file.
fixCarefully review the YAML syntax around the indicated line and column in the error message. Pay close attention to indentation, colons, and valid YAML structure. Use a YAML linter if available.
Upgrade
Version history
3.6.1latest on PyPI · released Jun 14, 2026
Audit
Dependencies
pytestrequiredTavern operates as a pytest plugin, and its recommended usage is through pytest for test execution and ecosystem integration.
PythonrequiredRequires Python 3.11 or newer.