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 |
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 |
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 |
|---|---|---|
|
|
Default lifecycle mode for custom resource tasks in this project, including named runtimes. Explicit task modes and |
|
|
Pinned AWS Emulator package used when building an image. |
|
Unset |
Use this Docker image instead of building one. Pull it if it is missing locally. |
|
|
Detect the Docker engine architecture, or select |
|
|
Automatically select an available local endpoint port; also the container port with |
|
|
Region passed to consuming SDKs and resource provisioning. |
|
|
Explicitly enable the emulator’s AWS telemetry. |
|
|
Docker command name or absolute executable path. |
|
Empty |
Docker daemon address passed as |
|
Empty |
Docker context name passed as |
|
|
|
|
|
Container memory limit. Swap is capped at the same total. |
|
|
HTTPS readiness deadline after the container starts, or while connecting to an external emulator. |
|
|
Timeout for each normal Docker command. |
|
|
Timeout for an image build or pull. |
|
|
Generated Dockerfiles, locks, and isolated runtime homes. |
|
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. |
|
|
Registered scenario selected by |
|
Empty container |
Named development scenarios with resource provisioning and ordered fixture tasks. See Data fixtures & development scenarios. |
|
Disabled |
Connect to an already-running emulator using |
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.
API: AwsEmulatorExtension.
Configure A Project
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"))
}
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.