测试 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 - 运行健全性测试（主要是 linters 和静态分析）。
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 并转到 Settings 屏幕。
在 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 管理的虚拟环境中运行测试。在运行测试之前会自动安装要求。

复合环境参数 

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

--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 选项以确保安装了正确版本的覆盖率模块。

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 命令。