测试 Ansible 和集合

本文档介绍如何使用 ansible-test 运行测试。

设置

在运行 ansible-test 之前，请根据您的情况，为 测试 Ansible 集合 或 测试 ansible-core 设置您的环境。

警告

如果您使用 git 进行版本控制，请确保您正在使用的文件没有被 git 忽略。如果被忽略，ansible-test 也会忽略它们。

测试 Ansible 集合

如果要测试 Ansible 集合，您需要该集合的副本，最好是 Git 克隆。例如，要使用 community.windows 集合，请按照以下步骤操作

  1. 将要测试的集合克隆到有效的集合根目录

    git clone https://github.com/ansible-collections/community.windows ~/dev/ansible_collections/community/windows

    重要

    路径必须以 /ansible_collections/{collection_namespace}/{collection_name} 结尾，其中 {collection_namespace} 是集合的命名空间，{collection_name} 是集合名称。

  2. 克隆集合所依赖的任何集合

    git clone https://github.com/ansible-collections/ansible.windows ~/dev/ansible_collections/ansible/windows

    重要

    如果您的集合对其他集合有任何依赖项，它们必须位于相同的集合根目录中，因为 ansible-test 不会使用您配置的集合根目录（或其他 Ansible 配置）。

    注意

    有关可能的依赖项列表，请参阅集合的 galaxy.yml。

  3. 切换到要测试的集合所在的目录

    cd ~/dev/ansible_collections/community/windows

测试 ansible-core

如果要测试 ansible-core 本身，则需要 ansible-core 源代码的副本，最好是 Git 克隆。拥有已安装的 ansible-core 副本是不够的，也不是必需的。例如，要使用从 GitHub 克隆的 ansible-core 源代码，请按照以下步骤操作

  1. 克隆 ansible-core 存储库

    git clone https://github.com/ansible/ansible ~/dev/ansible

  2. 切换到 ansible-core 源代码所在的目录

    cd ~/dev/ansible

  3. 将 ansible-core 程序添加到您的 PATH

    source hacking/env-setup

    注意

    如果只需要运行 ansible-test，而不需要其他 ansible-core 程序，则可以跳过此步骤。在这种情况下，只需从 ansible-core 源代码的根目录运行 bin/ansible-test 即可。

    注意

    如果您已安装 ansible-core 版本，并且尝试从 PATH 运行 ansible-test，请确保 shell 找到的程序是 ansible-core 源代码中的程序

    which ansible-test

命令

最常用的测试命令是

  • ansible-test sanity - 运行健全性测试（主要是 linter 和静态分析）。

  • ansible-test integration - 运行集成测试。

  • ansible-test units - 运行单元测试。

运行 ansible-test --help 以查看可用命令的完整列表。

注意

有关特定命令的详细帮助，请在命令后添加 --help 选项。

环境

大多数 ansible-test 命令都支持在一个或多个隔离的测试环境中运行，以简化测试。

容器

建议使用容器运行健全性、单元和集成测试，因为它们提供了一致的环境。单元测试将在网络隔离的情况下运行，从而避免了对网络资源的意外依赖。

--docker 选项使用 Docker 或 Podman 在容器中运行测试。

注意

如果同时安装了 Docker 和 Podman，将使用 Docker。要覆盖此设置，请将环境变量 ANSIBLE_TEST_PREFER_PODMAN 设置为任何非空值。

选择容器

如果没有其他参数，--docker 选项将使用 default 容器。要使用其他容器，请在 --docker 选项后立即指定它。

注意

建议所有健全性和单元测试使用 default 容器。

要查看支持的容器列表，请将 --help 选项与要使用的 ansible-test 命令一起使用。

注意

可用容器列表取决于您正在使用的 ansible-test 命令。

您还可以指定自己的容器。执行此操作时，您需要使用 --python 选项指示容器中的 Python 版本。

自定义容器

构建自定义容器时，请记住以下要求

  • USER 应该是 root。

  • 使用 init 进程，例如 systemd。

  • 包含 sshd 并接受默认端口 22 上的连接。

  • 包含一个可在 PATH 上找到的 POSIX 兼容的 sh shell。

  • 包含一个作为子进程运行的 sleep 实用程序。

  • 包含受支持的 Python 版本。

  • 避免使用 VOLUME 语句。

Docker 和 SELinux

在具有 SELinux 的主机上使用 Docker 可能需要将系统设置为宽容模式。请考虑改用 Podman。

带有 WSL2 的 Docker Desktop

这些说明解释了如何在 WSL2 和 Docker Desktop 中使用 ansible-test，而无需 systemd 支持。

注意

如果您的 WSL2 环境包含 systemd 支持，则不需要这些步骤。

配置要求

  1. 打开 Docker Desktop 并转到 Settings 屏幕。

  2. 在 General 选项卡上

    1. 取消选中 Start Docker Desktop when you log in 复选框。

    2. 选中 Use the WSL 2 based engine 复选框。

  3. 在 Resources 选项卡上的 WSL Integration 部分下

    1. 在 Enable integration with additional distros 部分下启用要使用的发行版。

  4. 如果进行了更改，请单击 Apply and restart。

设置说明

注意

