Configuration Overview

StackTest is configured with a project config file at the repository root (or passed via --config).

Supported formats (same Zod schema after parse):

Format	Filenames	Notes
YAML (default)	stacktest.yaml, stacktest.yml	Preferred for hand-authored configs (comments, familiarity)
JSON	stacktest.json	Useful for generated configs and tooling; supports "$schema"

Auto-discovery order when --config is omitted: stacktest.yaml → stacktest.yml → stacktest.json.

Here is a full YAML example showing the three main configuration blocks:

project:
  name: billing-infrastructure

providers:
  aws-cloudformation:
    regions:
      - us-east-1
      - us-west-2
    roleArn: arn:aws:iam::123456789012:role/StackTestExecutionRole

tests:
  basic-queue:
    provider: aws-cloudformation
    template: templates/sqs.yaml
    parameters:
      QueueName: $[stacktest_project_name]-$[stacktest_region]-$[stacktest_run_id]

Equivalent JSON:

{
  "$schema": "https://raw.githubusercontent.com/gattasrikanth/stacktest/main/schemas/stacktest.schema.json",
  "project": { "name": "billing-infrastructure" },
  "providers": {
    "aws-cloudformation": {
      "regions": ["us-east-1", "us-west-2"],
      "roleArn": "arn:aws:iam::123456789012:role/StackTestExecutionRole"
    }
  },
  "tests": {
    "basic-queue": {
      "provider": "aws-cloudformation",
      "template": "templates/sqs.yaml",
      "parameters": {
        "QueueName": "$[stacktest_project_name]-$[stacktest_region]-$[stacktest_run_id]"
      }
    }
  }
}

Structure Sections

1. project: Metadata like name.
2. providers: Settings specific to infrastructure deployment plugins.
3. tests: Define your test target matrix, template location, and parameter bindings.

Schema and IDE support

A machine-readable JSON Schema is generated from the Zod config models and lives at schemas/stacktest.schema.json.

YAML (Language Server):

# yaml-language-server: $schema=../../schemas/stacktest.schema.json

JSON:

{
  "$schema": "../../schemas/stacktest.schema.json"
}

Structural validation in the editor does not replace stacktest lint, which also checks template paths and cross-field rules.