The companion plugin io.github.gregwhitaker.aws-emulator.spring-boot adds bootRunLocal and bootRunLocalDebug. It automatically applies the base emulator plugin. Your application selects and applies org.springframework.boot and its Java or Kotlin JVM plugin.

The companion is a separate artifact, io.github.gregwhitaker:gradle-aws-emulator-spring-boot, released with the core plugin. It uses the application’s Spring Boot task type and does not bring Spring Boot into your build transitively. Compatibility is tested with Spring Boot 3.5.16 and 4.1.2.

Apply From The Plugin Portal

Get the companion from the Gradle Plugin Portal and apply it with a version. Gradle uses the Portal by default; if you customize plugin repositories, follow the plugin repository setup.

import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask

plugins {
    java
    id("org.springframework.boot") version "4.1.2"
    id("io.github.gregwhitaker.aws-emulator.spring-boot") version "0.3.0"
}

awsEmulator {
    springBoot {
        profiles.set(listOf("local"))
    }
}
tasks.register<CreateSqsQueueTask>("createApplicationQueue") {
    queueName.set("application-events")
}
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask

plugins {
    id 'java'
    id 'org.springframework.boot' version '4.1.2'
    id 'io.github.gregwhitaker.aws-emulator.spring-boot' version '0.3.0'
}

awsEmulator {
    springBoot {
        profiles.set(['local'])
    }
}
tasks.register('createApplicationQueue', CreateSqsQueueTask) {
    queueName.set('application-events')
}

Plugin application order does not matter. Until both Spring Boot and Java are present, the companion exposes its settings and the base emulator tasks, without registering the Boot tasks or starting Docker.

To test local plugin changes, use the checkout setup and omit the companion’s version.

Automatic Resource Creation

An external connection applies to both local Boot tasks and their resource setup. Configure awsEmulator.external on the runtime owner. Both modes connect to that instance and leave it running after application exits or failures.

Register resource-creation tasks with their required properties, as above. bootRunLocal and bootRunLocalDebug automatically discover those tasks in the application’s project and run them before starting the application. The queue in this example needs no setupTasks, dependsOn, or mode configuration.

Automatic setup covers S3 buckets; SQS queues and DLQs; SNS topics and SQS subscriptions; DynamoDB tables and their initializers; SSM parameters; Secrets Manager secrets; EventBridge buses, rules, and targets; Kinesis streams; KMS keys and aliases; and CloudWatch log groups and streams.

SES identity, template, configuration-set, and event-destination tasks also participate. Sending email and reading message insights require explicit dependencies.

Discovery uses the core @AwsEmulatorSetupTask annotation on resource task types. Subclasses inherit it. Annotate your own AbstractAwsResourceTask subclasses to opt them into discovery. Registration remains lazy, so tasks declared after the companion is applied are included.

The companion selects its runtime name and mode as defaults for discovered resource tasks and their resource prerequisites when a local Boot task is selected. Automatic discovery skips tasks explicitly assigned to other runtime names. Explicit prerequisites must use the application’s runtime; conflicts fail before startup. Explicit task dependencies determine ordering between resources; for example, a log-stream task should depend on its log-group task. Use additional setupTasks or dependsOn dependencies for message publishing, data fixtures, and custom preparation.

Explicit resource modes are respected. A conflicting mode fails with a configuration error before startup. For separate test-only resources, exclude those task names or paths:

awsEmulator {
    springBoot {
        excludedSetupTasks.add("createTestQueue")
    }
}

Exclusions affect automatic discovery; explicit dependencies still run. To select all setup tasks manually, set autoCreateResources to false and use setupTasks. In that case, configure resource tasks to use awsEmulator.springBoot.mode yourself. Ordinary bootRun, test tasks, and standalone resource invocations retain their existing behavior.

Run And Debug

For applications in different Gradle projects, awsEmulator.useSharedRuntime(":local-aws", "application") selects one owner and automatically attaches its named resources to both local Boot tasks. No additional springBoot.resourceSets attachment is needed for those sets. The owner’s settings govern the shared runtime; the application’s springBoot.mode still selects managed or development. See sharing across projects.

