测试 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 容器。

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

注意

可用容器的列表取决于您正在使用的 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 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。

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

注意

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

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

注意

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

Python 虚拟环境 

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

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

复合环境参数 

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

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

注意

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

在您的 ansible-test 命令中添加 --help 选项，以详细了解复合环境参数。

其他要求 

某些 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 选项以确保安装了正确版本的 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 命令。