Use typed data tasks on their own, or combine provisioning and fixtures into a named development scenario. The plugin creates an ordinary Gradle dependency graph, so failures propagate and configuration-cache reuse still runs the live resource operations.

Try The Example

From the repository root, with Docker running:

./gradlew -p examples/scenarios seedAwsEmulator --configuration-cache
./gradlew -p examples/scenarios verifyScenario --configuration-cache
./gradlew -p examples/scenarios resetAwsEmulator -PawsEmulator.scenario=empty
./gradlew -p examples/scenarios resetAwsEmulatorFailedOrders
./gradlew -p examples/scenarios stopAwsEmulator

The runnable example defines demo, empty, and failed-orders. demo loads files and products; empty creates resources without data; failed-orders loads a failed payment record.

Upload And Inspect S3 Objects

import io.github.gregwhitaker.awsemulator.aws.s3.*

val createAssets = tasks.register<CreateS3BucketTask>("createAssets") {
    bucketName.set("application-assets")
}
val uploadAssets = tasks.register<UploadS3DirectoryTask>("uploadAssets") {
    dependsOn(createAssets)
    bucketName.set(createAssets.flatMap { it.bucketName })
    sourceDirectory.set(layout.projectDirectory.dir("fixtures/assets"))
    prefix.set("assets")
    contentTypes.put("json", "application/json")
    metadata.put("fixture", "local-development")
}

fixtures/assets/nested/example.json becomes assets/nested/example.json. Relative paths are preserved, directory traversal is deterministic, and a missing trailing slash is added to a nonempty prefix. Symbolic links in fixture directories are rejected. An empty directory uploads nothing.

Common extensions have fixed MIME mappings: JSON, plain text, CSV, HTML, CSS, JavaScript, XML, PDF, SVG, PNG, JPEG, GIF, and WebP. Unknown extensions use application/octet-stream. contentTypes overrides use lowercase extensions without a dot. UploadS3ObjectTask.contentType overrides inference for one file. User metadata is passed to S3 alongside the content type.

Uploads replace objects at matching keys and preserve other objects. They do not synchronize deletions. Use PurgeS3BucketsTask or a scenario reset for a clean bucket.

Task type Required properties Optional properties

UploadS3ObjectTask

bucketName, objectKey, sourceFile

contentType, metadata (empty)

UploadS3DirectoryTask

bucketName, sourceDirectory

prefix (empty), contentTypes (empty), metadata (empty)

ListS3ObjectsTask

bucketName

prefix (empty)

DownloadS3ObjectTask

bucketName, objectKey, outputFile

None

All four types also accept mode and apiCallTimeoutSeconds. Custom instances inherit awsEmulator.defaultMode, initially MANAGED. Buckets must exist before object tasks execute; declare dependsOn on their creation tasks.

The registered listS3Objects command defaults to DEVELOPMENT, follows all response pages, and prints keys and sizes:

./gradlew listS3Objects --bucketName=application-assets --prefix=assets/

Register downloads with an explicit local output file. Object keys are never interpreted as filesystem paths. The destination is replaced only after the full download succeeds. Downloads rerun even when the local file already exists.

Seed And Clear DynamoDB Items

PutDynamoDbItemsTask reads a JSON array of DynamoDB attribute maps. An empty array is valid and writes no items, allowing empty-table exports to be replayed. Use explicit AttributeValue type tags to preserve number precision, binary data, sets, lists, and maps:

fixtures/products.json
[
  {
    "id": {"S": "book"},
    "price": {"N": "12.50"},
    "available": {"BOOL": true},
    "tags": {"SS": ["demo", "books"]},
    "details": {"M": {"ratings": {"L": [{"N": "5"}, {"N": "4"}]}}},
    "attachment": {"B": "AAH/"}
  }
]
import io.github.gregwhitaker.awsemulator.aws.dynamodb.PutDynamoDbItemsTask

// createProducts is a CreateDynamoDbTableTask; see the DynamoDB table guide.
val seedProducts = tasks.register<PutDynamoDbItemsTask>("seedProducts") {
    dependsOn(createProducts)
    tableName.set(createProducts.flatMap { it.tableName })
    itemsFile.set(layout.projectDirectory.file("fixtures/products.json"))
}

