Skip to main content

atmos.emulator

The atmos.emulator function runs atmos emulator through the current Atmos executable. Use it to start, reset, and stop local cloud-API emulator components and to run commands inside them from automation.

Also available as atmos.emu.

Usage​

atmos.emulator(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Subcommands​

Pass the subcommand and any positional arguments as strings before the keyword arguments. The call atmos.emulator("up", "aws", flags = {"stack": "local"}) runs atmos emulator up aws --stack=local.

SubcommandPurpose
upStart the emulator container.
downStop and remove the emulator container.
resetStop the emulator and wipe its persisted state.
execRun a command in the emulator container.
logsShow the emulator container logs.
psList configured running emulators.
listList emulators and their status. Also available as ls.

See the atmos emulator command reference for the complete list of subcommands and flags.

note

The emulator command is experimental, so each call prints the experimental notice. Starting an emulator needs a container runtime, either Docker or Podman, on the machine running the script. The reset subcommand asks for confirmation unless the force flag is set, so pass it when no terminal is available.

Arguments​

*positionals

(Optional) Strings placed on the command line right after emulator, in order: the subcommand and its positional arguments, such as the emulator component name. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. The stack key becomes --stack (shorthand s ). Other keys include ephemeral for up, force for reset, and runtime for list and ps.

args
(Optional) A list or tuple of strings appended after the flags.
working_directory, env, output, check

(Optional) See atmos.run for process options and defaults.

Options other than the positionals are keyword-only.

Returns​

A result with stdout, stderr, and exit_code. See atmos.run for output and error behavior.

Examples​

Start an emulator for a test run​

atmos.emulator("up", "aws", flags = {"stack": "local"})

Start without persisting state​

atmos.emulator("up", "aws", flags = {"stack": "local", "ephemeral": True})

The ephemeral key becomes the bare flag --ephemeral, so data is discarded when the emulator goes down.

Wipe state without a prompt​

atmos.emulator("reset", "aws", flags = {"stack": "local", "force": True})

Always stop the emulator after a job​

def run_checks():
    # Replace with your project's integration test command.
    return exec.run(["go", "test", "./tests/integration/..."], check = False)

atmos.emulator("up", "aws", flags = {"stack": "local"})
outcome = run_checks()
atmos.emulator("down", "aws", flags = {"stack": "local"})
if outcome.exit_code != 0:
    fail("Integration tests failed.")

Related​