Команда: test

Команда tofu test позволяет протестировать конфигурацию OpenTofu, создав реальную инфраструктуру и проверив выполнение необходимых условий (утверждений). После завершения теста OpenTofu удаляет созданные ресурсы.

Использование​

Использование: tofu test [options].

Эта команда выполнит все файлы *.tftest.hcl, *.tftest.json, *.tofutest.hcl и *.tofutest.json в текущем каталоге или в каталоге с именем tests. Настроить это поведение можно с помощью приведённых ниже параметров.

resource "local_file" "test" {
  filename = "${path.module}/test.txt"
  content  = "Hello world!"
}

run "test" {
  assert {
    condition     = file(local_file.test.filename) == "Hello world!"
    error_message = "Incorrect content in ${local_file.test.filename}."
  }
}

Приоритет расширений​

Если в каталоге присутствуют файлы .tftest.hcl и .tofutest.hcl с одинаковым базовым именем, OpenTofu отдаст предпочтение файлу .tofutest.hcl и проигнорирует файл .tftest.hcl. Например:

• Если в одном каталоге имеются файлы main.tftest.hcl и main.tofutest.hcl, OpenTofu загрузит только main.tofutest.hcl и проигнорирует main.tftest.hcl.

Это гарантирует, что файлы .tofu всегда имеют приоритет над файлами .tf, если доступны оба типа. Это может быть полезно авторам модулей, которые хотят, чтобы их модули поддерживали и OpenTofu, и Terraform, и хотят создавать для каждого из них отдельные тесты.

.
├── main.tf
├── main.tftest.hcl
├── foo.tf
├── foo.tftest.hcl
├── bar.tf
└── bar.tftest.hcl

.
├── main.tf
├── foo.tf
├── bar.tf
└── tests
     ├── main.tftest.hcl
     ├── foo.tftest.hcl
     └── bar.tftest.hcl

.
├── module1
│    ├── main.tf
│    ├── main.tftest.hcl
│    ├── foo.tf
│    ├── foo.tftest.hcl
│    ├── bar.tf
│    └── bar.tftest.hcl
└── module2
     └── ...

.
├── module1
│    ├── main.tf
│    ├── foo.tf
│    ├── bar.tf
│    └── tests
│         ├── main.tftest.hcl
│         ├── foo.tftest.hcl
│         └── bar.tftest.hcl
└── module2
     └── ...

run "test" {
  assert {
    condition     = file(local_file.test.filename) == "Hello world!"
    error_message = "Incorrect content in ${local_file.test.filename}."
  }
}

resource "local_file" "test" {
  filename = "${path.module}/test.txt"
  content  = "Hello world!"
}

run "test" {
  module {
    source = "./some-module"
  }
}

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "3.0.2"
    }
  }
}

resource "docker_container" "webserver" {
  name  = "nginx-test"
  image = "nginx"
  ports {
    internal = 80
    external = 8080
  }
}

run "http" {
  # Load the test helper instead of the main module:
  module {
    source = "./test-harness"
  }

  # Check if the webserver returned an HTTP 200 status code:
  assert {
    condition     = data.http.test.status_code == 200
    error_message = "Incorrect status code returned: ${data.http.test.status_code}"
  }
}

# Load the main module:
module "main" {
  source = "../"
}

# Fetch the website so the assert can do its job:
data "http" "test" {
  url = "http://localhost:8080"

  # Important! Wait for the main module to finish:
  depends_on = [module.main]
}

# First, set the variable here:
variables {
  name = "OpenTofu"
}

run "basic" {
  assert {
    condition     = output.greeting == "Hello OpenTofu!"
    error_message = "Incorrect greeting: ${output.greeting}"
  }
}

run "override" {
  # Override it for this test case only here:
  variables {
    name = "OpenTofu user"
  }
  assert {
    condition     = output.greeting == "Hello OpenTofu user!"
    error_message = "Incorrect greeting: ${output.greeting}"
  }
}

variable "name" {}

output "greeting" {
  value = "Hello ${var.name}!"
}

run "main" {
  command = plan

  variables {
    instances = -1
  }

  expect_failures = [
    var.instances,
  ]
}

variable "instances" {
  type = number

  validation {
    condition     = var.instances >= 0
    error_message = "The number of instances must be positive or zero"
  }
}

run "test-failure" {
  variables {
    # This healthcheck endpoint won't exist:
    health_endpoint = "/nonexistent"
  }

  expect_failures = [
    # We expect this to fail:
    check.health
  ]
}

variable "health_endpoint" {
  default = "/"
}

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "3.0.2"
    }
  }
}

resource "docker_container" "webserver" {
  name  = ""
  image = "nginx"
  rm    = true

  ports {
    internal = 80
    external = 8080
  }
}

