Molecule Testing Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Molecule Testing Architecture in the spm-middleware repository provides a robust framework for developing, testing, and verifying Ansible roles used in the installation of IBM Cúram Social Program Management (SPM) middleware. The system ensures that all contributions meet quality standards, including idempotency, linting compliance, and functional correctness across various environments like Rocky Linux and CentOS.
The architecture supports two primary development workflows: a local Python virtual environment and a Container-in-Docker (DinD) environment. This allows developers to simulate complex middleware installations (e.g., WebSphere, DB2, IHS) in isolated environments before deployment.
Sources: CONTRIBUTING.md:1-12, README.md:1-10
Core Components and Dependencies
The testing infrastructure relies on a specific stack of Python-based tools and Docker containers to manage the lifecycle of test instances.
Technical Stack
The following table summarizes the key dependencies required for the Molecule environment:
| Tool | Version | Purpose |
|---|---|---|
molecule | 6.0.3 | Core test runner and orchestrator |
molecule-docker | 2.1.0 | Driver for managing Docker-based test instances |
ansible | 8.7.0 | Configuration management engine |
ansible-lint | 6.22.2 | Static analysis for Ansible playbooks/roles |
docker | 7.1.0 | Container engine for isolation |
Sources: ci-requirements.txt:1-10
Environment Architecture
The testing architecture can be visualized as a layered flow where Molecule manages the transition between various stages of a test scenario.
The diagram illustrates the standard Molecule lifecycle used to validate roles against specific scenarios.
Sources: CONTRIBUTING.md:15-30, README.md:55-65
Execution Workflows
1. Local Virtual Environment
Developers can use a Python venv to isolate testing dependencies. This workflow requires docker to be running on the host to act as the Molecule driver.
python3 -m venv ~/venv/molecule
. ~/venv/molecule/bin/activate
pip install -r requirements.txt
molecule test -s ihs-v90-rockylinux8
Sources: CONTRIBUTING.md:1-12
2. Container-in-Docker (DinD) Environment
For a more isolated and portable setup, the project provides a Docker-based environment. This involves running a "Molecule Container" (molly) that internally executes Docker commands to create test instances.
The sequence shows the interaction between the developer, the primary Molecule container, and the nested test instances.
Sources: CONTRIBUTING.md:46-65
Verification Framework
The verify.yml playbooks serve as the automated testing suite for each scenario. They utilize Ansible's assert module and custom modules like merative.spm_middleware.iim_info to validate the state of the system after the converge phase.
Common Verification Tasks
- Package Validation: Ensuring specific IBM Installation Manager (IIM) packages are present.
- Configuration Check: Using
slurpto read files and verify content (e.g., JVM options or environment variables). - State Assertion: Checking binary existence and permissions.
Example Verification Structure (molecule/__websphere-v90/verify.yml)
- name: Verify
hosts: all
pre_tasks:
- name: Check packages
merative.spm_middleware.iim_info:
iim_path: /opt/IBM/InstallationManager
register: iim_info
tasks:
- name: Check that the correct packages are installed
assert:
that:
- "iim_info.packages | select('match', 'com.ibm.websphere.ND.v90.*') | list | length > 0"
Sources: molecule/__websphere-v90/verify.yml:1-30, molecule/__liberty/verify.yml:1-25
Asset Management (Artifactory Integration)
Because middleware installers (WAS, DB2, etc.) are large, the testing architecture supports fetching assets from Artifactory via environment variables.
| Variable | Description |
|---|---|
ARTIFACTORY_URL | The base URL for the Artifactory instance |
ARTIFACTORY_REPO | The repository containing software installers |
ARTIFACTORY_TOKEN | Authentication token for the API |
These variables are passed into the Molecule container or defined in a .env file for VS Code Dev Containers.
Sources: CONTRIBUTING.md:80-95, README.md:65-75
Summary
The Molecule Testing Architecture in this project provides a standardized way to ensure that middleware installation roles are reliable and idempotent. By utilizing Docker for isolation and a structured lifecycle (Create, Converge, Verify), the project maintains high quality for complex IBM SPM infrastructure deployments across multiple operating systems.