Команда: test

Команда tofu test позволяет тестировать конфигурацию OpenTofu путем создания реальной инфраструктуры и проверки выполнения требуемых условий (утверждений / assertions). После завершения теста 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, и хотят создать разные тесты для каждого из них.

То же правило применяется к тестовым файлам на основе JSON:

• если в одном и том же каталоге существуют и main.tftest.json, и main.tofutest.json, OpenTofu загрузит только main.tofutest.json и проигнорирует main.tftest.json.

Параметры​

• -test-directory=path Задать тестовый каталог (по умолчанию: "tests"). При запуске tofu test OpenTofu будет искать файлы тестов в указанном каталоге, а также в текущем каталоге. Путь должен быть относительным к текущему рабочему каталогу.
• -filter=testfile Указать отдельный тестовый файл для запуска. Используйте этот параметр несколько раз, чтобы указать более одного файла. Путь должен быть относительным к текущему рабочему каталогу.

tofu test -test-directory=extra-tests -filter=extra-tests/a.tftest.hcl

• -var 'foo=bar' Задать входную переменную корневого модуля. Укажите этот параметр несколько раз, чтобы добавить более одной переменной.
• -var-file=filename Задать несколько переменных из указанного файла. Помимо этого файла, OpenTofu автоматически загружает terraform.tfvars и *.auto.tfvars. Используйте этот параметр несколько раз, чтобы указать более одного файла.
• -json Изменить формат вывода на JSON.
• -no-color Отключить цветной вывод в выводе команды.
• -verbose Выводить план или состояние для каждого блока test run по мере его выполнения.

Структура каталогов​

Команда tofu test поддерживает две структуры каталогов: плоскую или вложенную:

.
├── 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
     └── ...

Структура файлов *.tftest.hcl / *.tofutest.hcl​

Язык тестирования OpenTofu похож на основной язык OpenTofu и использует ту же блочную структуру.

Тестовый файл состоит из:

• Блоки run: определяют ваши тесты.
• Блок variables (необязательный): определяет переменные для всех тестов в текущем файле.
• Блоки provider (необязательные): определяют провайдеров, используемых для тестов.
• Блоки mock_provider (необязательные): определяют имитируемых (mock) провайдеров.
• Блоки override_resource (необязательные): определяют переопределяемые ресурсы.
• Блоки override_data (необязательные): определяют переопределяемые источники данных.
• Блоки override_module (необязательные): определяют переопределяемые вызовы модулей.

Блок run​

Блок run содержит один тестовый сценарий, который запускает либо tofu apply, либо tofu plan, а затем вычисляет все блоки assert. После завершения теста он использует tofu destroy для удаления временно созданных ресурсов.

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

Блок run.assert​

Вы можете указать блоки assert внутри блока run для проверки состояния вашей инфраструктуры после завершения операции apply или plan. Теоретического ограничения на количество определяемых блоков нет.

Каждый блок требует наличия следующих двух атрибутов:

1. condition — это условие OpenTofu, которое должно возвращать true для успешного прохождения теста или false для сбоя теста. Условие обязано ссылаться на ресурс, источник данных, переменную, выходное значение (output) или модуль из основного кода, иначе OpenTofu откажется запускать тест.
2. error_message — это строка, объясняющая причину сбоя при провале теста.

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!"
}

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

Блок run.module​

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

Вы можете использовать блок module для переопределения основного модуля, который загружает tofu test. Это дает возможность создавать дополнительные ресурсы или источники данных, которые затем можно использовать в условиях assert.

Его синтаксис аналогичен загрузке модулей в обычном коде OpenTofu:

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

Блок module имеет следующие два атрибута:

• Атрибут source указывает на каталог загружаемого модуля или любой другой источник модуля.
• version задает версию модуля, которую вы хотите использовать.

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]
}

Блоки variables и run.variables​

Тестируемый код (например, main.tf) часто содержит блоки переменных, которые необходимо заполнить из вашего тестового сценария. Вы можете передать переменные в тестовый запуск с помощью любого из следующих способов:

OpenTofu оценивает переменные в указанном выше порядке, поэтому вы можете использовать это для переопределения ранее заданных переменных. Например:

# 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}!"
}

Выходные значения (outputs) блока run для переменных​

Также можно использовать выходные значения модулей ранее выполненного блока run для установки значений variables другого блока run.

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

run "setup" {
  module {
    source = "./setup"
  }
}

run "test" {
  variables {
    filename_from_setup = run.setup.filename
  }

  # more assertions to run
}

output "filename" {
  value = "some_file.txt"
}

Список run.expect_failures​

Вы можете использовать expect_failures внутри блока run для тестирования пользовательских условий, таких как предусловия (preconditions) и постусловия (postconditions), или правил валидации входных переменных.

Например, приведенный ниже тестовый сценарий проверяет, завершается ли валидация входной переменной instances ошибкой при значении в виде отрицательного числа:

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"
  }
}

В приведенном ниже примере проверяется, завершается ли некорректно настроенная проверка работоспособности (healthcheck) с ошибкой. Это гарантирует, что проверка работоспособности не возвращает всегда успешный результат, даже когда она выполняется для неверной конечной точки.

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 = "."
  }
}

Ссылки на выходные данные модуля run и переменные в блоках provider​

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

variables {
  region = "us-west-2"
}

provider "aws" {
  region = var.region
  access_key = run.setup.access_key
  secret_key = run.setup.secret_key
}

run "setup" {
  # `mod` module has outputs access_key and secret_key
  module {
    source = "./mod"
  }

# Actual run block behavior, such as asserts, are skipped for simplicity

}

Блоки mock_provider​

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

Для мок-провайдеров поддерживаются поля alias и for_each. Однако атрибут for_each поддерживается только тогда, когда также используется 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"
  }
}