Opt existing Test, JavaExec, or Exec tasks into the emulator with awsEmulator.useWith(taskProvider). One fresh managed instance is shared by the participating tasks in each project by default. Use useSharedRuntime to explicitly share an owner and resource setup across projects.
To use an already-running emulator, configure awsEmulator.external. The same consumer wiring applies. Both modes use that endpoint, and no external resources or connection source files are removed after the build.
For independent suites in one project, declare named runtimes and select them with useWith(task, "integration", setupTasks…) or useWith(task, "integration", EmulatorMode.DEVELOPMENT, setupTasks…). Existing overloads select default. useWithRuntime(task, runtimeNameProvider, modeProvider, setupTasks…) supports lazy selections. Typed setup tasks inherit the selected name unless explicitly assigned; conflicting names fail before execution. Reusable resource sets create separate tasks for each name and mode.
Opt In Tests
The method supports Gradle Test, JavaExec, and Exec tasks, including subclasses. Applying the plugin alone does not modify your tests. Prefer a separate integrationTest task for tests that need AWS so ordinary unit tests run independently of the emulator.
awsEmulator {
useWith(tasks.named<Test>("integrationTest"))
}
awsEmulator {
useWith(tasks.named<Test>("test"))
}
These snippets configure tasks that already exist. The plugin does not create integrationTest; the included example demonstrates creating a test source set and task.
Run A Java Application
For an existing JavaExec task, such as run from Gradle’s application plugin:
awsEmulator {
useWith(tasks.named<JavaExec>("run"))
}
The managed emulator stays available while that task consumes it. The optional Spring Boot companion adds local run and debug tasks.
Micronaut and Ktor use this same core integration for their existing run and test tasks. Runnable examples and compatibility tests cover framework consumers, resource setup, and both emulator lifetimes.
To select a persistent development instance and declare setup dependencies through the same core API:
awsEmulator.useWith(tasks.named<JavaExec>("run"), EmulatorMode.DEVELOPMENT, createResources)
Import io.github.gregwhitaker.awsemulator.model.EmulatorMode. Setup arguments accept Gradle dependency notation, including task providers and names. The mode may also be a Provider<EmulatorMode>. Configure resource tasks with the same mode as their consumer. Development instances require explicit stopAwsEmulator; one-argument useWith calls retain their managed behavior.
Run Python, Node, Or AWS CLI Commands
val pythonTests = tasks.register<Exec>("pythonTests") {
commandLine("python3", "-m", "pytest")
}
val cliIdentity = tasks.register<Exec>("cliIdentity") {
commandLine("aws", "sts", "get-caller-identity", "--no-cli-pager")
// Registered before useWith: runs after its connection setup, including on cache reuse.
doFirst { args("--endpoint-url", environment.getValue("AWS_ENDPOINT_URL")) }
}
awsEmulator {
useWith(pythonTests)
useWith(cliIdentity, EmulatorMode.DEVELOPMENT)
}
In Groovy, register with tasks.register('pythonTests', Exec) { commandLine 'python3', '-m', 'pytest' } and pass the provider to awsEmulator.useWith(pythonTests).
Exec receives the current connection environment immediately before launching: local endpoint, region, generated credential/config files, AWS_CA_BUNDLE, and NODE_EXTRA_CA_CERTS. Inherited AWS credentials, profiles, container-credential providers, and per-service endpoint overrides are removed. Setup tasks, resource sets, provider-selected modes, and shared runtime owners work as for JVM consumers. Nonzero process exits trigger ordinary managed cleanup unless the task explicitly ignores its exit value. Skipped tasks do not start an emulator themselves.
The plugin does not install external commands or SDKs. Use compatible SDKs with their normal environment providers; explicit client configuration can override the supplied values. Exec supplies environment values only; JVM system properties and combined JVM trust stores require Test or JavaExec. See connection exports for commands and IDE applications outside Gradle. The repository’s examples/processes build includes runnable Python/Node HTTPS probes and a signed AWS CLI STS call.
Provision Before Consumers Run
Pass the required resource tasks as setup arguments to useWith; it adds their task dependencies and checks their runtime selection. Their initial MANAGED default uses the same instance as useWith in that project. If you change awsEmulator.defaultMode, align each consumer with its resources by passing that property to useWith, or explicitly set the provisioning tasks to MANAGED for managed tests.
import io.github.gregwhitaker.awsemulator.aws.s3.CreateS3BucketTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode
val createBucket = tasks.register<CreateS3BucketTask>("createTestBucket") {
bucketName.set("application-test-data")
}
val tests = tasks.named<Test>("test")
awsEmulator {
useWith(tests, EmulatorMode.MANAGED, createBucket)
}
Resource setup tasks must use the same MANAGED or DEVELOPMENT mode as their consumer. Validation follows local prerequisites, including wrapper tasks and file-producing providers, and reports both task paths and modes before any selected task executes. It uses the final lazy mode selection and preserves configuration-cache reuse. Ordinary setup task modes are not changed automatically. A resource set creates separate tasks with the correct mode for each attachment.
Declare emulator setup through useWith to get this validation; unrelated Gradle dependsOn edges are not treated as setup declarations. Keep shared owner setup in shared resource sets.
See S3 bucket behavior for region selection and reuse. To provision queues before tests, see the SQS guide.
Execution And Cleanup
-
The service starts the managed emulator on demand and waits for HTTPS readiness.
-
The plugin supplies the child process’s endpoint, region, credential paths, and TLS trust at execution time.
-
Participating tasks selecting the same runtime name and mode in one project share an instance. Different projects receive separate instances unless they explicitly select the same runtime owner.
-
The service archives container logs under
.aws-emulator/logs/, then removes its managed container and connection files after consumers finish, including ordinary task or test failures. -
A skipped or
NO-SOURCEconsumer does not start an emulator itself. Its explicit provisioning dependencies can still execute.
Opted-in tasks with work always execute. Up-to-date skipping and build-cache reuse are disabled because each managed run starts with fresh external state. Configuration-cache reuse is supported: connection files are generated for the current execution instead of being stored in the configuration cache.
Parallel Builds
The default port value of 0 selects an available port for each instance, supporting concurrent projects and builds without additional configuration. With DIRECT, the plugin supplies that same nonzero port to Docker and the emulator. A competing process can still claim the selected port before Docker binds it; startup then fails and the plugin cleans up.
Tasks sharing an instance also share AWS resources. Use distinct bucket and queue names when tests run concurrently. A fixed port can also conflict with a development instance that remains running.
Use The Normal SDK Providers
Your application should use an AWS SDK that supports external endpoint configuration. The example verifies AWS SDK for Java v2 2.39.6.
Clients with explicit endpoint or credential configuration can override the plugin’s supplied values. JVM argument providers or options injected through the environment can also override them. See credentials, endpoints, and TLS before mixing emulator traffic with other HTTPS services.