0
# Vedro
1
2
A pragmatic Python testing framework that combines clear, scenario-style syntax with a lightweight, pluggable core architecture. Vedro features BDD-style test structure, powerful parameterization, comprehensive event system, and extensive plugin ecosystem for customizing testing workflows.
3
4
## Package Information
5
6
- **Package Name**: vedro
7
- **Language**: Python
8
- **Installation**: `pip install vedro`
9
- **Console Entry Point**: `vedro` command
10
11
## Core Imports
12
13
```python
14
import vedro
15
```
16
17
Common imports for test writing:
18
19
```python
20
from vedro import Scenario, scenario, given, when, then, ensure
21
from vedro import params, skip, skip_if, only
22
from vedro import catched, context, defer, defer_global
23
from vedro import create_tmp_dir, create_tmp_file
24
from vedro import attach_artifact, attach_scenario_artifact
25
```
26
27
Configuration and core system imports:
28
29
```python
30
from vedro import Config, computed
31
from vedro.core import Plugin, PluginConfig, Dispatcher
32
from vedro.events import StartupEvent, ScenarioPassedEvent, StepFailedEvent
33
```
34
35
## Basic Usage
36
37
### Class-based Scenarios
38
39
```python
40
import vedro
41
42
class Scenario(vedro.Scenario):
43
subject = "user authentication"
44
45
def given_valid_credentials(self):
46
self.username = "test_user"
47
self.password = "secure_pass"
48
49
def when_user_logs_in(self):
50
self.response = login(self.username, self.password)
51
52
def then_login_is_successful(self):
53
assert self.response.status_code == 200
54
assert "token" in self.response.json()
55
```
56
57
### Function-based Scenarios
58
59
```python
60
from vedro import scenario, given, when, then, ensure
61
62
@scenario("User can view dashboard")
63
def test_dashboard_access():
64
65
@given("authenticated user")
66
def setup():
67
return authenticate_user("test_user")
68
69
@when("user requests dashboard")
70
def action(user):
71
return request_dashboard(user.token)
72
73
@then("dashboard is displayed")
74
def verification(response):
75
ensure(response.status_code).equals(200)
76
ensure("dashboard" in response.text)
77
```
78
79
### Parameterized Scenarios
80
81
```python
82
from vedro import Scenario, params
83
84
class Scenario(vedro.Scenario):
85
subject = "math operations"
86
87
@params(2, 3, 5)
88
@params(5, 7, 12)
89
@params(10, 15, 25)
90
def __init__(self, a, b, expected):
91
self.a = a
92
self.b = b
93
self.expected = expected
94
95
def when_numbers_are_added(self):
96
self.result = self.a + self.b
97
98
def then_result_is_correct(self):
99
assert self.result == self.expected
100
```
101
102
## Architecture
103
104
Vedro follows an event-driven plugin architecture with clear separation of concerns:
105
106
- **Core Components**: Scenario discovery, loading, execution, and result collection
107
- **Plugin System**: Extensive plugin ecosystem with lifecycle hooks via event system
108
- **Event Dispatcher**: Central event system enabling plugin communication and customization
109
- **Configuration**: Hierarchical configuration system with factory/singleton patterns for dependency injection
110
- **CLI System**: Command-based CLI with backward compatibility and extensible argument parsing
111
112
This architecture enables customization of every aspect of the testing process while maintaining simplicity for basic usage patterns.
113
114
## Capabilities
115
116
### Test Definition and Structure
117
118
Core functionality for defining and organizing test scenarios using class-based or function-based approaches with BDD-style step organization.
119
120
```python { .api }
121
class Scenario:
122
subject: str
123
124
def scenario(description: str) -> Callable
125
def given(description: str) -> Callable
126
def when(description: str) -> Callable
127
def then(description: str) -> Callable
128
```
129
130
[Test Definition](./test-definition.md)
131
132
### Test Parameterization
133
134
Powerful parameterization system supporting multiple parameter sets with optional decorators for enhanced functionality.
135
136
```python { .api }
137
class params:
138
def __init__(self, *args, **kwargs): ...
139
def __call__(self, fn: F) -> F: ...
140
def __class_getitem__(cls, item) -> Callable[..., Parameterized]: ...
141
```
142
143
[Parameterization](./parameterization.md)
144
145
### Test Execution Control
146
147
Skip conditions, selective execution, and test flow control mechanisms for managing which tests run under different conditions.
148
149
```python { .api }
150
def skip(reason: str = "") -> Callable
151
def skip_if(cond: Callable[[], bool], reason: str = "") -> Callable
152
def only() -> Callable
153
```
154
155
[Execution Control](./execution-control.md)
156
157
### Retry Logic and Exception Handling
158
159
Retry mechanism for flaky operations and sophisticated exception catching with inspection capabilities.
160
161
```python { .api }
162
def ensure(*, attempts: Optional[int] = None,
163
delay: Optional[Union[float, int, Callable[[int], Union[float, int]]]] = None,
164
swallow: Optional[Union[Type[BaseException], Tuple[Type[BaseException], ...]]] = None) -> Ensure
165
166
class catched:
167
def __init__(self, expected_exc = BaseException): ...
168
@property
169
def type(self) -> Type[BaseException] | None: ...
170
@property
171
def value(self) -> BaseException | None: ...
172
@property
173
def traceback(self) -> TracebackType | None: ...
174
```
175
176
[Retry Logic and Exception Handling](./assertions.md)
177
178
### Artifacts and File Management
179
180
Comprehensive artifact attachment system and temporary file management with automatic cleanup.
181
182
```python { .api }
183
class Artifact: ...
184
class FileArtifact(Artifact): ...
185
class MemoryArtifact(Artifact): ...
186
187
def attach_artifact(artifact: Artifact) -> None
188
def attach_scenario_artifact(artifact: Artifact) -> None
189
def attach_step_artifact(artifact: Artifact) -> None
190
def attach_global_artifact(artifact: Artifact) -> None
191
192
def create_tmp_dir(*, suffix: Optional[str] = None, prefix: Optional[str] = None) -> Path
193
def create_tmp_file(*, suffix: Optional[str] = None, prefix: Optional[str] = None) -> Path
194
```
195
196
[Artifacts and Files](./artifacts-files.md)
197
198
### Context Management and Cleanup
199
200
Context providers and deferred cleanup actions for managing test state and resources.
201
202
```python { .api }
203
def context(fn: Callable) -> Callable
204
def defer(fn: Callable, *args, **kwargs) -> None
205
def defer_global(fn: Callable, *args, **kwargs) -> None
206
```
207
208
[Context and Cleanup](./context-cleanup.md)
209
210
### Event System
211
212
Comprehensive event system for plugin development and test lifecycle monitoring.
213
214
```python { .api }
215
class Event: ...
216
217
# Lifecycle Events
218
class StartupEvent: ...
219
class CleanupEvent: ...
220
221
# Scenario Events
222
class ScenarioRunEvent: ...
223
class ScenarioPassedEvent: ...
224
class ScenarioFailedEvent: ...
225
class ScenarioSkippedEvent: ...
226
227
# Step Events
228
class StepRunEvent: ...
229
class StepPassedEvent: ...
230
class StepFailedEvent: ...
231
```
232
233
[Events](./events.md)
234
235
### Configuration and Plugins
236
237
Configuration system with plugin management, dependency injection, and extensible architecture.
238
239
```python { .api }
240
class Config:
241
class Registry: ...
242
class Plugins: ...
243
244
def computed(fn: Callable) -> Callable
245
246
class Plugin: ...
247
class PluginConfig: ...
248
class Dispatcher: ...
249
```
250
251
[Configuration](./configuration.md)
252
253
### CLI and Execution
254
255
Command-line interface for running tests and managing plugins with extensive configuration options.
256
257
```python { .api }
258
def run(*, plugins=None) -> None
259
260
class Interface:
261
"""Base interface class for test scenarios."""
262
pass
263
264
# CLI Commands
265
# vedro run [options]
266
# vedro version
267
# vedro plugin [list|install|enable|disable]
268
```
269
270
[CLI](./cli.md)