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

# ubx test

> Run .test.iac test files — compiler-level tests without cloud resources.

`ubx test` discovers and runs `*.test.iac` files. No cloud resources, no credentials required.

## Usage

```bash theme={null}
ubx test [path] [flags]
```

## Examples

```bash theme={null}
ubx test
ubx test tests/s3.test.iac
ubx test tests/
ubx test --verbose
```

## Flags

| Flag        | Description                              |
| ----------- | ---------------------------------------- |
| `--verbose` | Show assertion details for passing tests |

## Test File Syntax

### Plan Assertion Tests

```hcl theme={null}
test "bucket_created" {
  assert {
    resource   = "aws_s3_bucket_v2.assets"
    action     = "create"
    attributes = { bucket = "my-assets" }
  }
}

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

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

### Error Assertion Tests

```hcl theme={null}
test "undefined_ref_caught" {
  source       = "unit \"aws_s3_bucket_v2\" \"assets\" { bucket = ~unit.missing.thing.attr }"
  expect_error = "missing"
}

test "required_field_missing" {
  source = """
    unit "aws_rds_instance" "db" {
      username = "admin"
    }
  """
  expect_error = "required attribute \"engine\" is missing"
}
```

## Test Block Fields

| Field          | Description                                    |
| -------------- | ---------------------------------------------- |
| `inputs`       | Map of input values (`{ env = "staging" }`)    |
| `assert`       | One or more assertion sub-blocks               |
| `source`       | Inline `.iac` source (overrides project files) |
| `expect_error` | Expected error substring                       |

### Assert Fields

| Field        | Description                                       |
| ------------ | ------------------------------------------------- |
| `resource`   | `"type.name"` matching the unit block             |
| `action`     | `"create"`, `"update"`, `"delete"`, `"no-change"` |
| `attributes` | Map of expected key-value pairs                   |

## Output

```
=== RUN   bucket_name_uses_env
--- PASS: bucket_name_uses_env (0.00s)

Tests: 1 passed, 0 failed, 1 total
```

Failing test:

```
=== RUN   wrong_bucket_name
--- FAIL: wrong_bucket_name (0.00s)
    attribute "bucket" on resource "aws_s3_bucket_v2.assets":
        expected: "wrong-name"
        got:      "my-assets"

Tests: 0 passed, 1 failed, 1 total
```

## Exit Codes

| Code | Meaning                |
| ---- | ---------------------- |
| `0`  | All tests pass         |
| `1`  | One or more tests fail |