{"id":8702,"library":"tavern","title":"Tavern: API Testing Framework","description":"Tavern is a Python library, pytest plugin, and command-line tool designed for automated testing of APIs, including RESTful, MQTT, and gRPC services. It utilizes a simple, concise, and flexible YAML-based syntax for defining tests, making it highly customizable for complex scenarios. Currently at version 3.3.3, Tavern maintains an active development status and integrates seamlessly with the pytest ecosystem for comprehensive test management and reporting.","status":"active","version":"3.3.3","language":"en","source_language":"en","source_url":"https://github.com/taverntesting/tavern","tags":["API testing","REST","HTTP","integration testing","pytest","YAML","MQTT","gRPC"],"install":[{"cmd":"pip install tavern","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Tavern operates as a pytest plugin, and its recommended usage is through pytest for test execution and ecosystem integration.","package":"pytest","optional":false},{"reason":"Requires Python 3.11 or newer.","package":"Python","optional":false}],"imports":[{"note":"For programmatic execution of Tavern tests.","symbol":"run","correct":"from tavern.core import run"},{"note":"General import for accessing core Tavern functionalities, though specific modules are often preferred.","symbol":"tavern","correct":"import tavern"},{"note":"Common validation helper functions for responses.","symbol":"validate_jwt, validate_regex, validate_content, check_jmespath_match","correct":"from tavern.helpers import validate_jwt, validate_regex, validate_content, check_jmespath_match"},{"note":"For implementing custom request or response handlers.","symbol":"BaseRequest, BaseResponse","correct":"from tavern.request import BaseRequest\nfrom tavern.response import BaseResponse"}],"quickstart":{"code":"import pytest\nimport os\n\n# Create a dummy test_example.tavern.yaml file\nwith open('test_example.tavern.yaml', 'w') as f:\n    f.write(\"\"\"\n---\ntest_name: Get some fake data from the JSON placeholder API\nstages:\n  - name: Make sure we have the right ID\n    request:\n      url: https://jsonplaceholder.typicode.com/posts/1\n      method: GET\n    response:\n      status_code: 200\n      json:\n        id: 1\n\"\"\")\n\n# Run pytest (this assumes pytest is installed and finds the .tavern.yaml file)\n# In a real scenario, you'd run 'pytest' from the command line.\n# For programmatic execution, you would use tavern.core.run directly.\nprint(\"Created test_example.tavern.yaml. Run 'pytest -v test_example.tavern.yaml' in your terminal.\")\n# For demonstration, we'll simulate running it (actual pytest.main() might exit the interpreter)\n# pytest.main(['-v', 'test_example.tavern.yaml'])","lang":"python","description":"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."},"warnings":[{"fix":"Set the `TAVERN_INCLUDE` environment variable or provide correct relative paths in your `!include` directives. Example: `export TAVERN_INCLUDE=/path/to/common_files`","message":"When using `!include` for shared YAML snippets (e.g., common stages or configurations), ensure the `TAVERN_INCLUDE` environment variable is set with the absolute path to the directory containing included files, or use correct relative paths. Otherwise, Tavern might not locate the included files.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Rename your test files to `test_yourtestname.tavern.yaml`.","message":"Files containing Tavern tests intended for execution with `pytest` must follow the `test_*.tavern.yaml` naming convention for automatic discovery. Files not adhering to this pattern will be ignored by pytest.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Place `is_defaults: true` only in the initial YAML document of a file. Do not include `test_name` or `stages` within the defaults document.","message":"The `is_defaults: true` flag for sharing common configuration across multiple tests in a single YAML file should only be used in the *first* document within that file. Subsequent documents will merge its contents, with test-specific values taking precedence. The defaults document itself cannot contain test definitions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade Tavern to version 0.26.5 or newer. If unable to upgrade, pin your `pytest` dependency to `<4.6.0`.","message":"Older versions of Tavern (prior to 0.26.5) experienced breaking compatibility with `pytest` versions 4.6.0 and above due to internal API changes in `pytest`. While this was addressed in newer Tavern releases, users on older Tavern versions might face issues.","severity":"deprecated","affected_versions":"<0.26.5"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure 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`.","cause":"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.","error":"Expected only one document in this file but found multiple"},{"fix":"Add a unique `test_name` string to each test definition in your YAML file, e.g., `test_name: My API Test`.","cause":"A test definition in a `.tavern.yaml` file is missing the required `test_name` key.","error":"KeyError: 'test_name'"},{"fix":"Ensure 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.","cause":"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.","error":"tavern.util.exceptions.MissingExtFunctionError: Could not find external function 'your_function' in any of [...]"},{"fix":"Carefully 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.","cause":"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.","error":"yaml.scanner.ScannerError: mapping values are not allowed here"}]}