terraform test 명령

terraform test 명령

terraform test 명령은 Terraform 테스트 파일을 불러와서 실행하는 명령이에요. 모듈 작성자가 공유 모듈을 검증하고 테스트할 수 있게 도와주며, 루트 모듈 검증에도 사용할 수 있어요.

출처: 문서

본문

소개 (Introduction)

terraform test 명령과 테스트 파일 구문은 모듈 작성자가 공유 모듈을 검증하고 테스트하는 데 도움을 줘요. 루트 모듈을 검증할 때도 terraform test 명령을 사용할 수 있어요.

사용법 (Usage)

terraform test [options]

이 명령은 현재 디렉터리와 지정된 테스트 디렉터리에서 Terraform 테스트 파일을 검색하고 지정된 테스트를 실행해요. 기본적으로 테스트 파일이 들어 있는 디렉터리는 tests로 이름이 정해져 있어요. 테스트 파일에 대한 자세한 내용은 Tests 문서를 참고해 주세요.

그런 다음 Terraform은 테스트 파일의 사양에 따라 일련의 terraform plan 또는 apply 명령을 실행하고, 테스트 파일의 사양에 따라 관련 plan 및 state 파일도 검증해요.

경고: Terraform test 명령은 비용이 들 수 있는 실제 인프라를 생성할 수 있어요. 생성된 인프라가 파괴되도록 보장하는 모범 사례는 Terraform Test Cleanup 섹션을 참고해 주세요.

일반 옵션 (General Options)

다음 옵션들이 terraform test 명령에 적용돼요.

• -cloud-run=<module source>: 이 테스트 실행이 지정된 Terraform 프라이빗 레지스트리 모듈 안에서 HCP Terraform에서 원격으로 실행됨.
• -filter=testfile: terraform test 작업을 지정한 테스트 파일로 제한함.
• -json: 테스트 결과에 대한 기계가 읽을 수 있는 JSON 출력을 표시함.
• -junit-xml=<output file path>: JUnit XML 형식의 테스트 보고서를 지정한 파일에 저장함. 현재는 -cloud-run 옵션을 사용한 원격 테스트 실행과 호환되지 않아요. 파일 경로는 상대 경로 또는 절대 경로여야 해요.
• -test-directory=<relative directory>: Terraform이 테스트 파일을 찾는 디렉터리를 재정의함. Terraform은 항상 메인 구성 디렉터리 안의 테스트 파일을 로드한다는 점을 주의해 주세요. 기본 테스트 디렉터리는 tests예요.
• -verbose: 각 run 블록의 command 속성에 따라 테스트 파일 안의 각 run 블록에 대한 plan 또는 state를 출력함.
• -parallelism=<n>: 단일 테스트 실행 안에서 병렬로 실행할 plan/apply 작업 수를 지정함. 기본값은 10이에요.

상태 관리 (State Management)

각 Terraform 테스트 파일은 실행하면서 필요한 모든 Terraform 상태를 메모리에 유지하며, 빈 상태에서 시작해요. 이 상태는 테스트 중인 구성의 기존 상태와 완전히 분리되어 있으므로, 라이브 인프라에 영향을 주지 않고 안전하게 Terraform test 명령을 실행할 수 있어요.

Terraform 테스트 정리 (Terraform Test Cleanup)

terraform test 명령은 실제 인프라를 생성해요. Terraform이 각 테스트 파일을 완전히 실행하면 남은 인프라를 파괴하려고 시도해요. 그렇게 할 수 없으면 Terraform은 생성했지만 파괴하지 못한 리소스 목록을 보고해요.

Terraform이 만든 인프라를 제거하는지 출력을 주의 깊게 모니터링하고, 그렇지 않으면 수동으로 정리해야 해요. 대상 프로바이더에 전용 테스트 계정을 만들어서 우연히 생성된 비용이 큰 리소스가 남지 않도록 정기적으로 안전하게 비워 둘 것을 권장해요.

Terraform은 자동 정리를 수행할 수 없는 이유를 설명하는 진단 정보도 제공해요. 향후 정리 작업이 성공하도록 이 진단을 검토해야 해요.

HCP Terraform에서 실행 (HCP Terraform execution)

-cloud-run 옵션을 사용해서 테스트를 HCP Terraform에서 원격으로 실행할 수 있어요.

-cloud-run 옵션은 프라이빗 레지스트리 모듈 소스를 받아들여요. 이 옵션은 테스트 실행을 HCP Terraform 사용자 인터페이스 안의 지정한 프라이빗 모듈과 연결해요.

공개 Terraform 레지스트리가 아닌 프라이빗 레지스트리의 모듈을 제공해야 해요.

이 옵션을 사용하기 전에 terraform login을 실행해야 하고, hostname 인자가 대상 모듈의 프라이빗 레지스트리 호스트 이름과 일치하는지 확인해야 해요.

예시: 테스트 디렉터리 구조와 명령 (Example: Test Directory Structure and Commands)

