测试 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，它可以在 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 密钥才能使用此功能。

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

注意

可用系统的列表取决于您正在使用的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_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 命令。