0
# Test Definition and Structure
1
2
Core functionality for defining and organizing test scenarios using class-based or function-based approaches with BDD-style step organization.
3
4
## Capabilities
5
6
### Class-based Scenarios
7
8
The foundational Scenario class that uses metaclass magic to create test scenarios with automatic parameterization support.
9
10
```python { .api }
11
class Scenario:
12
"""
13
Base class for test scenarios with parameterization support.
14
15
Attributes:
16
subject (str): Description of what is being tested
17
"""
18
subject: str
19
20
def __repr__(self) -> str: ...
21
```
22
23
#### Usage Example
24
25
```python
26
import vedro
27
28
class Scenario(vedro.Scenario):
29
subject = "user registration process"
30
31
def given_valid_user_data(self):
32
self.user_data = {
33
"username": "newuser",
34
"email": "user@example.com",
35
"password": "securepass123"
36
}
37
38
def when_user_registers(self):
39
self.response = register_user(self.user_data)
40
41
def then_registration_succeeds(self):
42
assert self.response.status_code == 201
43
assert "user_id" in self.response.json()
44
```
45
46
### Function-based Scenarios
47
48
Decorator-based approach for creating scenarios using functions with BDD-style step decorators.
49
50
```python { .api }
51
def scenario(description: str) -> Callable:
52
"""
53
Decorator to mark a function as a test scenario.
54
55
Args:
56
description: Human-readable description of the scenario
57
58
Returns:
59
Decorated function as a scenario
60
"""
61
```
62
63
### BDD Step Decorators
64
65
Organize test logic into Given-When-Then structure for clarity and readability.
66
67
```python { .api }
68
def given(description: str) -> Callable:
69
"""
70
Decorator for setup/precondition steps.
71
72
Args:
73
description: Description of the precondition being set up
74
75
Returns:
76
Decorated function as a given step
77
"""
78
79
def when(description: str) -> Callable:
80
"""
81
Decorator for action/event steps.
82
83
Args:
84
description: Description of the action being performed
85
86
Returns:
87
Decorated function as a when step
88
"""
89
90
def then(description: str) -> Callable:
91
"""
92
Decorator for verification/assertion steps.
93
94
Args:
95
description: Description of the expected outcome
96
97
Returns:
98
Decorated function as a then step
99
"""
100
```
101
102
#### Usage Example
103
104
```python
105
from vedro import scenario, given, when, then, ensure
106
107
@scenario("User can reset password")
108
def test_password_reset():
109
110
@given("user with forgotten password")
111
def setup():
112
user = create_user("test@example.com")
113
return {"user": user, "original_password": user.password}
114
115
@when("user requests password reset")
116
def action(ctx):
117
reset_token = request_password_reset(ctx["user"].email)
118
new_password = "newpassword123"
119
response = reset_password(reset_token, new_password)
120
return {"response": response, "new_password": new_password}
121
122
@then("password is successfully reset")
123
def verification(ctx):
124
ensure(ctx["response"].status_code).equals(200)
125
126
# Verify old password no longer works
127
with catched(AuthenticationError):
128
authenticate(ctx["user"].email, ctx["original_password"])
129
130
# Verify new password works
131
auth_result = authenticate(ctx["user"].email, ctx["new_password"])
132
ensure(auth_result.success).is_true()
133
```
134
135
### Interface Class
136
137
Base interface class for plugin interfaces and extensibility.
138
139
```python { .api }
140
class Interface:
141
"""
142
Base interface class for plugin interfaces.
143
"""
144
pass
145
```
146
147
## Types
148
149
### MetaData
150
151
Internal metadata handling for scenarios (used by the metaclass system).
152
153
```python { .api }
154
class MetaData:
155
"""Internal metadata container for scenario information."""
156
pass
157
```
158
159
## Advanced Patterns
160
161
### Method Organization
162
163
For class-based scenarios, organize methods with clear prefixes:
164
165
- `given_*`: Setup and precondition methods
166
- `when_*`: Action and event trigger methods
167
- `then_*`: Verification and assertion methods
168
169
### Nested Step Functions
170
171
Function-based scenarios support nested step definitions for complex test logic:
172
173
```python
174
@scenario("Complex user workflow")
175
def test_complex_workflow():
176
177
@given("authenticated user with permissions")
178
def setup():
179
user = authenticate_user("admin@example.com")
180
grant_permissions(user, ["read", "write", "delete"])
181
return user
182
183
@when("user performs multiple actions")
184
def actions(user):
185
# Multiple sub-actions
186
created_item = create_item(user, {"name": "test item"})
187
updated_item = update_item(user, created_item.id, {"status": "active"})
188
return {"created": created_item, "updated": updated_item}
189
190
@then("all actions succeed with proper state")
191
def verification(ctx):
192
ensure(ctx["created"].name).equals("test item")
193
ensure(ctx["updated"].status).equals("active")
194
195
# Verify database state
196
db_item = get_item(ctx["created"].id)
197
ensure(db_item.status).equals("active")
198
```
199
200
### Subject Patterns
201
202
Use descriptive subjects that clearly indicate what functionality is being tested:
203
204
```python
205
class Scenario(vedro.Scenario):
206
subject = "payment processing with multiple payment methods"
207
208
class Scenario(vedro.Scenario):
209
subject = "user authentication with two-factor authentication"
210
211
class Scenario(vedro.Scenario):
212
subject = "file upload validation and processing"
213
```