The SQS module supplies typed tasks for queues, deadletter queues, and message fixtures. All task types live in io.github.gregwhitaker.awsemulator.aws.sqs and use the AWS Emulator - SQS task group. Each task starts the selected emulator on demand and waits until it is ready.

Register Resource Tasks

Make your test task depend on provisioning, then opt that same consumer into the emulator. Provisioning tasks default to the shared managed instance.

Kotlin DSL

import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask

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

val createQueue = tasks.register<CreateSqsQueueTask>("createTestQueue") {
    queueName.set("application-test-events")
    attributes.put("VisibilityTimeout", "45")
}
val tests = tasks.named<Test>("test") {
    dependsOn(createQueue)
}
awsEmulator {
    useWith(tests)
}

Groovy DSL

import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask

plugins {
    id 'java'
    id 'io.github.gregwhitaker.aws-emulator' version '0.3.0'
}

def createQueue = tasks.register('createTestQueue', CreateSqsQueueTask) {
    queueName.set('application-test-events')
    attributes.put('VisibilityTimeout', '45')
}
def tests = tasks.named('test') {
    dependsOn(createQueue)
}
awsEmulator {
    useWith(tests)
}
Note
A managed provisioning task invoked alone creates resources that disappear when the build finishes. To keep resources available for a development session, select DEVELOPMENT mode.

Task Properties

All properties use Gradle’s lazy property API.

Task type Required Optional

CreateSqsQueueTask

queueName

attributes, mode, apiCallTimeoutSeconds

CreateSqsQueuesTask

queueNames

queueAttributes, mode, apiCallTimeoutSeconds

CreateSqsQueueWithDlqTask

queueName

queueAttributes, deadletterQueueName, deadletterQueueAttributes, maxReceiveCount (default 1), mode, apiCallTimeoutSeconds

ListSqsQueuesTask

None

prefix, mode, apiCallTimeoutSeconds

PurgeSqsQueuesTask

queueNames

mode, apiCallTimeoutSeconds

DeleteSqsQueuesTask

queueNames

mode, apiCallTimeoutSeconds

PublishSqsTask

queueNames, messages

messageGroupId (required for FIFO), mode, apiCallTimeoutSeconds

Shared property Default Meaning

mode

awsEmulator.defaultMode for custom instances (initially MANAGED)

Select the build-owned runtime or the persistent DEVELOPMENT runtime. The module convenience tasks default to DEVELOPMENT.

runtimeName

default

Select a declared named runtime. Its name and lifecycle mode must match the consumer; see named runtimes.

apiCallTimeoutSeconds

30

Positive timeout for each SDK operation, including retries.

Provisioning tasks always execute and are never restored from the build cache because they operate on live emulator state. The plugin supplies its own SDK dependencies for these tasks; the application declares its own dependencies.

SQS Queue Behavior

CreateSqsQueueTask and CreateSqsQueuesTask support standard and FIFO queues. The singular task uses attributes; the bulk task uses queueAttributes. Both maps use AWS attribute names and string values.

An existing queue is reused when the explicitly requested attribute values match. A mismatch fails the task without changing or purging the queue. Unspecified attributes keep their existing values. Comparisons use the returned strings, including JSON-valued attributes; semantically equivalent JSON with different formatting can still differ.

AWS service errors remain build failures.

FIFO Queues

Provide both a .fifo suffix and FifoQueue = true:

val createFifo = tasks.register<CreateSqsQueueTask>("createTestFifo") {
    queueName.set("application-events.fifo")
    attributes.put("FifoQueue", "true")
    attributes.put("ContentBasedDeduplication", "true")
}

Add createFifo to your consumer’s dependsOn(…​) list to create the queue before it runs.

Bulk Creation

import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueuesTask

val createQueues = tasks.register<CreateSqsQueuesTask>("createTestQueues") {
    queueNames.set(listOf("application-events", "application-notifications"))
    queueAttributes.put("VisibilityTimeout", "45")
}

queueNames is a ListProperty<String>. Bulk creation uses the singular task’s FIFO, reuse, and attribute checks. All names are validated before starting the emulator. Duplicate names are processed once.

Deadletter Queues

import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueWithDlqTask

val createOrders = tasks.register<CreateSqsQueueWithDlqTask>("createOrdersQueue") {
    queueName.set("application-orders.fifo")
    queueAttributes.put("FifoQueue", "true")
    maxReceiveCount.set(3)
}

deadletterQueueName defaults to <queue>-dlq, inserting -dlq before the .fifo suffix for FIFO queues. The example creates application-orders-dlq.fifo. A FIFO source infers FifoQueue=true for its DLQ. Both queues must have the same type and different names. Configure optional DLQ attributes with deadletterQueueAttributes.

