tox-ansible 的用法

需要帮助或想讨论该项目？请参阅我们的贡献者指南，了解如何加入对话！

在您的集合的根目录下，创建一个空的 tox-ansible.ini 文件并列出可用的环境

touch tox-ansible.ini
tox list --ansible --conf tox-ansible.ini

将显示动态生成的 Ansible 环境列表

default environments:
...
integration-py3.11-2.14      -> Integration tests for ansible.scm using ansible-core 2.14 and python 3.11
integration-py3.11-devel     -> Integration tests for ansible.scm using ansible-core devel and python 3.11
integration-py3.11-milestone -> Integration tests for ansible.scm using ansible-core milestone and python 3.11
...
sanity-py3.11-2.14           -> Sanity tests for ansible.scm using ansible-core 2.14 and python 3.11
sanity-py3.11-devel          -> Sanity tests for ansible.scm using ansible-core devel and python 3.11
sanity-py3.11-milestone      -> Sanity tests for ansible.scm using ansible-core milestone and python 3.11
...
unit-py3.11-2.14             -> Unit tests for ansible.scm using ansible-core 2.14 and python 3.11
unit-py3.11-devel            -> Unit tests for ansible.scm using ansible-core devel and python 3.11
unit-py3.11-milestone        -> Unit tests for ansible.scm using ansible-core milestone and python 3.11

这些代表可用的测试环境。每个环境都表示要运行的测试类型、用于运行测试的 Python 解释器以及用于运行测试的 Ansible 版本。

要使用单个环境运行测试，只需运行以下命令

tox -e sanity-py3.11-2.14 --ansible --conf tox-ansible.ini

要使用多个环境运行测试，只需将环境名称添加到命令中

tox -e sanity-py3.11-2.14,unit-py3.11-2.14 --ansible --conf tox-ansible.ini

要在所有可用环境中运行特定类型的所有测试，请使用因子 -f 标志

tox -f unit --ansible -p auto --conf tox-ansible.ini

要在所有可用环境中运行所有测试

tox --ansible -p auto --conf tox-ansible.ini

注意：-p auto 标志将并行运行多个测试。注意：特定的 Python 解释器需要在您的系统上预先安装，例如。

sudo dnf install python3.9

要查看每个集成、健全性和单元因子的具体命令和配置

tox config --ansible --conf tox-ansible.ini

根据 --matrix-scope 中提到的范围生成特定的 GitHub 操作矩阵

tox --ansible --gh-matrix --matrix-scope unit --conf tox-ansible.ini

将显示专门用于单元测试的动态生成的 Ansible 环境列表

[
  {
    "description": "Unit tests using ansible 2.9 and python 3.8",
    "factors": [
      "unit",
      "py3.8",
      "2.9"
    ],
    "name": "unit-py3.8-2.9",
    "python": "3.8"
  },
  ...
  {
    "description": "Unit tests using ansible-core milestone and python 3.12",
    "factors": [
      "unit",
      "py3.12",
      "milestone"
    ],
    "name": "unit-py3.12-milestone",
    "python": "3.12"
  }
]

将命令行参数传递给 ansible-test / pytest

可以通过向 ansible-test (对于 sanity-* 环境) 或 pytest (对于 unit-* 和 integration-* 环境) 命令传递其他命令行参数来自定义其行为，例如，像这样调用 tox

tox -f sanity --ansible --conf tox-ansible.ini -- --test validate-modules -vvv

-- 之后的参数将传递给 ansible-test 命令。因此，在此示例中，将仅运行 validate-modules 健全性测试，但会增加详细程度。

可以执行相同的操作，将参数传递给 unit-* 和 integration-* 环境的 pytest 命令

tox -e unit-py3.11-2.15 --ansible --conf tox-ansible.ini -- --junit-xml=tests/output/junit/unit.xml

在 CI/CD 管道中使用

该存储库包含一个 GitHub 工作流程，可以在 GitHub Actions CI/CD 管道中使用。除非受 tox-ansible.ini 文件中 skip 选项的限制，否则该工作流程将在所有可用环境中运行所有测试。

每个环境将在单独的作业中运行。该工作流程将并行运行所有作业。

GitHub 矩阵由 tox-ansible 使用 --gh-matrix 和 --ansible 标志动态创建。环境列表将转换为 json 格式的条目列表，并添加到由 "GITHUB_OUTPUT" 环境变量指定的文件中。工作流程将读取此文件并使用它来创建矩阵。

GitHub 工作流程的示例用法可能如下所示

name: Test collection

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

on:
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  tox-ansible:
    uses: ansible/tox-ansible/.github/workflows/run.yml@main

示例 json

[
  // ...
  {
    "description": "Integration tests using ansible-core devel and python 3.11",
    "factors": ["integration", "py3.11", "devel"],
    "name": "integration-py3.11-devel",
    "python": "3.11"
  }
  // ...
]

测试 molecule 场景

尽管 tox-ansible 插件没有特定于 molecule 的功能，但它可能是一个强大的工具，可以在 Ansible 和 Python 版本的矩阵中运行 molecule 场景。

这可以通过使用 pytest-ansible 插件将 molecule 场景呈现为可通过 pytest 获得的集成测试来实现，该插件在安装 tox-ansible 时安装。

假设以下集合目录结构

namespace.name
├── extensions
│   ├── molecule
│   │   ├── playbook
│   │   │   ├── create.yml
│   │   │   ├── converge.yml
│   │   │   ├── molecule.yml
│   │   │   └── verify.yml
│   │   ├── plugins
│   │   │   ├── create.yml
│   │   │   ├── converge.yml
│   │   │   ├── molecule.yml
│   │   │   └── verify.yml
│   │   ├── targets
│   │   │   ├── create.yml
│   │   │   ├── converge.yml
│   │   │   ├── molecule.yml
│   │   │   └── verify.yml
├── playbooks
│   └── site.yaml
├── plugins
│   ├── action
│   │   └── action_plugin.py
│   ├── modules
│   │   └── module.py
├── tests
│   ├── integration
│   │   │── targets
│   │   │   ├── success
│   │   │   │   └── tasks
│   │   │   │       └── main.yaml
│   │   └── test_integration.py
├── tox-ansible.ini
└── tox.ini

可以将单独的 molecule 场景添加到集合的扩展目录中，以测试剧本、角色和集成目标。

为了将每个 molecule 场景呈现为单独的 pytest 测试，需要添加一个新的 helper 文件。

# tests/integration/test_integration.py

"""Tests for molecule scenarios."""
from __future__ import absolute_import, division, print_function

from pytest_ansible.molecule import MoleculeScenario


def test_integration(molecule_scenario: MoleculeScenario) -> None:
    """Run molecule for each scenario.

    :param molecule_scenario: The molecule scenario object
    """
    proc = molecule_scenario.test()
    assert proc.returncode == 0

molecule_scenario fixture 对集合中找到的 molecule 场景进行参数化，并为每个场景创建一个单独的 pytest 测试，该测试将在任何 integration-* 环境期间运行。

这种方法提供了使用 molecule、pytest 或 tox 直接运行 molecule 场景的灵活性。此外，作为原生 pytest 测试呈现，molecule 场景应显示在用户 IDE 中的 pytest 测试树中。