1.7.23.1. test

terraform test 命令读取 Terraform 测试文件并执行其中的测试。

test 命令和测试文件对于想要验证和测试其旨在被复用的模块的作者特别有用。我们也可以使用 test 命令来验证根模块。

1.7.23.1.1. 用法

terraform test [options]

该命令在当前目录和指定的测试目录（默认情况下是 test 目录）中搜索所有 Terraform 测试文件，并执行指定的测试。有关测试文件的更多详细信息，请参阅测试。

Terraform 然后会根据测试文件的规范执行一系列 Terraform 的 plan 或 apply 命令，并根据测试文件的规范验证相关计划和状态文件。

警告：Terraform 测试命令可以创建真正的基础设施，但可能会产生成本。请参阅 Terraform 测试清理部分，了解确保创建的基础设施被清理的最佳实践。

1.7.23.1.2. 一般参数

Terraform test 命令支持以下参数：

-cloud-run=<module source> - 通过 HCP Terraform 远程运行针对指定的 Terraform 私有注册表模块的测试。
-filter=testfile - 将 terraform test 操作限制为指定的测试文件。
-json - 显示测试结果的机器可读 JSON 输出。
-test-directory=<relative directory> - 指定 Terraform 查找测试文件的目录。请注意，Terraform 始终在主代码目录中加载测试文件。默认的测试目录是 tests。
-verbose - 根据每个运行块的 command 属性打印出测试文件中每个 run 块的计划或状态。

1.7.23.1.3. 状态管理

每个 Terraform 测试文件在执行时都会在内存中从无到有地维护所需的所有 Terraform 状态。该状态完全独立于被测代码的任何现有状态，因此您可以安全地执行 Terraform 测试命令，而不会影响任何已存在的基础设施。

1.7.23.1.3.1. Terraform 测试清理

Terraform test 命令可以创建真实的基础设施。一旦 Terraform 完全执行了所有测试文件，Terraform 就会尝试销毁所有遗留的基础设施。如果无法销毁，Terraform 会报告由它创建但无法销毁的资源列表。

我们应该密切监视测试命令的输出，以确保 Terraform 清理了它创建的基础设施，否则需要执行手动清理。我们建议为目标 Provider 创建专用的测试帐户，这样可以定期安全地清除该帐户内的资源，确保不会意外地留下昂贵的资源。

Terraform 还提供诊断，解释为什么它无法自动清理。我们应该检查这些诊断，以确保未来的清理操作成功。

1.7.23.1.4. 在 HCP Terraform 上运行测试

我们可以使用 -cloud-run 参数在 HCP Terraform 上远程执行测试。

-cloud-run 参数接受私有注册表模块地址。此参数针对 HCP Terraform 用户界面中指定的私有模块运行测试。

我们必须提供来自私有注册表的模块，而不是公共 Terraform 注册表。

在使用该参数之前，您必须执行 terraform login，并确保您的 host 参数与目标模块的私有注册表主机名匹配。

1.7.23.1.5. 例子：测试的目录结构与命令

以下目录结构表示包含测试和配置（setup）模块的 Terraform 模块的示例目录树：

project/
|-- main.tf
|-- outputs.tf
|-- terraform.tf
|-- variables.tf
|-- tests/
|   |-- validations.tftest.hcl
|   |-- outputs.tftest.hcl
|-- testing/
    |-- setup/
        |-- main.tf
        |-- outputs.tf
        |-- terraform.tf
        |-- variables.tf

在项目的根目录下，有一些典型的 Terraform 配置文件：main.tf、outputs.tf、terraform.tf 和 variables.tf。测试文件 validations.tftest.hcl 和 outputs.tftest.hcl 位于默认测试目录 tests 中。

另外 testing 目录下有一个为测试而存在的设置(setup)模块

要执行测试，我们应该从代码根目录运行 terraform test，如同运行 terraform plan 或 terraform apply 一样。尽管实际的测试文件位于内嵌的 tests 目录中，但 Terraform 仍从主代码目录执行。

可以使用 -filter 参数指定执行特定的测试文件。

Linux、Mac 操作系统和 UNIX 下：

terraform test -filter=tests/validations.tftest.hcl

PowerShell：

terraform test -filter='tests\validations.tftest.hcl'

Windows cmd.exe：

terraform test -filter=tests\validations.tftest.hcl

1.7.23.1.5.1. 另一种测试目录结构

在上面的示例中，测试文件位于默认的 tests 目录中。测试文件也可以直接包含在主代码目录中：

project/
|-- main.tf
|-- outputs.tf
|-- terraform.tf
|-- variables.tf
|-- validations.tftest.hcl
|-- outputs.tftest.hcl
|-- testing/
    |-- setup/
        |-- main.tf
        |-- outputs.tf
        |-- terraform.tf
        |-- variables.tf

测试文件的位置不会影响 terraform test 的运行。测试文件的所有引用以及其中的绝对文件路径都应相对于主代码目录。

我们还可以使用 -test-directory 参数来更改测试文件的位置。例如， terraform test -test-directory=testing 将命令 Terraform 从 testing 目录加载测试，而不是 tests。

测试目录必须位于主代码目录下，但可以多层嵌套。

注意：无论 -test-directory 的值为何，根代码目录中的测试文件始终会被加载。

我们不建议更改默认测试目录。这些自定义选项是为那些在 terraform test 功能发布之前可能已在其代码中包含了 tests 子模块的代码作者准备的。一般来说，应始终使用默认的 tests 目录。

test