# atmos terraform test

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

## Usage

Execute the `terraform test` command like this:

```shell
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.

:::info 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`. Atmos does not generate a backend file for `test`, so a component without `backend_type` can run tests even when `auto_generate_backend_file` is enabled. Existing backend files are preserved. The test execution itself is handled by native Terraform.
:::

## Examples

### Run Tests

```shell
# Run all tests
atmos terraform test vpc -s dev
```

### Run Specific Test Files

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

### Verbose Output

```shell
# 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:

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

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.

Then run the component test against the fixture stack:

```shell
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.
  ```shell
  atmos terraform test vpc -s dev --skip-init
  ```
- **`--dry-run` (optional)** — Show what would be executed without actually running the command.
  ```shell
  atmos terraform test vpc -s dev --dry-run
  ```

### Processing flags

`--help` shows command-specific flags. Use `atmos terraform test --help=all` to
include inherited flags such as `--skip`, `--process-functions`, and
`--process-templates`.

```shell
atmos terraform test vpc -s dev --skip=secret
atmos terraform test vpc -s dev --process-functions=false
```

## Variables and generated files

Atmos passes the stack's resolved component `vars` in a generated
`<stack>-<component>.terraform.tfvars.json` file. Those values override module
input-variable defaults. Tests that need different inputs can declare them in
the test's `variables` blocks, following native Terraform test precedence, or
use a dedicated Atmos test stack. `--process-functions=false` disables YAML
function evaluation; it does not disable stack variable injection.

Atmos also passes `test.vars` in a separate generated test varfile and removes
that file after a successful test invocation. The component varfile,
`.terraform` initialization directory, and Terraform dependency lock file remain
in the component directory. Test execution does not provide an ephemeral working
directory or remove pre-existing initialization files.

## 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.

## Try it out

### terraform-tests

Copy the example into a new directory and make it your own:

```shell
atmos init examples/terraform-tests
cd terraform-tests
```

Requires Terraform, Docker or Podman, and network access. The test provisions its local emulator and fixture infrastructure as described in the README.

```shell
atmos terraform test app -s fixtures
```

- [Installation guide](/install)
- [Explore the example](/examples/terraform-tests)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)

## Related Commands

- [`atmos terraform plan`](/cli/commands/terraform/plan) - Generate execution plan
- [`atmos terraform apply`](/cli/commands/terraform/apply) - Apply changes
- [`atmos terraform init`](/cli/commands/terraform/init) - Initialize working directory