测试 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 上的连接。
包含可在 PATH 上找到的 POSIX 兼容的 sh shell。
包含作为子进程运行的 sleep 实用程序。
包含受支持的 Python 版本。
避免使用 VOLUME 语句。

Docker 和 SELinux 

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

带有 WSL2 的 Docker Desktop 

以下说明解释了如何在不支持 systemd 的情况下，将 ansible-test 与 WSL2 和 Docker Desktop 结合使用。

注意

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

配置要求 

打开 Docker Desktop 并转到“设置”屏幕。
在 General 标签页中
1. 取消选中 Start Docker Desktop when you log in 复选框。
2. 选中 Use the WSL 2 based engine 复选框。
在 Resources 标签页的 WSL Integration 部分
1. 在 Enable integration with additional distros 部分下启用您想要使用的发行版。
如果进行了更改，请单击 Apply and restart。

设置说明 

注意

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

验证 Docker Desktop 是否已正确配置（请参阅配置要求）。
如果 Docker Desktop 正在运行，请退出。
1. 右键单击 Docker Desktop 任务栏图标。
2. 单击 Quit 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 管理的虚拟环境中运行测试。在运行测试之前，会自动安装 requirements。

复合环境参数 

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

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