0
# Configuration
1

2
Molecule's configuration system provides type-safe management of scenarios, platforms, and testing parameters through a comprehensive set of configuration classes and data structures.
3

4
## Capabilities
5

6
### Core Configuration Class
7

8
Main configuration management class that orchestrates all aspects of a Molecule scenario.
9

10
```python { .api }
11
class Config:
12
    """
13
    Main configuration management class.
14
    
15
    Instantiates and manages Driver, Platforms, Provisioner, Verifier,
16
    Scenario, and State references for a complete test environment.
17
    """
18
    
19
    def __init__(self, args=None, command_args=None):
20
        """
21
        Initialize configuration.
22
        
23
        Args:
24
            args (MoleculeArgs): Base Molecule arguments
25
            command_args (CommandArgs): Command-specific arguments
26
        """
27
    
28
    @property
29
    def driver(self):
30
        """Driver instance for infrastructure management."""
31
    
32
    @property
33
    def platforms(self):
34
        """Platforms configuration for test instances."""
35
    
36
    @property
37
    def provisioner(self): 
38
        """Provisioner for applying Ansible roles."""
39
    
40
    @property
41
    def verifier(self):
42
        """Verifier for running test suites."""
43
    
44
    @property
45
    def scenario(self):
46
        """Scenario configuration and state."""
47
    
48
    @property
49
    def state(self):
50
        """State management for tracking test progress."""
51
```
52

53
### Configuration Data Types
54

55
Type-safe data structures for all aspects of Molecule configuration.
56

57
```python { .api }
58
class ConfigData:
59
    """Class representing molecule config."""
60
    dependency: DependencyData
61
    driver: DriverData
62
    executor: ExecutorData
63
    platforms: list[PlatformData]
64
    prerun: bool
65
    role_name_check: int
66
    provisioner: ProvisionerData
67
    scenario: ScenarioData
68
    verifier: VerifierData
69

70
class ScenarioData:
71
    """Molecule scenario configuration."""
72
    name: str
73
    check_sequence: list[str]
74
    cleanup_sequence: list[str]
75
    converge_sequence: list[str]
76
    create_sequence: list[str]
77
    destroy_sequence: list[str]
78
    test_sequence: list[str]
79

80
class PlatformData:
81
    """Platform data for a Molecule run."""
82
    name: str
83
    groups: list[str]
84
    children: list[str]
85

86
class DependencyData:
87
    """Molecule dependency configuration."""
88
    name: str
89
    command: str | None
90
    enabled: bool
91
    options: dict[str, str | bool]
92
    env: dict[str, str]
93

94
class ProvisionerData:
95
    """Molecule provisioner configuration."""
96
    name: str
97
    config_options: dict[str, Any]
98
    ansible_args: list[str]
99
    connection_options: dict[str, Any]
100
    options: dict[str, str | bool]
101
    env: dict[str, str]
102
    inventory: InventoryData
103
    children: dict[str, Any]
104
    playbooks: PlaybookData
105
    log: bool
106

107
class PlaybookData:
108
    """Playbooks for a scenario."""
109
    cleanup: str
110
    create: str
111
    converge: str
112
    destroy: str
113
    prepare: str
114
    side_effect: str
115
    verify: str
116

117
class InventoryData:
118
    """Inventory data for a molecule run."""
119
    hosts: dict[str, str] 
120
    host_vars: dict[str, str]
121
    group_vars: dict[str, str]
122
    links: dict[str, str]
123

124
class ExecutorData:
125
    """Molecule playbook executor configuration."""
126
    backend: str
127
```
128

129
### Command Arguments
130

131
Type definitions for command-line arguments and molecule execution parameters.
132

133
```python { .api }
134
class MoleculeArgs:
135
    """Base arguments passed to all Molecule commands."""
136
    base_config: list[str]
137
    debug: bool
138
    env_file: str
139
    verbose: int
140

141
class CommandArgs:
142
    """Commandline arguments passed to molecule."""
143
    destroy: Literal["always", "never"]
144
    driver_name: str
145
    force: bool
146
    format: Literal["simple", "plain", "yaml"]
147
    host: str
148
    parallel: bool
149
    platform_name: str
150
    report: bool
151
    scenario_name: str
152
    shared_inventory: bool
153
    shared_state: bool
154
    subcommand: str
155
```
156

157
### Status and Results
158

159
Data structures for tracking test execution status and results.
160

