0
# Tavern
1

2
A comprehensive API testing framework that serves as a pytest plugin, command-line tool, and Python library for automated testing of RESTful APIs and MQTT-based systems. Tavern features a YAML-based test syntax that is both simple and highly customizable, allowing developers to write clear, maintainable API tests with minimal boilerplate.
3

4
## Package Information
5

6
- **Package Name**: tavern
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install tavern`
10
- **CLI Tool**: `tavern-ci`
11

12
## Core Imports
13

14
```python
15
import tavern
16
```
17

18
For programmatic test execution:
19

20
```python
21
from tavern.core import run
22
```
23

24
For validation helpers:
25

26
```python
27
from tavern.helpers import (
28
    validate_jwt,
29
    validate_regex,
30
    validate_content,
31
    check_jmespath_match
32
)
33
```
34

35
For custom test implementations:
36

37
```python
38
from tavern.request import BaseRequest
39
from tavern.response import BaseResponse
40
```
41

42
## Basic Usage
43

44
### Command Line Usage
45

46
```bash
47
# Run a single test file
48
tavern-ci test_api.tavern.yaml
49

50
# Run with logging
51
tavern-ci --stdout --debug test_api.tavern.yaml
52

53
# Run with global configuration
54
tavern-ci --tavern-global-cfg config.yaml test_api.tavern.yaml
55
```
56

57
### Programmatic Usage
58

59
```python
60
from tavern.core import run
61

62
# Run tests programmatically
63
exit_code = run(
64
    in_file="test_api.tavern.yaml",
65
    tavern_global_cfg="config.yaml",
66
    tavern_strict=True
67
)
68

69
# Check if all tests passed
70
if exit_code == 0:
71
    print("All tests passed!")
72
else:
73
    print("Some tests failed!")
74
```
75

76
### YAML Test Example
77

78
```yaml
79
# test_api.tavern.yaml
80
test_name: Test user creation API
81

82
stages:
83
  - name: Create new user
84
    request:
85
      url: https://api.example.com/users
86
      method: POST
87
      json:
88
        name: "John Doe"
89
        email: "john@example.com"
90
    response:
91
      status_code: 201
92
      json:
93
        id: !anyint
94
        name: "John Doe"
95
        email: "john@example.com"
96
      save:
97
        json:
98
          user_id: id
99

100
  - name: Get created user
101
    request:
102
      url: https://api.example.com/users/{user_id}
103
      method: GET
104
    response:
105
      status_code: 200
106
      json:
107
        id: "{user_id}"
108
        name: "John Doe"
109
```
110

111
## Architecture
112

113
Tavern uses a plugin-based architecture that supports multiple protocols and testing patterns:
114

115
- **Core Engine**: Test execution, validation, and configuration management
116
- **Pytest Integration**: Seamless integration with pytest ecosystem and tooling
117
- **Plugin System**: Extensible architecture supporting HTTP, MQTT, and gRPC protocols
118
- **YAML DSL**: Declarative test specification language with variable templating
119
- **Response Validation**: Comprehensive validation using JMESPath, regex, and custom functions
120

121
The framework is designed for maximum developer productivity in API testing workflows, offering both declarative YAML-based testing and programmatic Python API access.
122

123
## Capabilities
124

125
### Core Test Execution
126

127
Primary interface for running Tavern tests programmatically or via command line. Supports global configuration, backend selection, and pytest integration.
128

129
```python { .api }
130
def run(
131
    in_file: str,
132
    tavern_global_cfg: Union[dict, str, None] = None,
133
    tavern_mqtt_backend: Union[str, None] = None,
134
    tavern_http_backend: Union[str, None] = None,
135
    tavern_grpc_backend: Union[str, None] = None,
136
    tavern_strict: Union[bool, None] = None,
137
    pytest_args: Union[list, None] = None,
138
) -> Union[ExitCode, int]
139
```
140

141
[Core Test Execution](./core-execution.md)
142

143
### Response Validation Helpers
144

145
Comprehensive validation functions for API responses including JWT validation, regex matching, schema validation, and content assertions using JMESPath.
146

147
```python { .api }
148
def validate_jwt(response: requests.Response, jwt_key: str, **kwargs) -> Mapping[str, Box]
149
def validate_regex(
150
    response: requests.Response,
151
    expression: str,
152
    *,
153
    header: Optional[str] = None,
154
    in_jmespath: Optional[str] = None,
155
) -> dict[str, Box]
156
def validate_content(response: requests.Response, comparisons: Iterable[dict]) -> None
157
def check_jmespath_match(parsed_response, query: str, expected: Optional[str] = None)
158
```
159

160
[Response Validation](./response-validation.md)
161

162
### Pytest Integration
163

164
Deep integration with pytest providing custom hooks, CLI options, automatic test file discovery, and seamless integration with pytest plugins and reporting.
165

166
```python { .api }
167
def pytest_addhooks(pluginmanager)
168
def pytest_addoption(parser)
169
def pytest_collect_file(parent, path)
170
def add_parser_options(parser_addoption, with_defaults=True)
171
```
172

173
[Pytest Integration](./pytest-integration.md)
174

175
### Plugin Architecture
176

177
Extensible plugin system supporting HTTP/REST, MQTT, and gRPC protocols with standardized interfaces for requests, responses, and session management.
178

179
```python { .api }
180
class BaseRequest:
181
    def __init__(self, session: Any, rspec: dict, test_block_config: TestConfig) -> None
182
    @property
183
    def request_vars(self) -> box.Box
184
    def run(self)
185

186
class BaseResponse:
187
    name: str
188
    expected: Any
189
    test_block_config: TestConfig
190
    response: Optional[Any] = None
191
    def verify(self, response)
192
```
193

194
[Plugin System](./plugin-system.md)
195

196
### Exception Handling
197

198
Comprehensive exception hierarchy for detailed error reporting and debugging, covering schema validation, key mismatches, protocol errors, and configuration issues.
199

200
```python { .api }
201
class TavernException(Exception):
202
    stage: Optional[dict]
203
    test_block_config: Optional["TestConfig"]
204
    is_final: bool = False
205

206
class BadSchemaError(TavernException)
207
class TestFailError(TavernException)
208
class KeyMismatchError(TavernException)
209
```
210

211
[Exception Handling](./exceptions.md)
212

213
## Command Line Interface
214

215
```python { .api }
216
class TavernArgParser(ArgumentParser):
217
    def __init__(self) -> None
218

219
def main() -> None
220
```
221

222
**CLI Options:**
223
- `--tavern-global-cfg`: Path to global configuration file
224
- `--tavern-http-backend`: HTTP backend selection (default: "requests")
225
- `--tavern-mqtt-backend`: MQTT backend selection (default: "paho-mqtt")
226
- `--tavern-grpc-backend`: gRPC backend selection (default: "grpc")
227
- `--tavern-strict`: Response matching strictness level
228
- `--tavern-file-path-regex`: Test file pattern (default: `*.tavern.ya?ml`)
229
- `--log-to-file`: Log output to a file (defaults to `tavern.log` if no filename provided)
230
- `--stdout`: Log output to stdout
231
- `--debug`: Enable debug logging (only relevant with --stdout or --log-to-file)
232

233
## Types
234

235
```python { .api }
236
from typing import Union, Optional, Any, Mapping, Iterable
237
from _pytest.config import ExitCode
238
from box.box import Box
239
import requests
240

241
TestConfig = "tavern._core.pytest.config.TestConfig"
242
```