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)