测试 Ansible 和集合

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

设置 

在运行 ansible-test 之前，请为测试 Ansible 集合或测试 ansible-core 设置您的环境，具体取决于您的情况。

警告

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

测试 Ansible 集合 

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

将您要测试的集合克隆到有效的集合根目录
```
git clone https://github.com/ansible-collections/community.windows ~/dev/ansible_collections/community/windows
```
重要

路径必须以 /ansible_collections/{collection_namespace}/{collection_name} 结尾，其中 {collection_namespace} 是集合的命名空间，{collection_name} 是集合的名称。
克隆集合所依赖的任何其他集合
```
git clone https://github.com/ansible-collections/ansible.windows ~/dev/ansible_collections/ansible/windows
```
重要

如果您的集合依赖于其他集合，则它们必须位于同一个集合根目录下，因为 ansible-test 不会使用您配置的集合根目录（或其他 Ansible 配置）。

注意

请查看集合的 galaxy.yml 文件以获取可能的依赖项列表。

切换到包含要测试的集合的目录

cd ~/dev/ansible_collections/community/windows

测试 `ansible-core`

如果您要测试 ansible-core 本身，您需要一份 ansible-core 源代码的副本，最好是 Git 克隆。安装 ansible-core 的副本既不是充分的也不是必要的。例如，要使用从 GitHub 克隆的 ansible-core 源代码，请按照以下步骤操作

克隆 ansible-core 存储库

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

切换到包含 ansible-core 源代码的目录
```
cd ~/dev/ansible
```
将 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 容器。

要查看支持的容器列表，请在要使用的 ansible-test 命令中使用 --help 选项。

注意

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

您也可以指定自己的容器。在这种情况下，您需要使用 --python 选项指示容器中的 Python 版本。

自定义容器 

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

USER 应为 root。
使用 init 进程，例如 systemd。
包括 sshd 并在默认端口 22 上接受连接。
包括一个 POSIX 兼容的 sh shell，该 shell 可以在 PATH 中找到。
包括一个 sleep 实用程序，它可以作为子进程运行。
包括支持的 Python 版本。
避免使用 VOLUME 语句。

Docker 和 SELinux 

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

带有 WSL2 的 Docker 桌面 

这些说明解释了如何在没有 systemd 支持的情况下，使用 ansible-test 与 WSL2 和 Docker Desktop。

注意

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

配置要求 

打开 Docker Desktop 并进入 **设置** 屏幕。
在 **常规** 选项卡上
1. 取消选中 **登录时启动 Docker Desktop** 复选框。
2. 选中 **使用基于 WSL 2 的引擎** 复选框。
在 **资源** 选项卡上的 **WSL 集成** 部分
1. 在 **启用与其他发行版的集成** 部分中启用您要使用的发行版。
如果进行了更改，请单击 **应用并重启**。

设置说明 

注意

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

验证 Docker Desktop 是否已正确配置（参见配置要求）。
如果 Docker Desktop 正在运行，请退出。
1. 右键单击 **Docker Desktop** 任务栏图标。
2. 单击 **退出 Docker Desktop** 选项。
使用以下命令停止任何正在运行的 WSL 实例
```
wsl --shutdown
```
使用以下命令验证所有 WSL 实例是否已停止
```
wsl -l -v
```
启动 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
```
启动 Docker Desktop。

您现在应该能够使用 ansible-test 的 --docker 选项。

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_KEEP_REMOTE_FILES=1 可以在运行 ansible-test integration --venv 时设置。但是，使用 --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 选项添加到任何测试命令以收集代码覆盖率数据。如果您没有使用 --venv 或 --docker 选项创建隔离的 python 环境，那么您可能需要使用 --requirements 选项来确保安装了正确版本的覆盖率模块。

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 命令。