Skip to main content
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: 
test "bucket_uses_env_name" {
  inputs = { env = "staging" }

  assert {
    resource   = "aws_s3_bucket_v2.assets"
    action     = "create"
    attributes = { bucket = "staging-assets" }
  }
}
Run: 
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: 
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: 
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

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

- 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