The parser validates the whole fixture before sending any writes, rejects duplicate JSON fields and invalid type values, and limits fixture files to 16 MiB. Each entry needs the table’s complete primary key. Duplicate primary keys are rejected before any writes. Fixture parsing errors omit values.

Imports replace the entire existing item when its primary key matches; other items remain. The task sends batches of up to 25 writes and retries only unprocessed items with exponential backoff capped at 2 seconds. maxRetries defaults to 8; retryDelayMillis defaults to 100. These retries supplement the SDK’s request retries. Batch imports are not transactional: a failure can leave earlier writes applied. DynamoDB’s per-item limits still apply. See BatchWriteItem behavior.

PurgeDynamoDbTableTask scans primary keys across every page, then deletes those items in batches. It preserves the table and indexes and uses the same retry properties. Stop writers while clearing a table; items written after the scan are not included. The registered development command requires an explicit table name:

./gradlew purgeDynamoDbTable --tableName=application-products

Both item task types accept tableName, mode, apiCallTimeoutSeconds, maxRetries, and retryDelayMillis. PutDynamoDbItemsTask additionally requires itemsFile. Custom instances inherit awsEmulator.defaultMode, initially MANAGED; the registered purge command uses DEVELOPMENT.

Reuse Resources Across Tests And Development

Declare task configurations in awsEmulator.resourceSets to use the same resource and fixture definitions with managed tests, local Boot runs, and development scenarios:

import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask
import io.github.gregwhitaker.awsemulator.aws.sqs.PublishSqsTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode

val applicationResources = awsEmulator.resourceSets.register("application") {
    provision("queue", CreateSqsQueueTask::class.java) {
        queueName.set("application-events")
    }
    seed("messages", PublishSqsTask::class.java) {
        queueNames.add("application-events")
        messages.from(layout.projectDirectory.file("fixtures/messages.txt"))
    }
}
awsEmulator {
    useWith(tasks.named<Test>("test"), EmulatorMode.MANAGED, applicationResources)
    scenarios { register("default") { resources(applicationResources) } }
    // With the Spring Boot companion applied:
    springBoot { resourceSets.add(applicationResources) }
}

The equivalent definition and attachments in Groovy:

def applicationResources = awsEmulator.resourceSets.register('application') {
    provision('queue', CreateSqsQueueTask) { queueName.set('application-events') }
    seed('messages', PublishSqsTask) {
        queueNames.add('application-events')
        messages.from(layout.projectDirectory.file('fixtures/messages.txt'))
    }
}
awsEmulator {
    useWith(tasks.named('test'), EmulatorMode.MANAGED, applicationResources)
    scenarios { register('default') { resources(applicationResources) } }
    springBoot { resourceSets.add(applicationResources) }
}

Definitions use the existing typed tasks and their lazy properties. The attachment selects and locks runtimeName and mode; do not set them inside a definition. All provisioning steps run in declaration order, followed by all fixture steps in declaration order, even if a fixture was declared first. Failure skips dependent steps, including with --continue. Names start with a lowercase letter and contain letters, numbers, or single hyphens; step names must be unique within a set.

Compose shared prerequisites with include(otherSetProvider). Included sets complete, including their fixtures, before this set’s steps. Separate included sets have no implicit order between them; express dependencies with nested includes. Cycles are rejected. Multiple sets attached to a consumer are independent; use includes for dependencies instead of references to generated task names or tasks in another mode. Sets must belong to the consumer’s project.

Only selected sets are materialized. A set creates one task graph per project, runtime name, and mode, reused by every attachment selecting that pair. Different named runtimes and managed/development graphs can execute in the same invocation with separate task instances. Consumers in the same runtime name and mode share resources and fixture execution; use separate resource names for concurrent tests sharing an instance. Resource operations always rerun on subsequent builds, including configuration-cache reuse. Set declarations become immutable once their task dependencies are resolved.

The Boot companion excludes generated resource-set tasks from automatic discovery. Attach sets explicitly with springBoot.resourceSets; these attachments also run when autoCreateResources is false. Ordinary resource task discovery is unchanged.