The task creates or reuses the DLQ, reads its ARN from SQS, and sets the source’s redrive policy. An existing source queue receives the requested queueAttributes and policy without being recreated; existing messages remain subject to those attributes, such as retention. An existing DLQ must match explicitly configured DLQ attributes. This differs from ordinary queue creation, which verifies existing source attributes without changing them.

maxReceiveCount defaults to 1 and accepts 1 through 1000. Set deadletterQueueName and maxReceiveCount instead of providing RedrivePolicy in queueAttributes.

Publish Message Fixtures

Use the createOrders task from Deadletter Queues as the publisher’s dependency:

import io.github.gregwhitaker.awsemulator.aws.sqs.PublishSqsTask

val publishOrders = tasks.register<PublishSqsTask>("publishTestOrders") {
    dependsOn(createOrders)
    queueNames.add("application-orders.fifo")
    messages.from(layout.projectDirectory.dir("src/integration/messages"))
    messageGroupId.set("integration-tests")
}
tasks.named<Test>("test") {
    dependsOn(publishOrders)
}
awsEmulator { useWith(tasks.named<Test>("test")) }

messages is a ConfigurableFileCollection. It accepts UTF-8 files, recursively visited directories, and .tar.gz or .tgz archives. Every nonempty line becomes one message sent to each selected queue. Whitespace is preserved; blank lines are skipped. Files are processed in path order, archive entries in archive order. Hidden directory/archive entries and symlinks encountered inside directories are skipped. Archives are read directly without extraction.

The task validates input before publishing: unreadable files, corrupt archives, malformed UTF-8, invalid SQS characters, and lines exceeding the 1 MiB service limit fail the build. The queue can impose a smaller maximum. All queue URLs are resolved before the first send. An SDK failure stops publishing, but earlier successful sends remain; rerunning can send duplicates.

FIFO queues require messageGroupId. Every FIFO delivery receives a unique deduplication ID, preserving repeated identical lines as separate fixture messages. The publisher executes again on configuration-cache reuse, just like other resource tasks.

Module Convenience Tasks

The SQS module registers these tasks in the AWS Emulator - SQS group. They use the persistent development emulator by default:

Task CLI options

listSqsQueues

Optional --prefix=application-

purgeSqsQueues

--queueNames=one,two

deleteSqsQueues

--queueNames=one,two

publishSqs

--queueNames=one,two, --message=path, optional --messageGroupId=group

Every resource task accepts --mode=MANAGED or --mode=DEVELOPMENT and --runtime <name>. Custom instances inherit awsEmulator.defaultMode, initially MANAGED. Ensure provisioning and consuming tasks select the same runtime name and mode.

./gradlew listSqsQueues --prefix=application-
./gradlew publishSqs --queueNames=application-events --message=src/integration/messages
./gradlew purgeSqsQueues --queueNames=application-events
./gradlew deleteSqsQueues --queueNames=application-events,application-orders.fifo

Listing And Cleanup

SQS listing follows all response pages and prints queue names, URLs, and approximate available message counts. Purging resolves all selected names before requesting removal of their messages; it keeps the queues. The SQS purge API can take up to 60 seconds to remove available and in-flight messages. The task returns when the service accepts the requests and propagates service errors.

DeleteSqsQueuesTask deletes explicitly named standard or FIFO queues and their messages. It requires a nonempty queueNames list, validates every name before connecting, and processes duplicates once. It does not discover queues by prefix or delete related DLQs automatically. Select a DLQ explicitly when you want to remove it too.

import io.github.gregwhitaker.awsemulator.aws.sqs.DeleteSqsQueuesTask

tasks.register<DeleteSqsQueuesTask>("deleteFixtureQueues") {
    queueNames.set(listOf("application-events", "application-orders.fifo"))
}

Missing queues succeed, including a queue removed between lookup and deletion. The task resolves all selected names before its first delete; other lookup failures stop it without deleting any selected queues. A deletion failure propagates immediately and can leave earlier deletions applied. This is not an atomic operation. The task returns after request acceptance, without waiting for disappearance or immediate name reuse; AWS deletion can take up to 60 seconds. Custom tasks inherit awsEmulator.defaultMode; deleteSqsQueues defaults to DEVELOPMENT. Both always execute, including on configuration-cache reuse. Deletion tasks are not Spring Boot automatic setup tasks.

SDK Connection Isolation

Provisioning clients use explicit emulator endpoints, regions, generated credentials, and per-client TLS trust. They bypass inherited proxy settings. They do not modify the Gradle daemon’s credentials or global SSL configuration, and they do not require the AWS CLI.