测试 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选项在云托管的临时虚拟机中运行测试。

注意

除非在经过批准的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选项来确保安装了正确版本的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命令。