The scenario example uses includes to share its bucket, table, and S3 fixtures across datasets. Run managed verification and a development reset together:

./gradlew -p examples/scenarios resetAwsEmulator verifyFixtures --configuration-cache
./gradlew -p examples/scenarios stopAwsEmulator

Define Development Scenarios

Prefer resources(setProvider) for definitions shared with managed tests or Boot runs. Existing task-based scenarios remain supported:

awsEmulator {
    defaultScenario.set("demo")
    scenarios {
        register("demo") {
            provision(createAssets, createProducts)
            seed(uploadAssets, seedProducts)
        }
        register("empty") {
            provision(createAssets, createProducts)
        }
    }
}

The same methods work in Groovy:

awsEmulator {
    defaultScenario.set('demo')
    scenarios {
        register('demo') {
            provision(createAssets, createProducts)
            seed(uploadAssets, seedProducts)
        }
        register('empty') { provision(createAssets, createProducts) }
    }
}

Provisioning follows the tasks' dependsOn relationships; unrelated provisioning tasks can run in parallel. Every seed waits for all provisioning, and seeds run in declaration order. A provisioning or seed failure skips dependent seeds, including with --continue.

Only the selected scenario’s resource tasks are added to the command’s dependency graph. Its explicit resource tasks and resource prerequisites are bound to DEVELOPMENT for that invocation and leave the emulator running. They must belong to the same Gradle project. Do not use those same explicit task instances for managed consumers in the same invocation; use reusable resource sets for separate mode-specific instances. Existing scenarios can share task providers across separate invocations. If a scenario combines resource sets and explicit tasks, its sets complete before its explicit provisioning and seeding.

Scenarios select the default runtime unless configured with runtimeName.set("integration"). Declare that name in awsEmulator.runtimes first. Choose one scenario per runtime name per Gradle invocation; scenarios targeting different named runtimes can run together. See named runtimes for a complete example. Scenario names start with a lowercase letter and contain letters, numbers, or single hyphens. Names must produce distinct generated task names: failed-orders becomes FailedOrders.

Command Behavior

seedAwsEmulator

Start or reuse the development instance, provision resources, and seed the selected scenario. Preserve unrelated state.

resetAwsEmulator

Apply the selected reset scope, then provision and seed the selected scenario. The default scope is RUNTIME.

seedAwsEmulatorDemo

Seed demo regardless of the default or selection property.

resetAwsEmulatorDemo

Reset and seed demo explicitly, using its reset scope.

cleanAwsEmulator

Run only explicit cleanup for the selected scenario; preserve the runtime and omit provisioning/seeding.

cleanAwsEmulatorDemo