如果所有 WSL 实例都已停止，则需要重新应用这些更改。

  1. 验证 Docker Desktop 是否已正确配置（请参阅配置要求）。

  2. 如果 Docker Desktop 正在运行，请退出。

    1. 右键单击Docker Desktop任务栏图标。

    2. 单击退出 Docker Desktop选项。

  3. 使用以下命令停止任何正在运行的 WSL 实例：

    wsl --shutdown

  4. 使用以下命令验证所有 WSL 实例是否已停止：

    wsl -l -v

  5. 启动一个 WSL 实例，并以 root 身份执行以下步骤：

    1. 验证 systemd 子系统是否未注册：

      1. 使用以下命令检查 systemd cgroup 层次结构：

        grep systemd /proc/self/cgroup

      2. 如果找到任何匹配项，请重新检查配置要求，并再次按照设置说明进行操作。

    2. 使用以下命令挂载 systemd cgroup 层次结构：

    mkdir /sys/fs/cgroup/systemd
mount cgroup -t cgroup /sys/fs/cgroup/systemd -o none,name=systemd,xattr

  6. 启动 Docker Desktop。

现在您应该可以使用带有 --docker 选项的 ansible-test 了。

Linux cgroup 配置

注意

这些更改需要在每次容器主机启动时重新应用。

对于某些容器主机和容器组合，可能需要在容器主机上进行额外的设置。在这种情况下，ansible-test 将报告错误，并提供以 root 身份运行的其他说明。

mkdir /sys/fs/cgroup/systemd
mount cgroup -t cgroup /sys/fs/cgroup/systemd -o none,name=systemd,xattr

如果您正在使用无根 Podman，则还必须以 root 身份运行其他命令。请确保将 {user} 和 {group} 替换为您自己的用户和组。

chown -R {user}:{group} /sys/fs/cgroup/systemd
Podman

使用 Podman 时，您可能需要在按照Linux cgroup 配置说明操作后停止现有的 Podman 进程。否则，Podman 可能无法看到新的挂载点。

您可以通过查找 podman 和 catatonit 进程来检查 Podman 是否正在运行。

远程虚拟机

建议使用远程虚拟机来运行不适合在容器中执行的集成测试。

--remote 选项在云托管的临时虚拟机中运行测试。

注意

除非在经过批准的 Azure Pipelines 组织下运行，否则需要 API 密钥才能使用此功能。

要查看支持的系统列表，请将 --help 选项与您要使用的 ansible-test 命令一起使用。

注意

可用系统列表取决于您正在使用的 ansible-test 命令。

Python 虚拟环境

Python 虚拟环境提供了一种简单的方法来实现与系统和用户 Python 环境的隔离。当无法使用 --docker 和 --remote 选项时，建议将它们用于单元测试和集成测试。

--venv 选项在由 ansible-test 管理的虚拟环境中运行测试。在运行测试之前会自动安装所需的依赖项。

复合环境参数

本文档中介绍的环境参数足以满足大多数用例。但是，某些情况可能需要复合环境参数提供的额外灵活性。

--controller 和 --target 选项是 --docker、--remote 和 --venv 选项的替代方案。

注意

当使用 shell 命令时，--target 选项将替换为三个特定于平台的选项。

将 --help 选项添加到您的 ansible-test 命令中，以了解有关复合环境参数的更多信息。

其他要求

某些 ansible-test 命令有其他要求。您可以使用 --requirements 选项自动安装它们。

注意

当使用由 ansible-test 管理的测试环境时，通常不需要 --requirements 选项。

环境变量

当使用环境变量来操作测试时，需要注意一些限制。环境变量：

  • 使用 --docker 或 --remote 选项时，不会从主机传播到测试环境。

  • 除非在 test/lib/ansible_test/_internal/util.py 的 common_environment 函数中启用，否则不会暴露给测试环境。

    示例：在运行 ansible-test integration --venv 时，可以设置 ANSIBLE_KEEP_REMOTE_FILES=1。但是，使用 --docker 选项将需要运行 ansible-test shell 来访问 Docker 环境。一旦进入 shell 提示符，就可以设置环境变量并执行测试。这对于按照调试模块的说明调试容器内的测试很有用。

交互式 shell

使用 ansible-test shell 命令在用于运行测试的同一环境中获取交互式 shell。示例：

  • ansible-test shell --docker - 在默认 docker 容器中打开一个 shell。

  • ansible-test shell --venv --python 3.10 - 在 Python 3.10 虚拟环境中打开一个 shell。

代码覆盖率

代码覆盖率报告可以轻松识别未测试的代码，并应该为这些代码编写更多的测试。在线报告可用，但仅涵盖 devel 分支（请参阅测试 Ansible）。对于新代码，需要本地报告。

将 --coverage 选项添加到任何测试命令以收集代码覆盖率数据。如果您没有使用创建隔离的 python 环境的 --venv 或 --docker 选项，那么您可能必须使用 --requirements 选项来确保安装了正确版本的 coverage 模块。

ansible-test coverage erase
ansible-test units --coverage apt
ansible-test integration --coverage aws_lambda
ansible-test coverage html

可以生成多种不同格式的报告：

  • ansible-test coverage report - 控制台报告。

  • ansible-test coverage html - HTML 报告。

  • ansible-test coverage xml - XML 报告。

要在测试运行之间清除数据，请使用 ansible-test coverage erase 命令。