check "health" {
  data "http" "www" {
    url = "http://localhost:8080${var.health_endpoint}"
    depends_on = [docker_container.webserver]
  }

  assert {
    condition = data.http.www.status_code == 200
    error_message = "Invalid status code returned: ${data.http.www.status_code}"
  }
}

Настройка run.command и блок run.plan_options​

По умолчанию tofu test использует tofu apply для создания реальной инфраструктуры. В некоторых случаях, например если реальная инфраструктура очень дорогая или её невозможно использовать для тестирования, может быть полезно запускать только tofu plan. Вы можете использовать настройку command = plan, чтобы выполнить план вместо применения. В следующем примере проверяется, правильно ли переменная передаётся ресурсу docker_image, без фактического применения плана:

run "test" {
  command = plan
  plan_options {
    refresh = false
  }
  variables {
    image_name = "myapp"
  }
  assert {
    condition     = docker_image.build.name == "myapp"
    error_message = "Missing build resource"
  }
}

variable "image_name" {
  default = "app"
}

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "3.0.2"
    }
  }
}

resource "docker_image" "build" {
  name = var.image_name
  build {
    context = "."
  }
}

Независимо от настройки command, вы можете использовать блок plan_options, чтобы задать следующие дополнительные параметры для обоих режимов:

Блок providers​

В некоторых случаях может потребоваться переопределить настройки провайдера при запуске тестов. Вы можете использовать блоки provider вне блока run, чтобы задать дополнительные параметры конфигурации провайдеров, например учётные данные тестовой учётной записи.

provider "aws" {
  // Add additional settings here
}

Эта возможность также позволяет выполнять частично или полностью автономные тесты, если провайдер поддерживает такой режим. В следующем примере показан полностью автономный тест с провайдером AWS и ресурсом бакета S3:

// Configure the AWS provider to run fake credentials and without
// any validations. Not all providers support this, but when they
// do, you can run fully offline tests.
provider "aws" {
  access_key = "foo"
  secret_key = "bar"

  skip_credentials_validation = true
  skip_region_validation      = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true
}

run "test" {
  // Run in plan mode to skip applying:
  command = plan

  // Disable the refresh to prevent reaching out to the AWS API:
  plan_options {
    refresh = false
  }

  // Test if the bucket name is correctly passed to the aws_s3_bucket
  // resource:
  variables {
    bucket_name = "test"
  }
  assert {
    condition     = aws_s3_bucket.test.bucket == "test"
    error_message = "Incorrect bucket name: ${aws_s3_bucket.test.bucket}"
  }
}

variable "bucket_name" {}

provider "aws" {
  region = "us-east-2"
}

resource "aws_s3_bucket" "test" {
  bucket = var.bucket_name
}

Псевдонимы провайдеров​

Помимо переопределения провайдеров, вы можете назначать провайдерам псевдонимы, чтобы заменять их другими провайдерами внутри блока run. Это полезно, если нужно использовать две конфигурации провайдера в одном файле теста и переключаться между ними.

В приведённом ниже примере тестовый случай sockettest загружает конфигурацию провайдера Docker, отличную от используемой в остальной части файла.

# This is the default "docker" provider for this file:
provider "docker" {
  host = "tcp://0.0.0.0:2376"
}

# This will be the override:
provider "docker" {
  alias = "unixsocket"
  host = "unix:///var/run/docker.sock"
}

run "sockettest" {
  # Replace the "docker" provider for this test case only:
  providers = {
    docker = docker.unixsocket
  }

  assert {
    condition     = docker_image.build.name == "myapp"
    error_message = "Missing build resource"
  }
}

// Add other tests with the original provider here.

terraform {
  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "3.0.2"
    }
  }
}

resource "docker_image" "build" {
  name = "myapp"
  build {
    context = "."
  }
}

Блоки mock_provider​

Блок mock_provider позволяет заменить конфигурацию провайдера имитационной конфигурацией. В этом случае создание и получение ресурсов и источников данных провайдера пропускается. Вместо этого OpenTofu автоматически генерирует все вычисляемые атрибуты и блоки, которые будут использоваться в тестах.

Имитационные провайдеры также поддерживают поле alias, а также блоки mock_resource и mock_data. В некоторых случаях вместо автоматически сгенерированных значений могут потребоваться значения по умолчанию. Для этого передайте их в поле defaults блоков mock_resource или mock_data.

Кроме того, можно использовать блоки override_resource и override_data для переопределения ресурсов или источников данных в области действия одного провайдера. Подробнее о переопределении см. в следующем разделе.

В приведённом ниже примере проверяется, правильно ли имя бакета передаётся ресурсу, без его фактического создания:

// All resources and data sources provided by `aws.mock` provider
// will be mocked. Their values will be automatically generated.
mock_provider "aws" {
  alias = "mock"
}

