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

build.gradle.kts
plugins {
    java
    id("io.github.gregwhitaker.aws-emulator") version "0.3.0"
}

awsEmulator {
    useWith(tasks.named<Test>("test"))
}

Groovy DSL

build.gradle
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.

settings.gradle.kts
pluginManagement {
    includeBuild("../gradle-aws-emulator")
}
settings.gradle
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.

examples/basic/settings.gradle.kts
/*
 * 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.