0
# Core Test Execution
1

2
Primary interface for running Tavern tests programmatically, providing comprehensive control over test execution, configuration, and backend selection.
3

4
## Capabilities
5

6
### Programmatic Test Runner
7

8
The main entry point for executing Tavern tests from Python code, offering full control over test configuration and execution parameters.
9

10
```python { .api }
11
def run(
12
    in_file: str,
13
    tavern_global_cfg: Union[dict, str, None] = None,
14
    tavern_mqtt_backend: Union[str, None] = None,
15
    tavern_http_backend: Union[str, None] = None,
16
    tavern_grpc_backend: Union[str, None] = None,
17
    tavern_strict: Union[bool, None] = None,
18
    pytest_args: Union[list, None] = None,
19
) -> Union[ExitCode, int]:
20
    """
21
    Run all tests contained in a file using pytest.main()
22

23
    Parameters:
24
    - in_file: Path to the test file to run
25
    - tavern_global_cfg: Global configuration as dict or path to config file
26
    - tavern_mqtt_backend: MQTT plugin backend name (default: "paho-mqtt")
27
    - tavern_http_backend: HTTP plugin backend name (default: "requests")
28
    - tavern_grpc_backend: gRPC plugin backend name (default: "grpc")
29
    - tavern_strict: Strictness level for response validation
30
    - pytest_args: Additional arguments to pass to pytest
31

32
    Returns:
33
    ExitCode or int: 0 if all tests passed, non-zero otherwise
34
    """
35
```
36

37
**Usage Examples:**
38

39
```python
40
from tavern.core import run
41

42
# Basic usage
43
exit_code = run("tests/api_tests.tavern.yaml")
44

45
# With global configuration file
46
exit_code = run(
47
    "tests/api_tests.tavern.yaml",
48
    tavern_global_cfg="config/global.yaml"
49
)
50

51
# With global configuration as dictionary
52
global_config = {
53
    "variables": {
54
        "base_url": "https://api.staging.example.com",
55
        "api_key": "test-key-123"
56
    }
57
}
58
exit_code = run(
59
    "tests/api_tests.tavern.yaml",
60
    tavern_global_cfg=global_config
61
)
62

63
# With custom backends and strict validation
64
exit_code = run(
65
    "tests/api_tests.tavern.yaml",
66
    tavern_http_backend="requests",
67
    tavern_strict=True,
68
    pytest_args=["-v", "--tb=short"]
69
)
70

71
# Check test results
72
if exit_code == 0:
73
    print("All tests passed successfully!")
74
else:
75
    print(f"Tests failed with exit code: {exit_code}")
76
```
77

78
### Global Configuration Processing
79

80
Internal function for processing global configuration from various sources.
81

82
```python { .api }
83
def _get_or_wrap_global_cfg(
84
    stack: ExitStack, 
85
    tavern_global_cfg: Union[dict, str]
86
) -> str:
87
    """
88
    Parse global configuration from file path or dictionary.
89

90
    Parameters:
91
    - stack: Context stack for temporary file management
92
    - tavern_global_cfg: Configuration as file path or dictionary
93

94
    Returns:
95
    str: Path to configuration file
96

97
    Raises:
98
    InvalidSettingsError: If configuration format is invalid or file doesn't exist
99
    """
100
```
101

102
## Configuration Examples
103

104
### Global Configuration File Format
105

106
```yaml
107
# global_config.yaml
108
variables:
109
  base_url: "https://api.example.com"
110
  api_version: "v1"
111
  auth_token: "{env:API_TOKEN}"
112

113
stages:
114
  - name: "setup"
115
    request:
116
      url: "{base_url}/auth"
117
      method: POST
118
      json:
119
        token: "{auth_token}"
120
    response:
121
      status_code: 200
122
      save:
123
        json:
124
          session_token: token
125

126
# Available in all tests as {session_token}
127
```
128

129
### Backend Selection
130

131
```python
132
# Use different HTTP backend
133
exit_code = run(
134
    "tests/api_tests.tavern.yaml",
135
    tavern_http_backend="custom_http_plugin"
136
)
137

138
# Use custom MQTT backend
139
exit_code = run(
140
    "tests/mqtt_tests.tavern.yaml",
141
    tavern_mqtt_backend="custom_mqtt_plugin"
142
)
143

144
# Use custom gRPC backend  
145
exit_code = run(
146
    "tests/grpc_tests.tavern.yaml",
147
    tavern_grpc_backend="custom_grpc_plugin"
148
)
149
```
150

151
### Strictness Control
152

153
```python
154
# Strict validation (exact key matching)
155
exit_code = run(
156
    "tests/api_tests.tavern.yaml",
157
    tavern_strict=True
158
)
159

160
# Relaxed validation (allow extra keys)
161
exit_code = run(
162
    "tests/api_tests.tavern.yaml",
163
    tavern_strict=False
164
)
165
```
166

167
### Integration with Pytest Arguments
168

169
```python
170
# Pass pytest-specific arguments
171
exit_code = run(
172
    "tests/api_tests.tavern.yaml",
173
    pytest_args=[
174
        "-v",              # Verbose output
175
        "--tb=short",      # Short traceback format
176
        "-x",              # Stop on first failure
177
        "--maxfail=3",     # Stop after 3 failures
178
        "-k", "user_api",  # Run only tests matching pattern
179
        "--durations=10"   # Show 10 slowest tests
180
    ]
181
)
182
```
183

184
## Types
185

186
```python { .api }
187
from typing import Union, Optional
188
from contextlib import ExitStack
189
from _pytest.config import ExitCode
190

191
InvalidSettingsError = "tavern._core.exceptions.InvalidSettingsError"
192
```