0
# Molecule
1

2
Molecule aids in the development and testing of Ansible roles by providing a comprehensive testing framework that supports multiple scenarios, platforms, and testing tools. It enables developers to create, validate, and maintain high-quality infrastructure automation code through automated testing workflows across different environments.
3

4
## Package Information
5

6
- **Package Name**: molecule
7
- **Language**: Python
8
- **Installation**: `pip install molecule`
9
- **Python Version**: >=3.10
10

11
## Core Imports
12

13
```python
14
import molecule
15
```
16

17
For API access:
18

19
```python
20
from molecule.api import drivers, verifiers, Driver, Verifier
21
```
22

23
For configuration:
24

25
```python
26
from molecule.config import Config
27
```
28

29
For exceptions:
30

31
```python
32
from molecule.exceptions import MoleculeError, ScenarioFailureError
33
```
34

35
For concrete verifiers:
36

37
```python
38
from molecule.verifier.ansible import Ansible
39
from molecule.verifier.testinfra import Testinfra
40
```
41

42
## Basic Usage
43

44
```python
45
from molecule.api import drivers, verifiers
46

47
# Get available drivers
48
available_drivers = drivers()
49
print("Available drivers:", list(available_drivers.keys()))
50

51
# Get available verifiers  
52
available_verifiers = verifiers()
53
print("Available verifiers:", list(available_verifiers.keys()))
54

55
# Access package version
56
import molecule
57
print("Molecule version:", molecule.__version__)
58
```
59

60
Command-line usage:
61

62
```bash
63
# Create a new role with molecule scenario
64
molecule init role my-role --driver-name default
65

66
# Run the full test sequence
67
molecule test
68

69
# Create test instances
70
molecule create
71

72
# Converge (apply) the role
73
molecule converge
74

75
# Run verification tests
76
molecule verify
77

78
# Destroy test instances
79
molecule destroy
80
```
81

82
## Architecture
83

84
Molecule follows a plugin-based architecture with several key components:
85

86
- **Drivers**: Handle infrastructure provisioning (create/destroy instances)
87
- **Verifiers**: Execute test suites to validate role behavior
88
- **Provisioners**: Apply Ansible roles to test instances (primarily Ansible)
89
- **Config**: Manages scenario configuration and state
90
- **Commands**: CLI interface for test lifecycle operations
91

92
The testing workflow follows a defined sequence: dependency → create → prepare → converge → idempotence → side_effect → verify → cleanup → destroy.
93

94
## Capabilities
95

96
### Core API Functions
97

98
Access to the plugin system and runtime configuration for extending Molecule with custom drivers and verifiers.
99

100
```python { .api }
101
def drivers(config=None):
102
    """
103
    Return list of active drivers.
104
    
105
    Args:
106
        config: plugin config
107
        
108
    Returns:
109
        dict[str, Driver]: A dictionary of active drivers by name
110
    """
111

112
def verifiers(config=None):
113
    """
114
    Return list of active verifiers.
115
    
116
    Args:
117
        config: plugin config
118
        
119
    Returns:
120
        dict[str, Verifier]: A dictionary of active verifiers by name
121
    """
122
```
123

124
[Core API](./core-api.md)
125

126
### Command-Line Interface
127

128
Complete CLI interface for managing test scenarios, including lifecycle commands for creating, testing, and destroying infrastructure.
129

130
```python { .api }
131
def main(ctx, debug, verbose, base_config, env_file):
132
    """
133
    Molecule aids in the development and testing of Ansible roles.
134
    
135
    Args:
136
        ctx: Click context object
137
        debug: Debug option value
138
        verbose: Verbose option value  
139
        base_config: Base config option value
140
        env_file: Environment variable file option value
141
    """
142
```
143

144
[CLI Commands](./cli-commands.md)
145

146
### Driver System
147

148
Extensible driver system for provisioning test infrastructure across different platforms and environments.
149

150
```python { .api }
151
class Driver:
152
    """Base class for all drivers."""
153
    
154
    @property
155
    def name(self):
156
        """Name of the driver."""
157
    
158
    @property  
159
    def login_cmd_template(self):
160
        """Login command template."""
161
        
162
    def sanity_checks(self):
163
        """Confirm that driver is usable."""
164
        
165
    def status(self):
166
        """Collect instances state."""
167
```
168

169
[Driver System](./driver-system.md)
170

171
### Verifier System
172

173
Extensible verifier system for running various types of tests against provisioned infrastructure.
174

175
```python { .api }
176
class Verifier:
177
    """Base class for all verifiers."""
178
    
179
    @property
180
    def name(self):
181
        """Name of the verifier."""
182
        
183
    @property
184
    def enabled(self):
185
        """Is the verifier enabled."""
186
        
187
    def execute(self, action_args):
188
        """Execute cmd."""
189
        
190
    def schema(self):
191
        """Return validation schema."""
192
```
193

194
[Verifier System](./verifier-system.md)
195

196
### Configuration Management
197

198
Type-safe configuration system for managing scenarios, platforms, and testing parameters.
199

200
```python { .api }
201
class Config:
202
    """Main configuration management class."""
203
    
204
class ConfigData:
205
    """Class representing molecule config."""
206
    
207
class ScenarioData:
208
    """Molecule scenario configuration."""
209
    
210
class PlatformData:
211
    """Platform data for a Molecule run."""
212
```
213

214
[Configuration](./configuration.md)
215

216
### Exception Handling
217

218
Comprehensive exception system for handling errors during testing workflows.
219

220
```python { .api }
221
class MoleculeError(Exception):
222
    """
223
    Generic Molecule error.
224
    
225
    Args:
226
        message: The message to display about the problem
227
        code: Exit code to use when exiting
228
        warns: Warnings about the problem to issue
229
    """
230
    
231
class ScenarioFailureError(MoleculeError):
232
    """Details about a scenario that failed."""
233
```
234

235
[Exception Handling](./exceptions.md)
236

237
## Types
238

239
```python { .api }
240
# Core type definitions
241
Options = MutableMapping[str, str | bool]
242

243
class MoleculeArgs:
244
    """Base arguments passed to all Molecule commands."""
245
    base_config: list[str]
246
    debug: bool
247
    env_file: str  
248
    verbose: int
249

250
class CommandArgs:
251
    """Commandline arguments passed to molecule."""
252
    destroy: Literal["always", "never"]
253
    driver_name: str
254
    force: bool
255
    format: Literal["simple", "plain", "yaml"]
256
    scenario_name: str
257
    platform_name: str
258
    parallel: bool
259

260
class ScenarioResult:
261
    """Dictionary containing the result of a Scenario action."""
262
    subcommand: str | None
263
    state: Literal["PASSED", "FAILED", "SKIPPED"]
264
```