ci(runners): add terraform test for pool module type safety (#5157)

## Problem

`terraform validate` cannot detect conditional type mismatches like the
one introduced in #4875:

```hcl
role = var.iam_overrides["override_runner_role"] ? { arn = var.iam_overrides["runner_role_arn"] } : aws_iam_role.runner[0]
```

This passes `terraform validate` but fails at plan time because the two
branches produce objects with different attributes (1 vs 16).

## Solution

Add a `terraform test` file (`modules/runners/tests/pool.tftest.hcl`)
that uses mock providers to run a full plan of the runners module with
pool enabled. This catches type errors that `validate` misses, without
requiring AWS credentials.

Also adds a `terraform_test` job to the existing CI workflow. The job
uses Terraform `latest` (requires 1.7+ for `mock_provider` / `mock_data`
support) and runs `terraform test` on modules that have test files.

### Verified locally

With the buggy code (before #5156):
```
Error: Inconsistent conditional result types
  on pool.tf line 54, in module "pool":
  The true and false result expressions must have consistent types.
```

With the fix (#5156 applied):
```
Success! 1 passed, 0 failed.
```

## Future work

The `terraform_test` job matrix can be expanded as more modules add
`.tftest.hcl` files. This is a starting point to catch the class of bugs
that `validate` cannot.

---------

Signed-off-by: Brend Smits <brend.smits@philips.com>
Co-authored-by: Niek Palm <npalm@users.noreply.github.com>
Co-authored-by: Ederson Brilhante <contato@edersonbrilhante.com.br>

Author: 3 people

.github/workflows/terraform.yml

@@ -206,3 +206,30 @@ jobs:
         run: |
           tflint --init -c ${GITHUB_WORKSPACE}/.tflint.hcl --chdir "examples/${EXAMPLE_NAME}"
           tflint -f compact -c ${GITHUB_WORKSPACE}/.tflint.hcl --var-file ${GITHUB_WORKSPACE}/.github/lint/tflint.tfvars --chdir "examples/${EXAMPLE_NAME}"
+
+  terraform_test:
+    name: Terraform test
+    strategy:
+      fail-fast: false
+      matrix:
+        module:
+          - modules/runners
+    defaults:
+      run:
+        working-directory: ${{ matrix.module }}
+    runs-on: ubuntu-latest
+    container:
+      image: hashicorp/terraform@sha256:1d10ec4073f4ddbdf34a28540a3b9250852ab500cb1c53f68c8bd17d82f474d8 # 1.14
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@f808768d1510423e83855289c910610ca9b43176 # v2.17.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - name: terraform init
+        run: terraform init -backend=false -input=false
+      - name: terraform test
+        run: terraform test -test-directory=tests

modules/runners/tests/README.md

@@ -0,0 +1,72 @@
+# Terraform Tests
+
+This directory contains [Terraform test files](https://developer.hashicorp.com/terraform/language/tests) (`.tftest.hcl`) for the runners module.
+
+## Why `terraform test` instead of `terraform validate`?
+
+`terraform validate` only checks syntax and basic type correctness of the configuration. It **cannot** detect:
+
+- Conditional expressions with inconsistent result types (e.g., one branch returns an object with 1 attribute, the other returns 16)
+- Runtime type mismatches that only surface during `plan`
+- Invalid cross-module references that depend on resource attribute shapes
+
+`terraform test` with `mock_provider` runs a full plan without needing real cloud credentials, catching these classes of bugs in CI.
+
+## Requirements
+
+- Terraform >= 1.7 (for `mock_provider` and `mock_data` support)
+- No AWS credentials required — all providers are mocked
+
+## Running locally
+
+```bash
+cd modules/runners
+terraform test -test-directory=tests
+```
+
+Expected output:
+
+```
+tests/pool.tftest.hcl... in progress
+  run "plan_with_pool_enabled"... pass
+tests/pool.tftest.hcl... pass
+
+Success! 1 passed, 0 failed.
+```
+
+## Writing new tests
+
+1. Create a `.tftest.hcl` file in this directory
+2. Use `mock_provider "aws" {}` to avoid needing credentials
+3. Use `mock_data` blocks to provide realistic values for data sources that perform validation (e.g., `aws_iam_policy_document` validates JSON)
+4. Set all required variables in a `variables {}` block
+5. Use `run` blocks with `command = plan` and `assert` conditions
+
+### Example template
+
+```hcl
+mock_provider "aws" {
+  mock_data "aws_iam_policy_document" {
+    defaults = {
+      json = "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"lambda.amazonaws.com\"},\"Action\":\"sts:AssumeRole\"}]}"
+    }
+  }
+}
+
+variables {
+  # ... required variables ...
+}
+
+run "descriptive_test_name" {
+  command = plan
+
+  assert {
+    condition     = <expression>
+    error_message = "Explanation of what failed"
+  }
+}
+```
+
+## CI integration
+
+These tests run automatically in the `terraform_test` job of `.github/workflows/terraform.yml` on every PR that touches `*.tf` or `*.hcl` files.

modules/runners/tests/pool.tftest.hcl

@@ -0,0 +1,60 @@
+mock_provider "aws" {
+  mock_data "aws_iam_policy_document" {
+    defaults = {
+      json = "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"lambda.amazonaws.com\"},\"Action\":\"sts:AssumeRole\"}]}"
+    }
+  }
+}
+
+variables {
+  aws_region = "eu-west-1"
+  vpc_id     = "vpc-12345678"
+  subnet_ids = ["subnet-12345678"]
+
+  instance_types = ["m5.large"]
+
+  s3_runner_binaries = {
+    arn = "arn:aws:s3:::my-bucket"
+    id  = "my-bucket"
+    key = "runners/linux/actions-runner.tar.gz"
+  }
+
+  sqs_build_queue = {
+    arn = "arn:aws:sqs:eu-west-1:123456789012:build-queue"
+    url = "https://sqs.eu-west-1.amazonaws.com/123456789012/build-queue"
+  }
+
+  enable_organization_runners = true
+  enable_ssm_on_runners       = true
+  runner_labels               = ["self-hosted", "linux", "x64"]
+
+  # Use S3 bucket to avoid filebase64sha256 needing local zip files
+  lambda_s3_bucket     = "my-lambda-bucket"
+  runners_lambda_s3_key = "runners.zip"
+
+  github_app_parameters = {
+    key_base64 = { name = "/github-runner/key-base64", arn = "arn:aws:ssm:eu-west-1:123456789012:parameter/github-runner/key-base64" }
+    id         = { name = "/github-runner/app-id", arn = "arn:aws:ssm:eu-west-1:123456789012:parameter/github-runner/app-id" }
+  }
+
+  ssm_paths = {
+    root   = "/github-runner"
+    tokens = "tokens"
+    config = "config"
+  }
+
+  # Enable pool to exercise the pool module and its role type
+  pool_config = [{
+    schedule_expression = "cron(0 8 * * ? *)"
+    size                = 1
+  }]
+}
+
+run "plan_with_pool_enabled" {
+  command = plan
+
+  assert {
+    condition     = length(module.pool) == 1
+    error_message = "Pool module should be enabled when pool_config is non-empty"
+  }
+}