161
```python { .api }
162
class Status:
163
    """NamedTuple with scenario status information."""
164
    instance_name: str
165
    driver_name: str
166
    provisioner_name: str
167
    scenario_name: str
168
    created: str  # String representation of boolean ("true"/"false")
169
    converged: str  # String representation of boolean ("true"/"false")
170

171
class ScenarioResult:
172
    """Dictionary containing the result of a Scenario action."""
173
    subcommand: str | None
174
    state: Literal["PASSED", "FAILED", "SKIPPED"]
175

176
class ScenariosResults:
177
    """Dictionary containing results of multiple Scenario runs."""
178
    name: str
179
    results: list[ScenarioResult]
180
```
181

182
### Supporting Classes
183

184
Additional classes for managing scenario components.
185

186
```python { .api }
187
class Platforms:
188
    """
189
    Defines the instances to be tested and their groups.
190
    
191
    Manages platform configuration, instance relationships,
192
    and group membership for test environments.
193
    """
194

195
class Scenario:
196
    """
197
    Represents a Molecule scenario.
198
    
199
    Contains scenario metadata, sequence definitions,
200
    and execution state for a complete test workflow.
201
    """
202
```
203

204
## Usage Examples
205

206
### Basic Configuration Setup
207

208
```python
209
from molecule.config import Config
210
from molecule.types import MoleculeArgs, CommandArgs
211

212
# Create molecule arguments
213
mol_args = MoleculeArgs(
214
    debug=True,
215
    verbose=2,
216
    base_config=[],
217
    env_file=".env.yml"
218
)
219

220
# Create command arguments
221
cmd_args = CommandArgs(
222
    scenario_name="default",
223
    driver_name="default",
224
    destroy="always"
225
)
226

227
# Initialize configuration
228
config = Config(args=mol_args, command_args=cmd_args)
229

230
# Access configuration components
231
print(f"Driver: {config.driver.name}")
232
print(f"Scenario: {config.scenario.name}")
233
print(f"Platforms: {len(config.platforms.instances)}")
234
```
235

236
### Configuration File Loading
237

238
```yaml
239
# molecule.yml - Example configuration
240
dependency:
241
  name: galaxy
242
  enabled: true
243
  options:
244
    role-file: requirements.yml
245

246
driver:
247
  name: default
248
  options:
249
    managed: false
250

251
platforms:
252
  - name: instance-1
253
    groups:
254
      - web_servers
255
    children:
256
      - databases
257

258
provisioner:
259
  name: ansible
260
  config_options:
261
    defaults:
262
      host_key_checking: false
263
  ansible_args:
264
    - --diff
265
    - --extra-vars
266
    - test_var=value
267
  env:
268
    ANSIBLE_ROLES_PATH: ../roles
269

270
verifier:
271
  name: ansible
272
  enabled: true
273
  directory: verify
274

275
scenario:
276
  name: default
277
  test_sequence:
278
    - dependency
279
    - cleanup  
280
    - destroy
281
    - syntax
282
    - create
283
    - prepare
284
    - converge
285
    - idempotence
286
    - side_effect
287
    - verify
288
    - cleanup
289
    - destroy
290
```
291

292
### Programmatic Configuration
293

294
```python
295
from molecule.config import Config
296
from molecule.types import ConfigData, ScenarioData, PlatformData
297

298
# Create scenario configuration
299
scenario_data = ScenarioData(
300
    name="integration",
301
    test_sequence=[
302
        "create", "prepare", "converge", 
303
        "verify", "destroy"
304
    ],
305
    converge_sequence=["converge"],
306
    verify_sequence=["verify"]
307
)
308

309
# Create platform configuration
310
platform_data = PlatformData(
311
    name="ubuntu-20.04",
312
    groups=["test_servers"],
313
    children=[]
314
)
315

316
# Build complete configuration
317
config_data = ConfigData(
318
    scenario=scenario_data,
319
    platforms=[platform_data],
320
    # ... other configuration sections
321
)
322
```
323

324
### Status Monitoring
325

326
```python
327
from molecule.config import Config
328

329
config = Config()
330

331
# Get driver status
332
driver_status = config.driver.status()
333
for status in driver_status:
334
    print(f"Instance: {status.instance_name}")
335
    print(f"Created: {status.created}")
336
    print(f"Converged: {status.converged}")
337
    print(f"Driver: {status.driver_name}")
338

339
# Get scenario state
340
scenario_state = config.state
341
print(f"Scenario state: {scenario_state}")
342
```
343

344
## Integration Notes
345

346
- Configuration is loaded from `molecule.yml` files using YAML parsing
347
- Environment variable substitution is supported in configuration files
348
- Multiple configuration files can be merged using the `--base-config` option
349
- Type safety is enforced through TypedDict classes for all configuration structures
350
- Configuration validation uses JSON schema definitions
351
- State persistence allows resuming test sequences from intermediate steps
352
- Platform configuration supports complex inheritance and grouping scenarios