测试 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 - 运行健全性测试（主要是 lint 工具和静态分析）。
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 上的连接。
包括一个与 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 并转到 Settings（设置）屏幕。
在 General（常规）选项卡上
1. 取消选中 Start Docker Desktop when you log in（登录时启动 Docker Desktop）复选框。
2. 选中 Use the WSL 2 based engine（使用基于 WSL 2 的引擎）复选框。
在 Resources（资源）选项卡下的 WSL Integration（WSL 集成）部分
1. 在 Enable integration with additional distros（启用与其他发行版的集成）部分下启用要使用的发行版。
如果进行了更改，请单击 Apply and restart（应用并重新启动）。

设置说明 

注意

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

验证 Docker Desktop 是否已正确配置（请参阅配置要求）。
如果 Docker Desktop 正在运行，请退出。
1. 右键单击 Docker Desktop 任务栏图标。
2. 单击 Quit Docker Desktop（退出 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 选项在云托管的临时虚拟机中运行测试。

注意

除非在经过批准的 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 选项添加到任何测试命令以收集代码覆盖率数据。如果您没有使用 --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 命令。