> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Infrastructure

> Write .test.iac files and run ubx test.

ubx has a built-in testing framework. Test files use `.test.iac` extension and run at compile time — no cloud resources required.

## Quick Start

Create `tests/s3.test.iac`:

```hcl theme={null}
test "bucket_uses_env_name" {
  inputs = { env = "staging" }

  assert {
    resource   = "aws_s3_bucket_v2.assets"
    action     = "create"
    attributes = { bucket = "staging-assets" }
  }
}
```

Run:

```bash theme={null}
ubx test
# === RUN   bucket_uses_env_name
# --- PASS: bucket_uses_env_name (0.00s)
# Tests: 1 passed, 0 failed, 1 total
```

## Two Test Types

### Plan Assertions

Compile the project with given inputs and verify the generated TypeScript:

```hcl theme={null}
test "prod_uses_large_instance" {
  inputs = { env = "prod" }

  assert {
    resource   = "aws_rds_instance.db"
    action     = "create"
    attributes = { instance_class = "db.r6g.xlarge" }
  }
}

test "staging_uses_small_instance" {
  inputs = { env = "staging" }

  assert {
    resource   = "aws_rds_instance.db"
    action     = "create"
    attributes = { instance_class = "db.t3.micro" }
  }
}
```

### Error Assertions

Compile inline source and assert a specific error:

```hcl theme={null}
test "missing_engine_caught" {
  source = """
    unit "aws_rds_instance" "db" {
      username = "admin"
    }
  """
  expect_error = "required attribute \"engine\" is missing"
}

test "undefined_ref_caught" {
  source       = "unit \"aws_s3_bucket_v2\" \"b\" { bucket = ~unit.missing.thing.id }"
  expect_error = "missing"
}
```

## Test Organisation

```
project/
  stack.iac
  tests/
    s3.test.iac
    rds.test.iac
    policy.test.iac
```

```bash theme={null}
ubx test                    # all tests
ubx test tests/s3.test.iac  # specific file
ubx test tests/             # specific directory
ubx test --verbose          # show assertion detail for passing tests
```

## CI Integration

```yaml theme={null}
- name: Run ubx tests
  run: ubx test
```

Exit code 0 if all pass, 1 if any fail.

## What to Test

* Environment-specific attribute values (staging vs prod instance sizes)
* Conditional resource creation (`when` modifiers)
* Policy violations are caught
* Required fields are missing → correct error
* Cross-resource references are correct