// The same goes for `local` provider. Also, every `local_file`
// data source will have its `content` set to `test`.
mock_provider "local" {
  mock_data "local_file" {
    defaults = {
      content = "test"
    }
  }
}

// Test if the bucket name is correctly passed to the aws_s3_bucket
// resource from the local file.
run "test" {
  // Use `aws.mock` provider for this test run only.
  providers = {
    aws = aws.mock
  }

  assert {
    condition     = aws_s3_bucket.test.bucket == "test"
    error_message = "Incorrect bucket name: ${aws_s3_bucket.test.bucket}"
  }
}

data "local_file" "bucket_name" {
  filename = "bucket_name.txt"
}

provider "aws" {
  region = "us-east-2"
}

resource "aws_s3_bucket" "test" {
  bucket = data.local_file.bucket_name.content
}

Блоки override_resource и override_data​

В некоторых случаях может потребоваться протестировать инфраструктуру с переопределёнными ресурсами или источниками данных. Вы можете использовать блоки override_resource или override_data, чтобы пропустить создание и получение этих ресурсов или источников данных с помощью реального провайдера. Вместо этого OpenTofu автоматически генерирует все вычисляемые атрибуты и блоки, которые будут использоваться в тестах.

Эти блоки состоят из следующих элементов:

Блоки override_resource или override_data можно использовать для всего файла тестов или внутри отдельного блока run. Если оба блока заданы для одного и того же target, приоритет имеет последний.

В приведённом ниже примере проверяется, правильно ли имя бакета передаётся ресурсу, без его фактического создания:

// This data source will not be called for any run
// in this `.tftest.hcl` file. Instead, `values` object
// will be used to populate `content` attribute. Other
// attributes and blocks will be automatically generated.
override_data {
  target = data.local_file.bucket_name
  values = {
    content = "test"
  }
}

// Test if the bucket name is correctly passed to the aws_s3_bucket
// resource from the local file.
run "test" {
  // S3 bucket will not be created in AWS for this run,
  // but it's available to use in both tests and configuration.
  override_resource {
    target = aws_s3_bucket.test
  }

  assert {
    condition     = aws_s3_bucket.test.bucket == "test"
    error_message = "Incorrect bucket name: ${aws_s3_bucket.test.bucket}"
  }
}

data "local_file" "bucket_name" {
  filename = "bucket_name.txt"
}

provider "aws" {
  region = "us-east-2"
}

resource "aws_s3_bucket" "test" {
  bucket = data.local_file.bucket_name.content
}

Автоматически сгенерированные значения​

Для имитации ресурсов и источников данных OpenTofu требуется автоматически генерировать вычисляемые атрибуты, не вызывая соответствующие провайдеры. При генерации этих значений OpenTofu не может использовать пользовательскую логику провайдера, поэтому применяет простые правила, основанные на типе значения:

Блок override_module​

В некоторых случаях может потребоваться протестировать инфраструктуру с переопределёнными вызовами модулей. Вы можете использовать блок override_module, чтобы игнорировать всю конфигурацию, предоставленную вызываемым модулем. В этом случае OpenTofu будет использовать пользовательские значения, заданные в блоке override_module, в качестве выходных данных модуля.

Блок состоит из следующих элементов:

Блок override_module можно использовать для всего файла тестов или внутри отдельного блока run. Если оба блока заданы для одного и того же target, приоритет имеет последний.

В приведённом ниже примере проверяется, правильно ли имя бакета передаётся из модуля, без его фактического вызова:

// All the module configuration will be ignored for this
// module call. Instead, the `outputs` object will be used
// to populate module outputs.
override_module {
  target = module.bucket_meta
  outputs = {
    name = "test"
    tags = {
      Environment = "Test Env"
    }
  }
}

// Test if the bucket name is correctly passed to the aws_s3_bucket
// resource from the module call.
run "test" {
  // S3 bucket will not be created in AWS for this run,
  // but it's available to use in both tests and configuration.
  override_resource {
    target = aws_s3_bucket.test
  }

  assert {
    condition     = aws_s3_bucket.test.bucket == "test"
    error_message = "Incorrect bucket name: ${aws_s3_bucket.test.bucket}"
  }

  assert {
    condition     = aws_s3_bucket.test.tags["Environment"] == "Test Env"
    error_message = "Incorrect `Environment` tag: ${aws_s3_bucket.test.tags["Environment"]}"
  }
}

module "bucket_meta" {
  source = "./bucket_meta"
}

provider "aws" {
  region = "us-east-2"
}

resource "aws_s3_bucket" "test" {
  bucket = module.bucket_meta.name
  tags   = module.bucket_meta.tags
}

data "local_file" "bucket_name" {
  filename = "bucket_name.txt"
}

output "name" {
  value = data.local_file.bucket_name.content
}

output "tags" {
  value = {
    Environment = "Dev"
  }
}