다음 디렉터리 구조는 테스트와 설정(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

프로젝트의 루트 디렉터리에는 main.tf, outputs.tf, terraform.tf, variables.tf 같은 일반적인 Terraform 구성 파일들이 있어요. 테스트 파일인 validations.tftest.hcl과 outputs.tftest.hcl은 기본 테스트 디렉터리인 tests 안에 있어요.

또한 테스트용 설정 모듈이 testing 디렉터리 안에 존재해요.

테스트를 실행하려면 terraform plan이나 terraform apply를 실행하는 것처럼 루트 구성 디렉터리에서 terraform test를 실행해야 해요. 실제 테스트 파일이 중첩된 tests 디렉터리에 있음에도 Terraform은 메인 구성 디렉터리에서 실행돼요.

특정 테스트 파일은 -filter 옵션으로 실행할 수 있어요.

Linux, Mac OS, 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

대체 테스트 디렉터리 (Alternate Test Directories)

위 예시에서 테스트는 기본 테스트 디렉터리인 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이 tests 대신 testing 디렉터리에서 테스트를 로드하도록 지시해요.

테스트 디렉터리는 메인 구성 디렉터리 아래에 있어야 하지만, 여러 번 중첩될 수 있어요.

참고: 루트 구성 디렉터리 안의 테스트 파일은 -test-directory 값과 무관하게 항상 로드돼요.

기본 테스트 디렉터리를 변경하는 것은 권장하지 않아요. 사용자 정의 옵션은 terraform test 명령이 출시되기 전에 구성에 tests 하위 모듈을 포함했던 구성 작성자를 위해 제공된 거예요. 일반적으로 기본 테스트 디렉터리인 tests를 항상 사용해야 해요.

예시: 테스트 출력 형식 옵션 (Example: Test Output Format Options)

아래는 로컬 변수 true와 false의 값에 대해 단언(assertion)하는 Terraform 테스트의 예시예요. 두 개의 테스트 파일이 있는데, 하나는 통과하는 테스트를, 하나는 실패하는 테스트를 포함해요.

# main.tf
locals {
  true  = "true"
  false = "true" # incorrect, should be "false"!
}

example_1.tftest.hcl의 local.true == "true" 단언은 통과해요.

# example_1.tftest.hcl
run "true_is_true" {
  assert {
    condition     = local.true == "true"
    error_message = "local.true did not match expected value"
  }
}

example_2.tftest.hcl의 local.false == "false" 단언은 실패해요.

# example_2.tftest.hcl
run "false_is_false" {
  assert {
    condition     = local.false == "false"
    error_message = "local.false did not match expected value"
  }
}

JUnit XML 형식으로 파일에 저장된 테스트 출력 (Test output in JUnit XML format, saved to file)

아래는 위 예시 파일을 사용한 terraform test -junit-xml=./output.xml 명령의 출력이에요. 테스트 출력은:

• 기본적인 사람이 읽기 좋은 형식으로 터미널에 인쇄됨.
• 플래그로 지정한 파일에 JUnit XML 형식으로도 저장됨.

결과로 생성되는 output.xml 파일의 내용은 다음과 같아요.

<?xml version="1.0" encoding="UTF-8"?><testsuites>
  <testsuite name="example_1.tftest.hcl" tests="1" skipped="0" failures="0" errors="0">
    <testcase name="true_is_true" classname="example_1.tftest.hcl" time="0.002295" timestamp="2025-01-13T19:23:16Z"></testcase>
  </testsuite>
  <testsuite name="example_2.tftest.hcl" tests="1" skipped="0" failures="1" errors="0">
    <testcase name="false_is_false" classname="example_2.tftest.hcl" time="0.001468" timestamp="2025-01-13T19:23:16Z">
      <failure message="local.false did not match expected value"><![CDATA[
Error: Test assertion failed

  on example_2.tftest.hcl line 3, in run "false_is_false":
   3:     condition     = local.false == "false"
    ├────────────────
    │ local.false is "true"

local.false did not match expected value
]]></failure>
    </testcase>
  </testsuite>
</testsuites>

run 블록에 실패한 단언이 있으면 <testcase> 요소는 오류 메시지와 추가 세부 사항을 포함하는 <failure> 요소를 포함해요.

<testcase> 요소는 테스트가 건너뛰어진 이유에 대한 세부 사항을 포함하는 <skipped> 요소를 포함할 수도 있어요. 이는 오류로 인해 나머지 run 블록이 건너뛰어진 경우나 명령이 중단된 경우일 수 있어요.

Terraform 테스트 명령 개념을 JUnit XML 형식으로 매핑 (Mapping Terraform test command concepts to JUnit XML format)

-junit-xml을 사용할 때 생성되는 테스트 보고서는 다음 표에 따라 Terraform 테스트 명령 개념을 JUnit XML 형식으로 매핑해요.

Terraform 테스트 개념	JUnit XML 출력의 요소
테스트 디렉터리	<testsuites>
테스트 파일	<testsuite>
Run 블록	<testcase>
Run 블록 단언	없음; 세부 사항은 실패 시에만 포함됨
테스트 실패	<failure>
테스트 건너뜀	<skipped>
오류로 테스트 중단	<error>
처리되지 않은 경고 또는 오류	<system-err>

더 알아보기 (Learn more)

• Terraform 테스트 파일 구문 문서 (Tests)
• terraform plan / apply 명령
• Running Terraform in Automation 튜토리얼
• Terraform CLI 명령 목록