Skip to main content

emulator

The emulator step type starts, stops, or resets a local cloud emulator component from a workflow, custom command, or lifecycle hook. It is the declarative way to bracket an operation with a sandbox — most commonly a kind: step hook on the before.terraform.test / after.terraform.test events that brings the emulator up before Terraform tests and tears it down after. No shelling out to atmos emulator.

steps:
  - name: start-sandbox
    type: emulator
    component: aws        # the emulator component to operate on
    action: up            # up | down | reset (default: up)

The most common use is on the terraform test lifecycle so apply-backed tests run against a local sandbox with no cloud account:

hooks:
  start-emulator:
    kind: step
    type: emulator
    events: [before.terraform.test]
    with: { component: aws, action: up }
  stop-emulator:
    kind: step
    type: emulator
    events: [after.terraform.test]
    when: always          # tear down even if a test fails
    with: { component: aws, action: down }

Fields​

component
Required. The name of the emulator component to operate on (e.g. aws). Supports Go templates.
action
Lifecycle action: up (start or reuse the sandbox), down (stop and remove it), or reset (stop and wipe persisted state, non-interactively). Defaults to up.
ephemeral
When true with action: up, runs the emulator without persistence for this invocation, overriding the component's ephemeral: config. Defaults to false.
stack
The stack the emulator belongs to. As a lifecycle hook this defaults to the component's stack, so it is rarely set explicitly.

See also​