Ansible Molecule 测试角色

bash pip install molecule molecule-plugins[docker]

`molecule-plugins[docker]` 会安装 Docker 驱动程序，让你在容器中运行测试。如果使用 Podman，可将 `docker` 替换为 `podman`。

验证安装：

```bash
molecule --version

如果你计划在 Windows 或 macOS 上运行 Linux 容器，请确保已安装并启动 Docker Desktop（或等效工具）。

创建你的第一个角色与 Molecule 场景

通常你会在一个 Ansible 角色目录下初始化 Molecule 配置。如果你的角色还不存在，可以用 ansible-galaxy 快速生成骨架：

ansible-galaxy role init myrole
cd myrole

进入角色目录后，使用 Molecule 初始化默认场景：

molecule init scenario --driver-name docker

该命令会在角色根目录下创建 molecule/default/ 目录，内含：

• molecule.yml – 场景配置（平台、驱动、依赖等）
• converge.yml – 应用角色并执行测试的 playbook
• verify.yml – 验证步骤（默认调用 Testinfra）
• create.yml / destroy.yml – 生命周期管理（可选）

此时你的目录结构大致如下：

myrole/
├── defaults/
├── handlers/
├── meta/
├── tasks/
├── tests/
├── vars/
├── molecule/
│   └── default/
│       ├── converge.yml
│       ├── molecule.yml
│       └── verify.yml
└── ...

理解场景的核心：molecule.yml 配置

打开 molecule/default/molecule.yml，你会看到类似配置：

dependency:
  name: galaxy
driver:
  name: docker
platforms:
  - name: instance
    image: geerlingguy/docker-ubuntu2204-ansible:latest
    pre_build_image: true
provisioner:
  name: ansible
verifier:
  name: ansible

关键配置项说明

拓展多平台测试

你可以在 platforms 下添加多个实例，模拟真实的多版本环境：

platforms:
  - name: ubuntu-22
    image: geerlingguy/docker-ubuntu2204-ansible:latest
    pre_build_image: true
  - name: debian-11
    image: geerlingguy/docker-debian11-ansible:latest
    pre_build_image: true
  - name: centos-stream9
    image: geerlingguy/docker-centos-stream9-ansible:latest
    pre_build_image: true

这些镜像由 Jeff Geerling 维护，专为 Ansible 测试优化，内置 Python 和必要工具。

编写测试：从 converge 到 verify

converge.yml – 应用角色

converge.yml 就是普通的 Ansible playbook，负责把你的角色应用到测试实例上：

---
- name: Converge
  hosts: all
  become: true
  roles:
    - role: myrole

你可以在这里传递变量：

roles:
  - role: myrole
    vars:
      myrole_package_state: latest

注意：hosts: all 会映射到 Molecule 创建的所有实例。

verify.yml – 声明式验证

现代 Molecule（2.x 之后）使用 Ansible 自身的 assert 或 stat 模块进行验证，无需外部 Testinfra 工具。默认的 verify.yml 可能如下：

---
- name: Verify
  hosts: all
  become: true
  tasks:
    - name: Check if nginx is installed
      ansible.builtin.package:
        name: nginx
        state: present
      check_mode: true
      register: pkg_check
      failed_when:
        - pkg_check is changed
    - name: Assert service is running
      ansible.builtin.service_facts:
    - name: Test nginx service state
      assert:
        that:
          - ansible_facts.services["nginx.service"].state == "running"
          - ansible_facts.services["nginx.service"].status == "enabled"

如果你更习惯 Testinfra（Python 断言），可以在 molecule.yml 中将 verifier 改为 testinfra，并在 tests/ 目录下编写 test_default.py。

执行生命周期命令

Molecule 将测试过程分为几个阶段，你可以单独执行或一键完成所有步骤。

列出所有可用命令

molecule --help

关键命令

日常开发流

1. 修改角色任务后，运行 molecule converge 快速部署到现有实例。
2. 确认行为后，运行 molecule verify 检查断言。
3. 如果只改测试，可单独执行 molecule verify。
4. 提交前运行 molecule test 完成全流程验证。

幂等性验证：保证角色可重复运行

Ansible 角色必须具备幂等性：多次运行后系统状态不变。Molecule 内置幂等性检查，可通过以下命令触发：

molecule idempotence

它会执行两次 converge：第一次部署，第二次重新应用，期望结果为 changed=0。若第二次仍有任务被标记为 changed，则幂等性失败，你需要检查角色逻辑。

若使用 molecule test，幂等性检查会自动执行。

多场景管理：针对不同用例独立测试

复杂角色可能需要多种配置组合（例如：不同安装模式、不同依赖版本）。Molecule 的场景机制完美解决这一问题。

创建新场景

molecule init scenario --role-name myrole new-scenario

这会在 molecule/new-scenario/ 下生成独立的配置和 playbook。

场景切换

在执行命令时通过 -s 参数指定场景：

molecule test -s new-scenario

场景重用

你可以在新场景的 molecule.yml 中复用默认场景的部分内容，只需编写差异部分即可。

进阶：集成 CI/CD（以 GitHub Actions 为例）

为了让每次提交都自动跑测试，在仓库根目录创建 .github/workflows/molecule.yml：

name: Molecule test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        scenario:
          - default
          - new-scenario
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install dependencies
        run: pip install molecule molecule-plugins[docker] ansible
      - name: Run molecule test
        run: molecule test -s ${{ matrix.scenario }}
        env:
          MOLECULE_NO_LOG: false

该流水线会：

1. 检出代码
2. 安装 Molecule 及 Docker 插件
3. 对每个场景并行运行 molecule test

你可以根据需求添加 MOLECULE_DISTRO 等环境变量来切换基础镜像。

常见问题与排错

1. Docker 权限错误

sudo usermod -aG docker $USER