0
# Verifier System
1
2
The Molecule verifier system provides an extensible architecture for running various types of tests against provisioned infrastructure. Verifiers execute test suites to validate that Ansible roles behave correctly across different scenarios and environments.
3
4
## Capabilities
5
6
### Base Verifier Class
7
8
Abstract base class that all verifiers must inherit from, defining the interface for test execution.
9
10
```python { .api }
11
class Verifier:
12
"""Base class for all verifiers."""
13
14
@property
15
def name(self):
16
"""
17
Name of the verifier.
18
19
Returns:
20
str: Verifier name identifier
21
"""
22
23
@property
24
def default_options(self):
25
"""
26
Get default CLI arguments.
27
28
Returns:
29
dict: Default command-line options for the verifier
30
"""
31
32
@property
33
def default_env(self):
34
"""
35
Get default env variables.
36
37
Returns:
38
dict[str, str]: Default environment variables
39
"""
40
41
def execute(self, action_args):
42
"""
43
Execute cmd.
44
45
Args:
46
action_args (list[str]): Command arguments to execute
47
48
Returns:
49
CompletedProcess: Result of command execution
50
"""
51
52
def schema(self):
53
"""
54
Return validation schema.
55
56
Returns:
57
dict: Schema for validating verifier configuration
58
"""
59
```
60
61
### Verifier Properties
62
63
Concrete properties available to all verifiers for configuration and state management.
64
65
```python { .api }
66
class Verifier:
67
@property
68
def enabled(self):
69
"""
70
Is the verifier enabled.
71
72
Returns:
73
bool: True if verifier is enabled for execution
74
"""
75
76
@property
77
def directory(self):
78
"""
79
Verifier directory.
80
81
Returns:
82
str: Path to verifier test files and configuration
83
"""
84
85
@property
86
def options(self):
87
"""
88
Computed options for this verifier.
89
90
Returns:
91
dict: Merged default and user-specified options
92
"""
93
94
@property
95
def env(self):
96
"""
97
Computed environment variables for this verifier.
98
99
Returns:
100
dict[str, str]: Merged default and user-specified environment
101
"""
102
```
103
104
### Built-in Verifiers
105
106
Concrete verifier implementations provided with Molecule.
107
108
```python { .api }
109
class Ansible(Verifier):
110
"""
111
Default test verifier using Ansible playbooks.
112
113
Executes Ansible playbooks as test suites, allowing for complex
114
testing scenarios using native Ansible modules and tasks.
115
"""
116
117
@property
118
def name(self):
119
"""Returns 'ansible'."""
120
121
@property
122
def default_options(self):
123
"""Default options for ansible-playbook execution."""
124
125
@property
126
def default_env(self):
127
"""Default environment variables for Ansible."""
128
129
class Testinfra(Verifier):
130
"""
131
Testinfra-based verifier for infrastructure testing.
132
133
Uses pytest and testinfra to write Python-based infrastructure
134
tests that can validate system state, services, and configuration.
135
"""
136
137
@property
138
def name(self):
139
"""Returns 'testinfra'."""
140
141
@property
142
def default_options(self):
143
"""Default options for pytest/testinfra execution."""
144
145
@property
146
def default_env(self):
147
"""Default environment variables for testinfra."""
148
```
149
150
## Verifier Configuration Types
151
152
Type definitions for verifier configuration and options.
153
154
```python { .api }
155
class VerifierData:
156
"""Molecule verifier configuration."""
157
name: str
158
directory: str
159
enabled: bool
160
options: dict[str, str | bool]
161
env: dict[str, str]
162
additional_files_or_dirs: list[str]
163
```
164
165
## Usage Examples
166
167
### Creating a Custom Verifier
168
169
```python
170
from molecule.verifier.base import Verifier
171
import subprocess
172
173
class CustomVerifier(Verifier):
174
def __init__(self, config=None):
175
super().__init__(config)
176
self._name = "custom"
177
178
@property
179
def name(self):
180
return self._name
181
182
@property
183
def default_options(self):
184
return {
185
"verbose": True,
186
"timeout": 300
187
}
188
189
@property
190
def default_env(self):
191
return {
192
"CUSTOM_TEST_ENV": "test"
193
}
194
195
def execute(self, action_args):
196
"""Execute custom test suite."""
197
cmd = ["custom-test-runner"] + action_args
198
return subprocess.run(
199
cmd,
200
env=self.env,
201
capture_output=True,
202
text=True
203
)
204
205
def schema(self):
206
return {
207
"type": "object",
208
"properties": {
209
"name": {"type": "string"},
210
"options": {"type": "object"},
211
"env": {"type": "object"}
212
}
213
}
214
```
215
216
### Using Verifiers Programmatically
217
218
```python
219
from molecule.api import verifiers
220
from molecule.config import Config
221
222
# Get available verifiers
223
available_verifiers = verifiers()
224
ansible_verifier = available_verifiers.get("ansible")
225
226
if ansible_verifier:
227
print(f"Verifier: {ansible_verifier.name}")
228
print(f"Enabled: {ansible_verifier.enabled}")
229
print(f"Directory: {ansible_verifier.directory}")
230
print(f"Options: {ansible_verifier.options}")
231
232
# Execute verification tests
233
if ansible_verifier.enabled:
234
result = ansible_verifier.execute([])
235
print(f"Test result: {result.returncode}")
236
```
237
238
### Ansible Verifier Usage
239
240
```python
241
# Using the built-in Ansible verifier
242
from molecule.verifier.ansible import Ansible
243
244
verifier = Ansible()
245
print(f"Default options: {verifier.default_options}")
246
247
# Execute with custom arguments
248
result = verifier.execute([
249
"--inventory", "inventory/",
250
"--extra-vars", "test_var=value",
251
"verify.yml"
252
])
253
```
254
255
### Testinfra Verifier Usage
256
257
```python
258
# Using the built-in Testinfra verifier
259
from molecule.verifier.testinfra import Testinfra
260
261
verifier = Testinfra()
262
print(f"Test directory: {verifier.directory}")
263
264
# Execute testinfra tests
265
result = verifier.execute([
266
"--verbose",
267
"--connection=ansible",
268
"--ansible-inventory=inventory/",
269
"tests/"
270
])
271
```
272
273
### Verifier Configuration
274
275
```yaml
276
# molecule.yml
277
verifier:
278
name: ansible
279
enabled: true
280
directory: verify
281
options:
282
verbose: true
283
diff: true
284
env:
285
ANSIBLE_ROLES_PATH: ../roles
286
additional_files_or_dirs:
287
- ../shared_tests/
288
```
289
290
```yaml
291
# Using testinfra verifier
292
verifier:
293
name: testinfra
294
enabled: true
295
directory: tests
296
options:
297
verbose: true
298
junit-xml: results.xml
299
env:
300
TESTINFRA_BACKEND: ansible
301
additional_files_or_dirs:
302
- ../common_tests/
303
```
304
305
## Integration Notes
306
307
- Verifiers are discovered through setuptools entry points under `molecule.verifier`
308
- Built-in verifiers include Ansible (default) and Testinfra
309
- Custom verifiers should inherit from the `Verifier` base class
310
- Verifier loading failures are logged but don't prevent tool usage
311
- Verifiers can specify additional files/directories to include in test runs
312
- Test execution occurs in the verify phase of the Molecule test sequence
313
- Verifiers can be disabled by setting `enabled: false` in configuration