Run only `demo’s explicit cleanup.

-PawsEmulator.scenario=<name> selects a scenario for the generic commands and takes precedence over awsEmulator.defaultScenario. The default name is default; it must be registered, or set defaultScenario to a registered name. Unknown names fail before lifecycle tasks execute. Listing tasks and requesting help do not start Docker.

Important
The default RUNTIME reset scope removes all resources in the selected development emulator, including resources outside the selected scenario and in other services. It then reloads only the chosen scenario. With shared ownership, this affects every application using that named development instance; define and run shared scenarios in the owner project. Reset does not affect the separate managed instance, other named runtimes, or a different owner’s emulator. Use resource-scoped reset with explicit cleanup to retain unrelated resources. Seed alone does not remove old data.

restartAwsEmulator retains its existing behavior: restart with empty state, without provisioning or fixtures. RUNTIME reset builds on that lifecycle operation; it is not a persisted snapshot.

Selective Reset And Cleanup

Define cleanup alongside each resource set’s provisioning and fixtures. Cleanup uses ordinary typed resource tasks and explicit resource names; the plugin does not infer ownership, discover all resources, or automatically delete resources mentioned by provisioning tasks.

import io.github.gregwhitaker.awsemulator.aws.s3.DeleteS3BucketsTask
import io.github.gregwhitaker.awsemulator.aws.dynamodb.DeleteDynamoDbTableTask
import io.github.gregwhitaker.awsemulator.model.ScenarioResetScope

val infrastructure = awsEmulator.resourceSets.register("infrastructure") {
    // Add the corresponding provision(...) steps here.
    cleanup("remove-assets", DeleteS3BucketsTask::class.java) {
        buckets.add("scenario-assets")
        force.set(true)
    }
    cleanup("remove-products", DeleteDynamoDbTableTask::class.java) {
        tableName.set("scenario-products")
        ignoreMissing.set(true)
    }
}
awsEmulator.scenarios.register("demo") {
    resources(infrastructure)
    resetScope.set(ScenarioResetScope.RESOURCES)
}

In Groovy, use cleanup('remove-assets', DeleteS3BucketsTask) { …​ } and resetScope.set(ScenarioResetScope.RESOURCES). Existing task-based scenarios can declare cleanup(deleteAssets, deleteProducts) using task providers. Keep cleanup and provisioning in separate tasks; cleanup must not depend on provisioning or seeding. Do not refer to generated task names.

resetScope defaults to ScenarioResetScope.RUNTIME. -PawsEmulator.resetScope=RESOURCES or RUNTIME overrides the selected scenario’s setting for reset commands; values are case-insensitive. Invalid scopes fail before lifecycle actions. seedAwsEmulator never runs cleanup. cleanAwsEmulator always uses explicit resource cleanup and ignores reset scope.

./gradlew -p examples/scenarios resetAwsEmulator -PawsEmulator.resetScope=RESOURCES
./gradlew -p examples/scenarios resetAwsEmulator -PawsEmulator.resetScope=RESOURCES -PawsEmulator.scenario=empty
./gradlew -p examples/scenarios cleanAwsEmulator

Resource-scoped reset runs all cleanup before any resource provisioning or seeding. Explicit scenario cleanup runs first, in declaration order. Resource-set cleanup then runs from dependents to included prerequisites; a shared included set is cleaned once. Steps within a set run in declaration order. Cleanup failure blocks subsequent cleanup and all provisioning/seeding, including with --continue. Resource-scoped reset and clean reject scenarios with no cleanup steps; sets with no cleanup declarations contribute no deletions. Only the selected scenario’s cleanup runs, so scenarios that switch between datasets should include the same cleanup definitions.

The selected development runtime is started or reused without restarting it; external runtimes are connected to without lifecycle commands. Cleanup tasks inherit and lock the selected runtime name and DEVELOPMENT mode. Resources outside the explicit cleanup selections remain, including those used by other applications sharing the runtime. Cleanup is not transactional: earlier deletions remain if a later step fails. Choose idempotent deletion tasks for repeatable cleanup. S3 bucket deletion tolerates absent buckets; DynamoDB table deletion needs ignoreMissing.set(true). A purge step can preserve resource configuration instead, but requires the resource to exist.

Use a single reset command when cleanup must be followed by seeding. As with ordinary Gradle tasks, listing clean and seed separately on the command line does not itself express a dependency between them. Cleanup steps run only when requested by these commands; attaching a resource set to managed tests or Boot does not clean a development environment.

Export And Replay A Dataset

Export selected live data into portable fixture files, then provision the same resource definitions and replay them. These files capture S3 objects and DynamoDB items. They do not capture a whole emulator, resource definitions, or data from other AWS services. In particular, SQS queue messages are not exported because reading them changes delivery state and cannot provide a complete, consistent queue snapshot.

Task type Required properties Behavior

ExportS3ObjectsTask

bucketName, outputFile

Export current objects in the explicit bucket. Optional prefix defaults to empty and is a literal key prefix.

ReplayS3ObjectsTask

bucketName, objectsFile

Replay exported object data into an existing bucket, replacing matching keys and preserving other keys.

ExportDynamoDbItemsTask

tableName, outputFile

Scan all table items with consistent reads and export typed AttributeValue JSON.

PutDynamoDbItemsTask

tableName, itemsFile

Replay exported items into an existing table; replace matching primary keys and preserve other items.

Register these task types in your build. They accept runtimeName, mode, and apiCallTimeoutSeconds (default 30). Custom instances inherit awsEmulator.defaultMode, initially MANAGED. Exports require an already active runtime and never start an owned emulator. For development captures set mode to DEVELOPMENT; for managed captures schedule exports after setup or as consumer finalizers, before managed cleanup. All tasks execute on configuration-cache reuse and remain excluded from up-to-date skipping and build-cache reuse.

import io.github.gregwhitaker.awsemulator.aws.s3.ExportS3ObjectsTask
import io.github.gregwhitaker.awsemulator.aws.s3.ReplayS3ObjectsTask
import io.github.gregwhitaker.awsemulator.aws.dynamodb.ExportDynamoDbItemsTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode

val capturedObjects = layout.projectDirectory.file("fixtures/captured-objects.json")
tasks.register<ExportS3ObjectsTask>("captureAssets") {
    mode.set(EmulatorMode.DEVELOPMENT)
    bucketName.set("scenario-assets")
    outputFile.set(capturedObjects)
}
tasks.register<ExportDynamoDbItemsTask>("captureProducts") {
    mode.set(EmulatorMode.DEVELOPMENT)
    tableName.set("scenario-products")
    outputFile.set(layout.projectDirectory.file("fixtures/captured-items.json"))
}
tasks.register<ReplayS3ObjectsTask>("replayAssets") {
    mode.set(EmulatorMode.DEVELOPMENT)
    bucketName.set("scenario-assets")
    objectsFile.set(capturedObjects)
}

Use file paths for replay inputs, as above. Wiring replay to an export task’s output provider adds an implicit dependency and recaptures data before replay. Add provisioning dependencies to replay tasks, or use a scenario’s seed steps. For an exact dataset, clean the selected resources before provisioning and replay; replay alone does not delete extra objects or items.

The scenario example captures both files under build/fixtures/scenario/ and defines a replay scenario. Run export and replay as separate invocations:

./gradlew -p examples/scenarios seedAwsEmulator
./gradlew -p examples/scenarios exportScenario --configuration-cache
./gradlew -p examples/scenarios resetAwsEmulatorReplay -PawsEmulator.resetScope=RESOURCES --configuration-cache
./gradlew -p examples/scenarios stopAwsEmulator

Export follows every listing/scan page and rejects missing or repeated continuation tokens. Output ordering is deterministic for unchanged fixture values. Each file has a 16 MiB limit, including JSON and base64 overhead. A failed or oversized export leaves the previous file intact; a successful empty export replaces it with an empty dataset. Each artifact is replaced after its complete export succeeds; exporting multiple artifacts is not atomic across services. Stop application writers during capture and replay. Even consistent DynamoDB scans do not provide snapshot isolation.

S3 fixtures have the following versioned format. body is base64, contentType is optional, and metadata contains string values. Keys are retained verbatim as JSON data and never become local filesystem paths. Replay validates the entire file, rejects duplicate fields/keys, unknown fields/versions and malformed data before connecting. Writes can still fail partway through; earlier writes remain.

{"schemaVersion":1,"objects":[{"key":"assets/example.bin","body":"AAH/","contentType":"application/octet-stream","metadata":{"fixture":"captured"}}]}

Only current S3 object bytes, keys, content types, and user metadata are captured. Historical versions, delete markers, ACLs, tags, encryption settings, other HTTP headers, and bucket policies/versioning/notifications are excluded. Replaying into a versioned bucket creates new versions; identities, timestamps and ETags are not restored. DynamoDB exports use the same JSON array as regular item fixtures, preserve numbers as strings and binary/set/map/list types, and omit table/index/stream configuration. Empty S3 objects and DynamoDB arrays are valid and replay without writes.

Unlike metadata reports, exported fixtures contain actual object and item data in plaintext/base64. Choose the output location and share or commit those files deliberately. The tasks log counts and resource names, not fixture contents.

Start Application Tasks After Seeding

Add the scenario command as setup for a development consumer:

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

awsEmulator {
    useWith(tasks.named<JavaExec>("run"), EmulatorMode.DEVELOPMENT, "seedAwsEmulator")
}

You can also reference a generated scenario task directly, such as seedAwsEmulatorDemo. For managed tests, pass a resource-set provider to useWith in MANAGED mode. The example’s verifyFixtures task demonstrates reusing the demo definitions in a separate managed instance.