tessl/pypi-molecule

Molecule aids in the development and testing of Ansible roles

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Molecule

Name: tessl/pypi-molecule
Author: tessl

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.

Package Information

Package Name: molecule
Language: Python
Installation: pip install molecule
Python Version: >=3.10

Core Imports

import molecule

For API access:

from molecule.api import drivers, verifiers, Driver, Verifier

For configuration:

from molecule.config import Config

For exceptions:

from molecule.exceptions import MoleculeError, ScenarioFailureError

For concrete verifiers:

from molecule.verifier.ansible import Ansible
from molecule.verifier.testinfra import Testinfra

Basic Usage

from molecule.api import drivers, verifiers

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

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

# Access package version
import molecule
print("Molecule version:", molecule.__version__)

Command-line usage:

# Create a new role with molecule scenario
molecule init role my-role --driver-name default

# Run the full test sequence
molecule test

# Create test instances
molecule create

# Converge (apply) the role
molecule converge

# Run verification tests
molecule verify

# Destroy test instances
molecule destroy

Architecture

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

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

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

Capabilities

Core API Functions

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

def drivers(config=None):
    """
    Return list of active drivers.
    
    Args:
        config: plugin config
        
    Returns:
        dict[str, Driver]: A dictionary of active drivers by name
    """

def verifiers(config=None):
    """
    Return list of active verifiers.
    
    Args:
        config: plugin config
        
    Returns:
        dict[str, Verifier]: A dictionary of active verifiers by name
    """

Core API

Command-Line Interface

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

def main(ctx, debug, verbose, base_config, env_file):
    """
    Molecule aids in the development and testing of Ansible roles.
    
    Args:
        ctx: Click context object
        debug: Debug option value
        verbose: Verbose option value  
        base_config: Base config option value
        env_file: Environment variable file option value
    """

CLI Commands

Driver System

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

class Driver:
    """Base class for all drivers."""
    
    @property
    def name(self):
        """Name of the driver."""
    
    @property  
    def login_cmd_template(self):
        """Login command template."""
        
    def sanity_checks(self):
        """Confirm that driver is usable."""
        
    def status(self):
        """Collect instances state."""

Driver System

Verifier System

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

class Verifier:
    """Base class for all verifiers."""
    
    @property
    def name(self):
        """Name of the verifier."""
        
    @property
    def enabled(self):
        """Is the verifier enabled."""
        
    def execute(self, action_args):
        """Execute cmd."""
        
    def schema(self):
        """Return validation schema."""

Verifier System

Configuration Management

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

class Config:
    """Main configuration management class."""
    
class ConfigData:
    """Class representing molecule config."""
    
class ScenarioData:
    """Molecule scenario configuration."""
    
class PlatformData:
    """Platform data for a Molecule run."""

Configuration

Exception Handling

Comprehensive exception system for handling errors during testing workflows.

class MoleculeError(Exception):
    """
    Generic Molecule error.
    
    Args:
        message: The message to display about the problem
        code: Exit code to use when exiting
        warns: Warnings about the problem to issue
    """
    
class ScenarioFailureError(MoleculeError):
    """Details about a scenario that failed."""

Exception Handling

Types

# Core type definitions
Options = MutableMapping[str, str | bool]

class MoleculeArgs:
    """Base arguments passed to all Molecule commands."""
    base_config: list[str]
    debug: bool
    env_file: str  
    verbose: int

class CommandArgs:
    """Commandline arguments passed to molecule."""
    destroy: Literal["always", "never"]
    driver_name: str
    force: bool
    format: Literal["simple", "plain", "yaml"]
    scenario_name: str
    platform_name: str
    parallel: bool

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