测试 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，可以在 PATH 中找到。
包含一个作为子进程运行的 sleep 实用程序。
包含支持的 Python 版本。
避免使用 VOLUME 语句。

Docker 和 SELinux 

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

带有 WSL2 的 Docker Desktop 

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

注意

如果您的 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。

现在您应该能够使用带有 --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 选项可以在云托管的临时虚拟机中运行测试。

注意

使用此功能需要 API 密钥，除非是在已批准的 Azure Pipelines 组织中运行。

要查看支持的系统列表，请对要使用的 ansible-test 命令使用 --help 选项。

注意

可用系统的列表取决于您正在使用的 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 命令。