Configuration Schema Reference

StackTest configurations are defined in stacktest.yaml, stacktest.yml, or stacktest.json. Files are parsed by extension (YAML or JSON), then validated by the same Zod models in @stack-test/core.

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

Machine-readable schema

A JSON Schema is generated from the same Zod models and checked into the repository:

• Repository path: schemas/stacktest.schema.json
• Raw URL: https://raw.githubusercontent.com/gattasrikanth/stacktest/main/schemas/stacktest.schema.json

Point your editor at the schema for autocomplete:

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

{
  "$schema": "../../schemas/stacktest.schema.json",
  "project": { "name": "my-project" }
}

Note: JSON Schema validates structural shape. Runtime validation via stacktest lint is stricter: it enforces that referenced providers exist, that each test uses either a single provider+template or stages (not both), and that stage names are unique. An optional "$schema" property in JSON configs is ignored by Zod validation.

---

1. Project Configuration (project)

Defines the namespace for the test execution.

Field	Type	Required	Description
name	string	Yes	Unique project name. Must be lowercase, alphanumeric with hyphens, and start with a letter. Maximum 30 characters.

---

2. Providers Configuration (providers)

A dictionary mapping provider identifiers (like aws-cloudformation) to settings. Additional provider-specific keys are allowed.

Field	Type	Required	Description
regions	string[]	No	Default deployment target environments (for example AWS regions) used when a test does not set its own regions.

---

3. Tests Configuration (tests)

A dictionary mapping suite names to configurations. At least one test suite is required.

Field	Type	Required	Description
provider	string	Conditional	Provider name when not using sequential stages. Must be defined under providers.
template	string	Conditional	Path to the IaC template file (relative to the config file directory).
parameters	Record<string, string | number | boolean | null>	No	Default parameter values passed to the template. Keys must match provider/template parameter names (for CloudFormation: the template Parameters keys).
stages	TestStageConfig[]	Conditional	Sequential multi-provider stages. Mutually exclusive with top-level provider/template.
regions	(string | RegionConfig)[]	No	Target regions for this test. Overrides provider-level regions when set.

Region entries (regions)

Each entry may be either a region name string or an object with per-region parameter overrides:

Form	Example
String	"us-east-1"
Object	{ region: "us-west-2", parameters: { DelaySeconds: 5 } }

Region-level parameters are merged over test-level (or stage-level) parameters for that plan expansion.

Stage entries (stages[])

Field	Type	Required	Description
name	string	Yes	Unique stage name within the test (alphanumeric, dashes, underscores).
provider	string	Yes	Provider for this stage.
template	string	Yes	Template path for this stage.
parameters	Record<string, string | number | boolean | null>	No	Parameters for this stage.

Parameter example

tests:
  parameterized-queue:
    provider: aws-cloudformation
    template: templates/parameterized-queue.yaml
    parameters:
      QueueName: $[stacktest_project_name]-$[stacktest_region]
      DelaySeconds: 0
    regions:
      - region: us-east-1
        parameters:
          DelaySeconds: 0
      - region: us-west-2
        parameters:
          DelaySeconds: 5

See also Parameter Overrides and the AWS CloudFormation parameters example.