OpenTofu 模块测试能力解决哪类交付问题

OpenTofu 的模块测试能力，主要解决的是“模块可以解析，却把对调用方的交付承诺改坏了”这一类问题：例如环境前缀变化、输出字段值不再符合约定、非法输入意外被接受。我会把它放在模块交付之前，用显式输入和断言表达这些承诺，而不把一次测试通过理解为生产环境全部可用。

官方地址：https://opentofu.org/。当前官方文档提供 tofu test 的用例与断言机制。这里讨论现有能力的实际采用，不将其描述为刚发布的新闻。下面是我会选择的纯计算练习场景，代码和预期均未在本文环境执行，也没有创建基础设施。

我更关心模块是否守住输出契约

如果一个共享命名模块被多个业务仓库引用，我不希望每次改动都只能靠调用方在发布时发现名字变了。模块自身应该给出一组可以重复检查的输入：传入环境和应用名，预期得到什么名称；传入不允许的环境，预期拒绝什么。

这类检查的价值不在于替代所有工具，而在于把自然语言约定落成模块级反馈。默认值、条件分支和公开输出，都比“代码没有语法错误”更靠近调用方体验。对还没有复杂依赖的模块，我会先选成本低、结果明确的契约，而不是一上来为每个用例搭一整套云环境。

我给这个例子限定两条承诺：交付名称由环境前缀和规范化应用名组成；环境只接受 dev、qa、prod。它不承诺任意字符都符合某个云厂商的资源命名规则，也不涉及网络、权限或实际服务可用性。

先写一个没有云资源的模块

在独立练习目录保存 main.tf。这个文件仅包含变量、局部值和输出，不引用生产 backend，不读取外部数据源，也不调用其他模块：

# 纯计算命名模块：不声明 provider、resource、data 或远程模块。
variable "environment" {
  type    = string
  default = "qa"
  validation {
    condition     = contains(["dev", "qa", "prod"], var.environment)
    error_message = "环境只能为 dev、qa 或 prod。"
  }
}

variable "application" {
  type    = string
  default = "atlas"
}

locals {
  # 将应用名去除首尾空格并转为小写，形成对调用方公开的命名约定。
  delivery_name = format("%s-%s", var.environment, lower(trimspace(var.application)))
}

output "delivery_name" {
  value = local.delivery_name
}

我把计算结果放在 output.delivery_name，是因为调用方真正消费的是输出，而不是 locals 的内部写法。以后把内部表达式拆成多个局部值，只要公开承诺不变，测试就不应为了内部重排而被迫改写。

这里的变量 validation 限制了 environment。它与模块测试配合：模块负责拒绝输入，测试负责确认这个拒绝约定没有被意外删掉。需要更完整的应用名规则时应再补明确的校验和相应用例，不能把本例的 trimspace 与 lower 当成完整的输入清洗方案。

用三组 plan 用例表达交付承诺

再建立 tests/delivery.tftest.hcl。每个 run 显式选择 plan，本例的值均可在计划阶段计算：

# 正常输入：锁定空格处理、小写转换和环境前缀。
run "normalized_name" {
  command = plan
  variables {
    environment = "qa"
    application = " Atlas "
  }
  assert {
    condition     = output.delivery_name == "qa-atlas"
    error_message = "交付名称没有遵守规范化约定。"
  }
}

# 第二组输入：避免测试只覆盖默认环境。
run "production_prefix" {
  command = plan
  variables {
    environment = "prod"
    application = "atlas"
  }
  assert {
    condition     = output.delivery_name == "prod-atlas"
    error_message = "生产环境前缀不正确。"
  }
}

# 拒绝输入：预期的是指定变量的自定义校验失败，不是任意报错。
run "reject_unknown_environment" {
  command = plan
  variables {
    environment = "preview"
  }
  expect_failures = [var.environment]
}

第一组同时覆盖首尾空格与大小写转换；第二组覆盖不同环境；第三组预期指定变量的自定义条件失败。如果该条件不再拒绝 preview，负向用例就失去了预期错误，应当提示交付约定被改变。

我会让错误说明直接写出失败的承诺，而不是“test failed”。不过 expect_failures 不是吞掉所有错误的开关：它针对配置里的指定自定义条件，不代表连接失败、provider 内部错误或其他异常都算“符合预期”。

读者可在只包含上述文件的独立目录中尝试以下命令；本文没有执行这些命令，不提供伪造的通过日志：

# 在专门的新练习目录中执行，不借用已有云项目。
# 目录内只放本文 main.tf 与 tests/delivery.tftest.hcl。
tofu init
tofu test -filter=tests/delivery.tftest.hcl

对这个没有外部 provider、资源、数据源和模块依赖的练习，目标只是检查表达式与变量契约。预期是两组输出断言成立、非法环境按指定条件被拒绝。若把命名公式故意改为不转小写，第一组应当暴露差异；这是建议的反向检查，不是已经测得的结果。

它和 validate、plan 不是重复劳动

我最看重的收益，是模块仓库可以自己带着交付规则演进；代价则是团队要维护代表性输入和有意义的断言。若把输出公式原样抄进测试再比较，两边一起写错仍可能通过，所以示例使用独立写出的期望值。

默认 apply 是我会特别留意的风险

官方测试机制的 run 默认采用 apply，真实资源测试还涉及创建和清理。本例显式指定 plan，并且不声明资源；这两点共同限定了练习范围。不要从本例推导“所有 tofu test 都不会产生费用”，也不要认为任意有 provider 或 data source 的 plan 都不访问远端。

真实模块需要集成测试时，我会要求独立测试账号、最小权限、唯一资源命名和资源预算，并把清理失败作为需要处理的结果。测试框架会尝试清理它创建的资源，但权限变化、外部依赖和进程中断都可能留下需排查的对象。一次断言通过不能替代资源清点。

进入 CI 时，还需要固定 CLI 版本、依赖版本及可复用的测试输入，限制不可信改动拿到高权限凭据。带敏感输出的日志不应直接公开。以上是采用建议，不是本文对任何现有环境执行过的检查。

对维护共享模块的人，这套能力适合从命名、标签、输出形状和非法输入等稳定契约起步；对只关心线上可用性的人，它不能代替集成测试。我的取舍是先用低依赖用例发现可计算的回归，再把必须依赖真实环境的承诺交给隔离的资源测试。

官方资料

测试命令与用例结构：https://opentofu.org/docs/cli/commands/test/

配置静态检查的职责：https://opentofu.org/docs/cli/commands/validate/

输入变量与校验规则：https://opentofu.org/docs/language/values/variables/