Start with Java 17+, Gradle 8.14+, and Docker running Linux containers. The first emulator run downloads and builds the pinned package; later runs reuse the image.
If an emulator is already running elsewhere, use an external connection instead; the Gradle machine then needs no Docker installation.
Apply From The Plugin Portal
Get the core plugin from the Gradle Plugin Portal and apply it with a version in your application’s build script. Gradle uses the Portal by default, so no settings changes are needed for a standard build.
Kotlin DSL
plugins {
java
id("io.github.gregwhitaker.aws-emulator") version "0.3.0"
}
awsEmulator {
useWith(tasks.named<Test>("test"))
}
Groovy DSL
plugins {
id 'java'
id 'io.github.gregwhitaker.aws-emulator' version '0.3.0'
}
awsEmulator {
useWith(tasks.named('test'))
}
Add .aws-emulator/ to the consuming application’s .gitignore. It holds generated runtime files, including local emulator credentials while the instance runs.
Then run your application’s ./gradlew test. Tests with work run against a fresh managed emulator. A NO-SOURCE test task does not start one by itself. Your application must declare its own AWS SDK and test dependencies; the plugin’s SDK dependencies support its provisioning tasks.
|
Tip
|
An available host port is selected automatically, supporting parallel projects, concurrent builds, and simultaneous managed and development instances. Use -PawsEmulator.port=9297 when you need a fixed port.
|
For projects with separate unit and integration suites, attach the existing integrationTest task instead of test. The complete example below registers an integration suite and opts it in explicitly with useWith.
Custom Plugin Repositories
If your settings already declare pluginManagement.repositories, include gradlePluginPortal() alongside your other plugin repositories. This syntax works in both settings.gradle.kts and settings.gradle:
pluginManagement {
repositories {
gradlePluginPortal()
}
}
For Spring Boot applications, use the companion plugin, which applies the core plugin automatically.
Run The Included Example
From the plugin repository root:
./gradlew -p examples/basic integrationTest --configuration-cache
The example creates S3 buckets, standard/FIFO SQS queues and a FIFO DLQ, publishes message fixtures, verifies object and message round trips and a signed STS request, then removes its managed container. Run the command a second time to exercise configuration-cache reuse.
No AWS account, AWS CLI, or personal AWS credentials are needed. The plugin supplies the emulator connection at task execution time. Repository examples use this checkout through composite builds so they exercise local plugin changes.
Apply From A Checkout
To test local plugin changes in your own application, include the plugin repository in your application’s plugin management. Adjust the relative path for your checkout layout.
pluginManagement {
includeBuild("../gradle-aws-emulator")
}
pluginManagement {
includeBuild('../gradle-aws-emulator')
}
Use the application build configuration above, omitting the version from the emulator plugin declaration. The same setup supplies the Spring Boot companion from the checkout; omit its version too, while keeping your application’s Spring Boot plugin version.
The Complete Example
The following files are included directly from examples/basic during site generation. They use the checkout setup above; for your own application, use the Plugin Portal declaration with a version instead of the example’s includeBuild.
/*
* 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.
*/
pluginManagement {
includeBuild("../..")
}
rootProject.name = "aws-emulator-example"
View the example build script
/*
* 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.s3.CreateS3BucketsTask
import io.github.gregwhitaker.awsemulator.aws.s3.PutS3BucketPolicyTask
import io.github.gregwhitaker.awsemulator.aws.s3.PutS3BucketVersioningTask
import io.github.gregwhitaker.awsemulator.aws.s3.PutS3BucketNotificationConfigurationTask
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueuesTask
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueWithDlqTask
import io.github.gregwhitaker.awsemulator.aws.sqs.PublishSqsTask
import io.github.gregwhitaker.awsemulator.aws.sqs.DeleteSqsQueuesTask
import io.github.gregwhitaker.awsemulator.emulator.ReportAwsEmulatorTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode
import software.amazon.awssdk.services.s3.model.BucketVersioningStatus
import software.amazon.awssdk.services.s3.model.Event
import software.amazon.awssdk.services.s3.model.NotificationConfiguration
import software.amazon.awssdk.services.s3.model.QueueConfiguration
plugins {
java
id("io.github.gregwhitaker.aws-emulator")
}
repositories { mavenCentral() }
val integrationSourceSet = sourceSets.create("integration")
dependencies {
"integrationImplementation"(platform("software.amazon.awssdk:bom:2.39.6"))
"integrationImplementation"("software.amazon.awssdk:sts")
"integrationImplementation"("software.amazon.awssdk:s3")
"integrationImplementation"("software.amazon.awssdk:sqs")
"integrationImplementation"("software.amazon.awssdk:url-connection-client")
"integrationImplementation"(platform("org.junit:junit-bom:5.11.4"))
"integrationImplementation"("org.junit.jupiter:junit-jupiter")
"integrationRuntimeOnly"("org.junit.platform:junit-platform-launcher")
}
val createBuckets = tasks.register<CreateS3BucketsTask>("createExampleBuckets") {
buckets.set(listOf("example-test-bucket", "example-uploads"))
}
val createQueue = tasks.register<CreateSqsQueueTask>("createExampleQueue") {
queueName.set("example-test-queue")
attributes.put("VisibilityTimeout", "45")
}
val createFifoQueue = tasks.register<CreateSqsQueueWithDlqTask>("createExampleFifoQueue") {
queueName.set("example-events.fifo")
queueAttributes.put("FifoQueue", "true")
queueAttributes.put("ContentBasedDeduplication", "true")
maxReceiveCount.set(3)
}
val createFixtureQueues = tasks.register<CreateSqsQueuesTask>("createFixtureQueues") {
queueNames.set(listOf("example-seeded-queue", "example-secondary-queue"))
}
val publishFixtures = tasks.register<PublishSqsTask>("publishFixtures") {
dependsOn(createFixtureQueues)
queueNames.add("example-seeded-queue")
messages.from(layout.projectDirectory.dir("src/integration/messages"))
}
val configureUploadPolicy = tasks.register<PutS3BucketPolicyTask>("configureUploadPolicy") {
dependsOn(createBuckets)
bucketName.set("example-uploads")
policyFile.set(layout.projectDirectory.file("src/integration/fixtures/upload-policy.json"))
}
val versionUploads = tasks.register<PutS3BucketVersioningTask>("versionUploads") {
dependsOn(createBuckets)
bucketName.set("example-uploads")
status.set(BucketVersioningStatus.ENABLED)
}
// This pinned emulator uses account 000000000000 and the example's default us-east-1 region.
val createUploadEvents = tasks.register<CreateSqsQueueTask>("createUploadEvents") {
queueName.set("example-upload-events")
attributes.put("Policy", """{
"Version":"2012-10-17","Statement":[{"Effect":"Allow",
"Principal":{"Service":"s3.amazonaws.com"},"Action":"sqs:SendMessage",
"Resource":"arn:aws:sqs:us-east-1:000000000000:example-upload-events",
"Condition":{"ArnEquals":{"aws:SourceArn":"arn:aws:s3:::example-uploads"}}}]
}""")
}
val notifyUploads = tasks.register<PutS3BucketNotificationConfigurationTask>("notifyUploads") {
dependsOn(createBuckets, createUploadEvents)
bucketName.set("example-uploads")
notificationConfiguration.set(NotificationConfiguration.builder().queueConfigurations(
QueueConfiguration.builder().id("uploads")
.queueArn("arn:aws:sqs:us-east-1:000000000000:example-upload-events")
.events(Event.S3_OBJECT_CREATED).build()).build())
}
val createDiscardedQueue = tasks.register<CreateSqsQueueTask>("createDiscardedQueue") {
queueName.set("example-discarded-queue")
}
val deleteDiscardedQueue = tasks.register<DeleteSqsQueuesTask>("deleteDiscardedQueue") {
dependsOn(createDiscardedQueue)
queueNames.add("example-discarded-queue")
}
val integrationTest = tasks.register<Test>("integrationTest") {
description = "Verifies provisioned S3 and SQS resources using signed AWS SDK requests."
group = "verification"
testClassesDirs = integrationSourceSet.output.classesDirs
classpath = integrationSourceSet.runtimeClasspath
useJUnitPlatform()
// Deliberately poisoned settings prove that useWith supplies the emulator connection.
environment("AWS_ACCESS_KEY_ID", "not-a-real-access-key")
environment("AWS_SECRET_ACCESS_KEY", "not-a-real-secret")
environment("AWS_PROFILE", "not-a-real-profile")
systemProperty("aws.accessKeyId", "not-a-real-access-key")
systemProperty("aws.secretAccessKey", "not-a-real-secret")
systemProperty("example.fail", providers.gradleProperty("failExample").getOrElse("false"))
// Optional custom HTTPS trust is merged with this task's JDK roots and the emulator certificate.
providers.gradleProperty("exampleTrustStore").orNull?.let {
systemProperty("javax.net.ssl.trustStore", file(it).absolutePath)
}
providers.gradleProperty("exampleTrustStoreType").orNull?.let { systemProperty("javax.net.ssl.trustStoreType", it) }
providers.environmentVariable("EXAMPLE_TRUST_STORE_PASSWORD").orNull?.let {
systemProperty("javax.net.ssl.trustStorePassword", it)
}
}
awsEmulator {
useWith(integrationTest, EmulatorMode.MANAGED, createBuckets, createQueue, createFifoQueue, publishFixtures,
configureUploadPolicy, versionUploads, notifyUploads, deleteDiscardedQueue)
}
// Opt in to a snapshot after successful or failed tests, before the managed instance is removed.
val reportIntegrationEmulator = tasks.register<ReportAwsEmulatorTask>("reportIntegrationEmulator") {
mode.set(EmulatorMode.MANAGED)
}
if (providers.gradleProperty("emulatorReport").isPresent) {
integrationTest.configure { finalizedBy(reportIntegrationEmulator) }
}
View the SDK integration test
/*
* 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 org.junit.jupiter.api.Test;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.services.sts.StsClient;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.BucketVersioningStatus;
import software.amazon.awssdk.services.sqs.SqsClient;
import software.amazon.awssdk.services.sqs.model.QueueDoesNotExistException;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.core.client.config.SdkAdvancedClientOption;
import java.util.Set;
import java.time.Duration;
import java.util.stream.Collectors;
import static org.junit.jupiter.api.Assertions.*;
class EmulatorIntegrationTest {
@Test
void verifiesBucketConfigurationNotificationsAndExplicitQueueDeletion() {
try (S3Client s3 = S3Client.builder().forcePathStyle(true)
.overrideConfiguration(config -> config.putAdvancedOption(SdkAdvancedClientOption.DISABLE_HOST_PREFIX_INJECTION, true))
.httpClientBuilder(UrlConnectionHttpClient.builder()).build();
SqsClient sqs = SqsClient.builder().httpClientBuilder(UrlConnectionHttpClient.builder()).build()) {
assertEquals(BucketVersioningStatus.ENABLED, s3.getBucketVersioning(r -> r.bucket("example-uploads")).status());
assertTrue(s3.getBucketPolicy(r -> r.bucket("example-uploads")).policy().contains("ReadExampleUploads"));
assertEquals(1, s3.getBucketNotificationConfiguration(r -> r.bucket("example-uploads")).queueConfigurations().size());
assertThrows(QueueDoesNotExistException.class, () -> sqs.getQueueUrl(r -> r.queueName("example-discarded-queue")));
String first = s3.putObject(r -> r.bucket("example-uploads").key("notification.txt"), RequestBody.fromString("first")).versionId();
String second = s3.putObject(r -> r.bucket("example-uploads").key("notification.txt"), RequestBody.fromString("second")).versionId();
assertNotNull(first);
assertNotEquals(first, second);
assertEquals("first", s3.getObjectAsBytes(r -> r.bucket("example-uploads").key("notification.txt").versionId(first)).asUtf8String());
String url = sqs.getQueueUrl(r -> r.queueName("example-upload-events")).queueUrl();
boolean delivered = false;
long deadline = System.nanoTime() + Duration.ofSeconds(15).toNanos();
while (!delivered && System.nanoTime() < deadline) {
for (var message : sqs.receiveMessage(r -> r.queueUrl(url).waitTimeSeconds(2).maxNumberOfMessages(10)).messages()) {
delivered |= message.body().contains("notification.txt") && message.body().contains("example-uploads");
sqs.deleteMessage(r -> r.queueUrl(url).receiptHandle(message.receiptHandle()));
}
}
assertTrue(delivered, "Expected an S3 notification for the uploaded object");
}
}
@Test
void signsAnAwsRequestAndVerifiesTheEmulatorCertificate() {
assertNull(System.getenv("AWS_ACCESS_KEY_ID"));
assertNull(System.getenv("AWS_SECRET_ACCESS_KEY"));
assertNull(System.getenv("AWS_PROFILE"));
assertNull(System.getProperty("aws.accessKeyId"));
assertNull(System.getProperty("aws.secretAccessKey"));
// Endpoint, credentials, region, and TLS trust come from the plugin.
try (StsClient sts = StsClient.builder().httpClientBuilder(UrlConnectionHttpClient.builder()).build()) {
var identity = sts.getCallerIdentity();
assertEquals("000000000000", identity.account());
assertEquals("arn:aws:iam::000000000000:user/emulator", identity.arn());
}
assertFalse(Boolean.getBoolean("example.fail"), "Intentional failure to demonstrate managed cleanup");
}
@Test
void readsAndWritesTheProvisionedBucket() {
try (S3Client s3 = S3Client.builder().forcePathStyle(true)
.overrideConfiguration(config -> config.putAdvancedOption(SdkAdvancedClientOption.DISABLE_HOST_PREFIX_INJECTION, true))
.httpClientBuilder(UrlConnectionHttpClient.builder()).build()) {
s3.putObject(request -> request.bucket("example-test-bucket").key("greeting.txt"), RequestBody.fromString("Hello emulator"));
assertEquals("Hello emulator", s3.getObjectAsBytes(request -> request.bucket("example-test-bucket").key("greeting.txt")).asUtf8String());
}
}
@Test
void sendsAndReceivesOnProvisionedStandardAndFifoQueues() {
try (SqsClient sqs = SqsClient.builder().httpClientBuilder(UrlConnectionHttpClient.builder()).build()) {
for (String name : new String[] {"example-test-queue", "example-events.fifo"}) {
String url = sqs.getQueueUrl(request -> request.queueName(name)).queueUrl();
sqs.sendMessage(request -> {
request.queueUrl(url).messageBody("Hello queue");
if (name.endsWith(".fifo")) request.messageGroupId("example");
});
var messages = sqs.receiveMessage(request -> request.queueUrl(url).waitTimeSeconds(5)).messages();
assertEquals(1, messages.size());
assertEquals("Hello queue", messages.get(0).body());
sqs.deleteMessage(request -> request.queueUrl(url).receiptHandle(messages.get(0).receiptHandle()));
}
}
}
@Test
void readsPublishedFixturesAndTheFifoDeadletterPolicy() {
try (SqsClient sqs = SqsClient.builder().httpClientBuilder(UrlConnectionHttpClient.builder()).build()) {
String url = sqs.getQueueUrl(request -> request.queueName("example-seeded-queue")).queueUrl();
var bodies = sqs.receiveMessage(request -> request.queueUrl(url).maxNumberOfMessages(10).waitTimeSeconds(5))
.messages().stream().map(message -> message.body()).collect(Collectors.toSet());
assertEquals(Set.of("{\"event\":\"order-created\",\"orderId\":\"example-1\"}",
"{\"event\":\"order-shipped\",\"orderId\":\"example-1\"}"), bodies);
String fifoUrl = sqs.getQueueUrl(request -> request.queueName("example-events.fifo")).queueUrl();
String policy = sqs.getQueueAttributes(request -> request.queueUrl(fifoUrl).attributeNamesWithStrings("RedrivePolicy"))
.attributesAsStrings().get("RedrivePolicy");
assertTrue(policy.contains("example-events-dlq.fifo"));
}
}
}
View the message fixtures (src/integration/messages/events.jsonl)
{"event":"order-created","orderId":"example-1"}
{"event":"order-shipped","orderId":"example-1"}
The example deliberately configures invalid credentials before opting in. The plugin replaces those settings for the forked JVM. See credentials and TLS for the boundaries of this configuration.
Verify Cleanup After Failure
From the plugin repository root:
./gradlew -p examples/basic integrationTest -PfailExample=true
This command is expected to fail its test. The managed container is still removed after the build’s consumers finish.
Next, follow a service guide such as S3 or SQS to provision the resources your application needs, or start a persistent development instance.