For resources shared with managed tests and scenarios, declare reusable resource sets and attach them using awsEmulator.springBoot.resourceSets.add(setProvider). The plugin creates separate tasks for each runtime name and mode and runs provisioning and fixtures before either local Boot task. Generated resource-set tasks are excluded from automatic discovery, so test attachments do not leak into Boot setup. Explicit resource sets run even when autoCreateResources is false.

./gradlew bootRunLocal
./gradlew bootRunLocal --args='--server.port=8081'
./gradlew bootRunLocalDebug
./gradlew stopAwsEmulator

The debug task listens on 127.0.0.1:5005 and waits for a debugger. The ordinary bootRun task is not connected to the emulator by applying this plugin.

Both local tasks use BootRun. They inherit bootRun’s main-class provider (including Spring Boot’s automatic discovery), classpath, Java launcher, optimized-launch setting, working directory, environment, system properties, application arguments, JVM arguments, and argument providers when configured. Custom actions on `bootRun are not copied. Configure the local task directly when it needs additional task behavior. Command-line --args overrides the copied application arguments.

The tasks support configuration-cache reuse. With automatic main-class discovery, Spring Boot can invalidate the first cache entry when a clean compilation creates class directories; subsequent unchanged runs reuse the cache.

The base plugin supplies endpoint, region, generated credentials, and TLS trust just before the JVM starts. Your application still declares its own AWS SDK dependencies. See Credentials and TLS for connection details.

Gradle Isolated Projects

The companion’s local Boot tasks, resource setup, named runtimes, and shared owner selection support Isolated Projects. Keep each application’s configuration in its own project.

The upstream Spring Boot plugin still reads other projects' group and version while configuring BootJar in a multi-project build; see Spring Boot issue 43755. Gradle’s Java test ordering can realize that task even when packaging is not requested. Such builds can therefore fail isolation checks independently of the emulator plugin. Single-project Boot applications and shared-owner local Boot execution are covered by this plugin’s isolation tests; full multi-project Boot test and packaging support also depends on the upstream plugin.

Configuration

Configure the companion in awsEmulator { springBoot { …​ } }. The previous top-level springBootEmulator block remains an alias for the same settings for compatibility with existing builds.

awsEmulator.springBoot property Default Behavior

mode

EmulatorMode.DEVELOPMENT

Selects the persistent development instance or a build-owned MANAGED instance.

runtimeName

default

Selects a runtime declared in the owner’s awsEmulator.runtimes, or the existing default runtime.

profiles

["local"]

Adds spring.profiles.active; an empty list adds no profile argument.

jvmArgs

[]

Additional JVM arguments for both local tasks.

autoCreateResources

true

Automatically discovers resource-provisioning tasks and runs them before either local task.

excludedSetupTasks

[]

Task names or paths to omit from automatic discovery.

setupTasks

[]

Additional Gradle task names or paths that both local tasks depend on.

resourceSets

[]

Reusable definitions to provision and seed in the application’s selected mode.

debugPort

5005

Debugger port, from 1 to 65535.

debugSuspend

true

Whether the debug task waits for a debugger before starting the application.

Resource setup tasks use the same runtime as the application. Reusable sets create separate tasks for consumers in different runtime names or modes within one build. When using ordinary task instances instead, register separate tasks and exclude test-only resources from automatic discovery. See named runtimes for declaration, settings inheritance, and lifecycle commands.

Development instances retain their resources across Gradle invocations until stopAwsEmulator or restartAwsEmulator. For automatic cleanup after the application finishes, including ordinary application failures:

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

awsEmulator {
    springBoot {
        mode.set(EmulatorMode.MANAGED)
    }
}

Hard process termination or Docker daemon failure can prevent cleanup, as described in Tests and Java execution.

Runnable Example

The Spring Boot example sends and receives an SQS message and exits. From this repository:

./gradlew -p examples/spring-boot bootRunLocal --configuration-cache
./gradlew -p examples/spring-boot bootRunLocal --configuration-cache
./gradlew -p examples/spring-boot stopAwsEmulator

Use -Pmanaged=true for automatic cleanup, or bootRunLocalDebug to attach a debugger. Browse the companion Java API for the extension reference.

For auto-configured AWS clients, SQS listeners, and configuration imports, see the Spring Cloud AWS guide.