Skip to main content

atmos terraform test

Use this command to run Terraform tests for an Atmos component, validating the component's configuration and behavior.

atmos terraform test --help

Usage​

Execute the terraform test command like this:

atmos terraform test <component> -s <stack> [options]

This command runs tests for Terraform modules. Tests are written in .tftest.hcl or .tftest.json files and can validate that your infrastructure code works as expected.

Atmos Behavior

Atmos provides standard setup for this command including automatic terraform init, workspace selection, a generated component varfile for module inputs, and an optional generated test varfile from test.vars. The test execution itself is handled by native Terraform.

Examples​

Run Tests​

# Run all tests
atmos terraform test vpc -s dev

Run Specific Test Files​

# Run specific test file
atmos terraform test vpc -s dev -filter=tests/vpc_test.tftest.hcl

Verbose Output​

# Run with verbose output
atmos terraform test vpc -s dev -verbose

Use Fixture Components with Hooks​

Use component hooks when a Terraform test needs fixture infrastructure that the component under test should not provision itself. The tested component owns the fixture lifecycle, and Atmos runs it around terraform test.

For example, the terraform-tests example has an app component that requires a VPC but leaves VPC creation to a fixture component in a fixtures stack. The catalog declares the vpc fixture and the app-owned ordered hooks:

examples/terraform-tests/stacks/catalog/app.yaml

The deployable fixtures stack makes both components real for the test run:

examples/terraform-tests/stacks/deploy/fixtures/app.yaml

The app's Terraform test then looks up the VPC during the test instead of provisioning it. The fixtures stack uses test.vars with !terraform.state to pass the fixture VPC ID into Terraform test after the hook applies the VPC. The test file declares only the test-scope variables it references, so other test files can ignore those values without Terraform undeclared-variable warnings.

examples/terraform-tests/components/terraform/app/tests/app.tftest.hcl

Then run the component test against the fixture stack:

atmos terraform test app -s fixtures

The ordered kind: steps hooks start the emulator, apply the VPC fixture, execute the app test, destroy the fixture, and stop the emulator. The app can look up the VPC during Terraform test with a data source, proving it uses the fixture without provisioning the VPC itself.

Arguments​

component (required)

Atmos component name.

Flags​

--stack / -s (required)

Atmos stack name where the component is defined.

--skip-init (optional)

Skip running terraform init before executing the command.

atmos terraform test vpc -s dev --skip-init
--dry-run (optional)

Show what would be executed without actually running the command.

atmos terraform test vpc -s dev --dry-run

Native Terraform Flags​

This command supports native terraform test flags such as -filter to run specific test files, -verbose for detailed output, -json for JSON output.