Micronaut uses the core io.github.gregwhitaker.aws-emulator plugin. Attach its existing Gradle run and test tasks with awsEmulator.useWith(…); no additional emulator companion is required. Your application chooses its framework and AWS SDK versions.
The example uses Java 17+, Gradle 8.14+, a local Docker engine with Linux containers, and AWS SDK for Java v2. It performs signed HTTPS requests with normal certificate and hostname validation. No AWS account or AWS CLI is required.
Run The Example
From the repository root:
./gradlew -p examples/micronaut test run --configuration-cache
./gradlew -p examples/micronaut test run --configuration-cache
The example build provisions an SQS queue before the framework consumers start. Tests and application execution share a fresh managed instance within that project and build. The repeated command reuses the configuration cache while provisioning and consumers execute again. The managed container, generated credentials, and trust stores are removed after the consumers finish, including ordinary failures.
The example is an independent composite build. classes testClasses compiles it without Docker; test, run, and build require Docker. Applying the plugin or running help does not start an emulator.
Attach An Existing Application
First apply the core plugin from the Gradle Plugin Portal alongside your chosen framework plugins. This integration uses Gradle JavaExec and Test tasks:
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode
val createQueue = tasks.register<CreateSqsQueueTask>("createApplicationQueue") {
queueName.set("application-events")
}
awsEmulator {
useWith(tasks.named<JavaExec>("run"), EmulatorMode.MANAGED, createQueue)
useWith(tasks.named<Test>("test"), EmulatorMode.MANAGED, createQueue)
}
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode
def createQueue = tasks.register('createApplicationQueue', CreateSqsQueueTask) {
queueName.set('application-events')
}
awsEmulator {
useWith(tasks.named('run'), EmulatorMode.MANAGED, createQueue)
useWith(tasks.named('test'), EmulatorMode.MANAGED, createQueue)
}
Task names above refer to tasks supplied by the application’s existing plugins. Only explicitly selected consumers receive the emulator connection. Setup task modes must match their consumers. See Tests & Java execution for source sets and additional consumer configuration.
SDK Client Integration
The Java example uses the Micronaut application plugin and micronaut-aws-sdk-v2. Micronaut creates the injected SqsClient, and both the main application and @MicronautTest call the same Messages bean. The console application sends and receives a message, then closes its application context.
The SDK reads the execution-time connection supplied by Gradle. Keep emulator consumers on the normal SDK providers. Micronaut-specific endpoint overrides or custom credential beans can take precedence; scope production settings to other environments. The example uses the URLConnection HTTP client and leaves TLS verification enabled. See the Micronaut AWS guide for its client configuration.
The example does not apply Micronaut Test Resources. If an existing application uses that plugin to provision AWS/LocalStack, disable that competing AWS provider for emulator consumers. Other services may still use their own test resources.
View The Micronaut Build
/*
* Copyright 2026 Greg Whitaker
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode
plugins {
id("io.micronaut.application")
id("io.github.gregwhitaker.aws-emulator")
}
repositories { mavenCentral() }
micronaut {
version.set(providers.gradleProperty("micronautVersion").getOrElse("4.10.24"))
testRuntime("junit5")
processing {
incremental(true)
annotations("example.*")
}
}
dependencies {
implementation("io.micronaut:micronaut-runtime")
implementation("io.micronaut.aws:micronaut-aws-sdk-v2")
implementation(platform("software.amazon.awssdk:bom:2.39.6"))
implementation("software.amazon.awssdk:sqs") {
exclude(group = "software.amazon.awssdk", module = "apache-client")
exclude(group = "software.amazon.awssdk", module = "netty-nio-client")
}
implementation("software.amazon.awssdk:url-connection-client")
runtimeOnly("ch.qos.logback:logback-classic")
testImplementation("io.micronaut.test:micronaut-test-junit5")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}
java {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
application { mainClass.set("example.Application") }
val applicationMode = providers.gradleProperty("development").map {
if (it.toBoolean()) EmulatorMode.DEVELOPMENT else EmulatorMode.MANAGED
}.orElse(EmulatorMode.MANAGED)
val createApplicationQueue = tasks.register<CreateSqsQueueTask>("createApplicationQueue") {
queueName.set("micronaut-example-events")
mode.set(applicationMode)
}
val createTestQueue = tasks.register<CreateSqsQueueTask>("createTestQueue") {
queueName.set("micronaut-example-events")
}
val run = tasks.named<JavaExec>("run") {
systemProperty("example.fail", providers.gradleProperty("failExample").getOrElse("false"))
}
val tests = tasks.named<Test>("test") {
useJUnitPlatform()
systemProperty("example.fail", providers.gradleProperty("failExample").getOrElse("false"))
}
awsEmulator {
useWith(run, applicationMode, createApplicationQueue)
// Tests always get a fresh managed instance, even when run uses development mode.
useWith(tests, EmulatorMode.MANAGED, createTestQueue)
}
View The Framework-Managed SQS Consumer
/*
* Copyright 2026 Greg Whitaker
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package example;
import jakarta.inject.Singleton;
import software.amazon.awssdk.services.sqs.SqsClient;
import java.util.UUID;
/** Micronaut AWS creates and closes the injected SQS client using the normal SDK providers. */
@Singleton
public class Messages {
private final SqsClient sqs;
public Messages(SqsClient sqs) { this.sqs = sqs; }
public String roundTrip() {
String url = sqs.getQueueUrl(request -> request.queueName("micronaut-example-events")).queueUrl();
String body = "Hello from Micronaut: " + UUID.randomUUID();
sqs.sendMessage(request -> request.queueUrl(url).messageBody(body));
var messages = sqs.receiveMessage(request -> request.queueUrl(url).waitTimeSeconds(5)).messages();
if (messages.isEmpty()) throw new IllegalStateException("Expected an SQS message");
var message = messages.get(0);
sqs.deleteMessage(request -> request.queueUrl(url).receiptHandle(message.receiptHandle()));
if (!body.equals(message.body())) throw new IllegalStateException("Unexpected SQS message: " + message.body());
return message.body();
}
}
Development, Debugging, And Failures
The example accepts -Pdevelopment=true for application runs:
./gradlew -p examples/micronaut run -Pdevelopment=true --configuration-cache
./gradlew -p examples/micronaut run -Pdevelopment=true --configuration-cache
./gradlew -p examples/micronaut listSqsQueues
./gradlew -p examples/micronaut stopAwsEmulator
The application still exits after its round trip. Its development emulator survives success or failure and is reused until explicitly stopped. test always uses a managed instance, even with -Pdevelopment=true. The example registers separate setup tasks so managed tests and development runs cannot accidentally target the same runtime.
To debug the example, run run --debug-jvm and attach to port 5005. Gradle suspends the JVM until a debugger connects. The emulator and queue are ready before the application JVM starts.
To exercise managed cleanup after application or test failure:
./gradlew -p examples/micronaut run -PfailExample=true
./gradlew -p examples/micronaut test -PfailExample=true
These commands intentionally fail after completing their SDK round trip.
Compatibility And Verification
| Framework | Docker-free compatibility fixtures | Real-emulator fixtures |
|---|---|---|
Micronaut |
Platform 4.9.4 and 4.10.24; Micronaut Gradle plugin 4.6.2 |
Platform 4.10.24 |
The Docker-free suite compiles the application and its tests, verifies setup ordering and runtime selection, and checks configuration-cache reuse without invoking Docker. It runs under the repository’s JDK/Gradle CI matrix. Override the example framework version with -PmicronautVersion=4.9.4 to reproduce the alternate fixture.
The real-emulator suite checks framework consumers, signed HTTPS, inherited credential/endpoint replacement, managed runtime sharing and failure cleanup, development reuse, and isolation between development runs and managed tests. Both suites copy the runnable example, so the documented sources are the compatibility fixture.
./gradlew :plugin:functionalTest --tests '*FrameworkCompatibilityFunctionalTest'
./gradlew :plugin:integrationTest --tests '*FrameworkIntegrationTest'
Verified support covers JVM run and Test consumers using AWS SDK for Java v2. Native images and continuous restart or automatic reload workflows are outside this compatibility scope. IDE launches must delegate to the opted-in Gradle task to receive the generated connection. See Credentials & TLS for client-level overrides and trust configuration.