Configure the awsEmulator extension using Gradle’s lazy properties. Top-level runtime settings configure the reserved default runtime’s managed and development instances; restart an existing development instance after changing runtime settings.

Runtime Modes

Choose a mode based on how long the emulator should stay available. Applying the plugin does not start Docker or opt existing tests into the emulator.

Behavior MANAGED DEVELOPMENT

Use for

Tests and build tasks that need a fresh environment.

Local applications and interactive development across builds.

Startup

Starts on demand when an opted-in consumer or resource task needs it.

Starts with startAwsEmulator or on demand from a consumer or resource task selecting development mode.

Lifetime

Shared by participating tasks during the build. Removed automatically at build completion, including ordinary task failures.

Stays running after tasks, applications, and Gradle exit. Remove it explicitly with stopAwsEmulator.

Resource state

Starts fresh for each build; participating tasks share resources.

Resources remain available between builds until the instance stops or restarts.

Managed and development instances use separate containers and working directories, so development resources are not available to managed tests. Both store resources in memory; stopping or restarting discards them. Tasks selecting the same runtime name and mode within a project share an instance; shared runtimes extend that ownership across projects.

useWith(task) selects MANAGED. Pass EmulatorMode.DEVELOPMENT explicitly to connect a consumer to the persistent instance. Custom resource tasks inherit awsEmulator.defaultMode, initially MANAGED; module convenience tasks use DEVELOPMENT. Provisioning tasks and their consumers must select the same runtime name and mode. See resource task configuration for defaults and overrides.

See tests and process execution for consumer setup and managed cleanup, or development lifecycle for persistent instances and lifecycle commands.

With an external connection, both modes use the same existing instance. The plugin does not manage its lifecycle, separate its state by mode, or clean up its resources.

Extension Reference

Property Default Meaning

defaultMode

EmulatorMode.MANAGED

Default lifecycle mode for custom resource tasks in this project, including named runtimes. Explicit task modes and --mode take precedence. Consumers, resource-set attachments, convenience tasks, and Spring Boot select their own modes.

emulatorVersion

1.0.385

Pinned AWS Emulator package used when building an image.

image

Unset

Use this Docker image instead of building one. Pull it if it is missing locally.

platform

auto

Detect the Docker engine architecture, or select linux/amd64 or linux/arm64.

port

0

Automatically select an available local endpoint port; also the container port with DIRECT. If another process claims an automatically selected DIRECT port, startup removes the failed container and retries with a fresh port, up to three attempts. Set a nonzero value for a fixed port; fixed-port conflicts fail immediately. Also configurable with -PawsEmulator.port=…​.

region

us-east-1

Region passed to consuming SDKs and resource provisioning.

telemetryEnabled

false

Explicitly enable the emulator’s AWS telemetry.

dockerExecutable

docker

Docker command name or absolute executable path.

docker.host

Empty

Docker daemon address passed as --host, such as ssh://builder@example.com. Mutually exclusive with docker.context.

docker.context

Empty

Docker context name passed as --context. With both selection properties empty, Docker uses its existing context/environment.

docker.transport

DockerTransport.DIRECT

DIRECT uses local port publication and bind mounts. TUNNEL supports managed runtimes in containerized CI and on remote engines; see remote Docker.

memoryLimit

2g

Container memory limit. Swap is capped at the same total.

startupTimeoutSeconds

60

HTTPS readiness deadline after the container starts, or while connecting to an external emulator.

commandTimeoutSeconds

60

Timeout for each normal Docker command.

buildTimeoutSeconds

600

Timeout for an image build or pull.

workingDirectory

.aws-emulator in the project

Generated Dockerfiles, locks, and isolated runtime homes.

runtimes

Empty container

Independent named runtimes. Common settings inherit from this extension, with automatic ports, separate working directories, and independently configured external connections. See named runtimes.

defaultScenario

default

Registered scenario selected by seedAwsEmulator and resetAwsEmulator. Override with -PawsEmulator.scenario=<name>.

scenarios

Empty container

Named development scenarios with resource provisioning and ordered fixture tasks. See Data fixtures & development scenarios.

external

Disabled

Connect to an already-running emulator using endpoint, credentialsFile, and certificateFile. Configuring the block enables it; see existing emulators.

The useWith(taskProvider) method accepts an existing Test, JavaExec, or Exec task provider. See tests and process execution for lifecycle and caching behavior. When external.enabled is true, both runtime modes use the external connection; Docker settings are ignored and lifecycle commands are rejected.

The useSharedRuntime(ownerProject, resourceSets…​) method selects an absolute project path in this build and optional resource-set names from that owner. Its runtime settings and working directory replace the consumer’s runtime settings. See sharing across projects for ownership rules and examples.

Configure A Project

Kotlin DSL
awsEmulator {
    region.set("us-west-2")
    memoryLimit.set("3g")
    startupTimeoutSeconds.set(120)
    buildTimeoutSeconds.set(900)
    workingDirectory.set(layout.projectDirectory.dir(".aws-emulator"))
    useWith(tasks.named<Test>("test"))
}
Groovy DSL
awsEmulator {
    region.set('us-west-2')
    memoryLimit.set('3g')
    startupTimeoutSeconds.set(120)
    buildTimeoutSeconds.set(900)
    workingDirectory.set(layout.projectDirectory.dir('.aws-emulator'))
    useWith(tasks.named('test'))
}

Managed and development instances select available ports by default. The default runtime reads awsEmulator.port, so -PawsEmulator.port=9297 requests a fixed port without changing the build script. An explicit port.set(…​) replaces that convention and takes precedence over the command-line property. Named runtimes select their own ports independently.

Image And Platform Overrides

The default emulator version is bundled with each plugin release from the repository’s gradle/emulator.properties. Upgrade PRs must pass compatibility checks and a separate CloudFormation provisioning audit before a maintainer merges them. An explicit emulatorVersion.set("…​") selects another release for a consumer; CloudFormation validation still requires its separately audited version.

Leave image unset to build the pinned AWS package. Set it only for an image whose entrypoint runs AWS Emulator, binds 0.0.0.0, and accepts the emulator’s normal CLI flags.

platform = auto detects the Docker engine architecture, which may differ from the host running Gradle. Explicit values are linux/amd64 and linux/arm64.

The initial build or pull needs network access. Images stay in Docker’s cache when the plugin removes runtime containers.

Runtime Files

Add .aws-emulator/, or your chosen workingDirectory, to the application’s .gitignore. It contains generated local credentials while instances run. Managed and development runtime homes are isolated within this directory.

The plugin does not modify your personal AWS configuration. See credentials and TLS for the host-side connection files and how consuming JVMs receive them.

Resource Task Configuration

runtimeName, mode, and apiCallTimeoutSeconds belong to individual provisioning tasks. Custom tasks default to runtime default, mode awsEmulator.defaultMode (initially EmulatorMode.MANAGED), and 30 seconds per SDK operation. Select another declared runtime with runtimeName.set("integration") or --runtime integration.

Set the shared resource-task default once for a development project:

import io.github.gregwhitaker.awsemulator.model.EmulatorMode

awsEmulator {
    defaultMode.set(EmulatorMode.DEVELOPMENT)
}

In Groovy, use the same import and awsEmulator { defaultMode.set(EmulatorMode.DEVELOPMENT) }. Tasks registered before or after the extension block inherit the property lazily. A task’s explicit mode.set(…​) or --mode=MANAGED overrides it. Development resources remain available until stopAwsEmulator.

This property applies to custom resource tasks in the current project, across all runtime names. Module convenience tasks use DEVELOPMENT; resource sets use their consumer or scenario’s mode. useWith(task) continues to select MANAGED. To align a consumer with the resource-task default, pass the property explicitly: awsEmulator { useWith(tasks.named<Test>("test"), defaultMode) }. The Spring Boot companion uses its own awsEmulator.springBoot.mode setting.

Each service guide lists its task properties. See S3 task properties for buckets and objects, or SQS task properties for queues and message fixtures.