Ktor uses the core io.github.gregwhitaker.aws-emulator plugin. Attach its existing Gradle run and test tasks with awsEmulator.useWith(…​); no additional emulator companion is required. Your application chooses its framework and AWS SDK versions.

The example uses Java 17+, Gradle 8.14+, a local Docker engine with Linux containers, and AWS SDK for Java v2. It performs signed HTTPS requests with normal certificate and hostname validation. No AWS account or AWS CLI is required.

Run The Example

From the repository root:

./gradlew -p examples/ktor test run --configuration-cache
./gradlew -p examples/ktor test run --configuration-cache

The example build provisions an SQS queue before the framework consumers start. Tests and application execution share a fresh managed instance within that project and build. The repeated command reuses the configuration cache while provisioning and consumers execute again. The managed container, generated credentials, and trust stores are removed after the consumers finish, including ordinary failures.

The example is an independent composite build. classes testClasses compiles it without Docker; test, run, and build require Docker. Applying the plugin or running help does not start an emulator.

Attach An Existing Application

First apply the core plugin from the Gradle Plugin Portal alongside your chosen framework plugins. This integration uses Gradle JavaExec and Test tasks:

Kotlin DSL
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode

val createQueue = tasks.register<CreateSqsQueueTask>("createApplicationQueue") {
    queueName.set("application-events")
}
awsEmulator {
    useWith(tasks.named<JavaExec>("run"), EmulatorMode.MANAGED, createQueue)
    useWith(tasks.named<Test>("test"), EmulatorMode.MANAGED, createQueue)
}
Groovy DSL
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode

def createQueue = tasks.register('createApplicationQueue', CreateSqsQueueTask) {
    queueName.set('application-events')
}
awsEmulator {
    useWith(tasks.named('run'), EmulatorMode.MANAGED, createQueue)
    useWith(tasks.named('test'), EmulatorMode.MANAGED, createQueue)
}

Task names above refer to tasks supplied by the application’s existing plugins. Only explicitly selected consumers receive the emulator connection. Setup task modes must match their consumers. See Tests & Java execution for source sets and additional consumer configuration.

Application And Test Integration

The Kotlin example applies the Kotlin JVM and Ktor Gradle plugins. Its main function starts a Netty server on a loopback port, requests /message, verifies the SQS round trip, and stops the server. Its JUnit 5 test uses Ktor’s testApplication engine to exercise the same route against the emulator.

The application creates an AWS SDK for Java v2 client using the normal endpoint, region, credential, and TLS settings. Blocking SDK calls run on Dispatchers.IO; the client closes when the application stops. Ktor does not need an AWS-specific configuration adapter for this setup.

View The Ktor Build
/*
 * 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.sqs.CreateSqsQueueTask
import io.github.gregwhitaker.awsemulator.model.EmulatorMode
import org.jetbrains.kotlin.gradle.dsl.JvmTarget

plugins {
    kotlin("jvm")
    id("io.ktor.plugin")
    id("io.github.gregwhitaker.aws-emulator")
}

repositories { mavenCentral() }

dependencies {
    implementation("io.ktor:ktor-server-core")
    implementation("io.ktor:ktor-server-netty")
    implementation(platform("software.amazon.awssdk:bom:2.39.6"))
    implementation("software.amazon.awssdk:sqs") {
        exclude(group = "software.amazon.awssdk", module = "apache-client")
        exclude(group = "software.amazon.awssdk", module = "netty-nio-client")
    }
    implementation("software.amazon.awssdk:url-connection-client")
    runtimeOnly("ch.qos.logback:logback-classic:1.5.21")
    testImplementation("io.ktor:ktor-server-test-host")
    testImplementation(platform("org.junit:junit-bom:5.11.4"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}
kotlin { compilerOptions { jvmTarget.set(JvmTarget.JVM_17) } }
application { mainClass.set("example.ApplicationKt") }

val applicationMode = providers.gradleProperty("development").map {
    if (it.toBoolean()) EmulatorMode.DEVELOPMENT else EmulatorMode.MANAGED
}.orElse(EmulatorMode.MANAGED)
val createApplicationQueue = tasks.register<CreateSqsQueueTask>("createApplicationQueue") {
    queueName.set("ktor-example-events")
    mode.set(applicationMode)
}
val createTestQueue = tasks.register<CreateSqsQueueTask>("createTestQueue") {
    queueName.set("ktor-example-events")
}
val run = tasks.named<JavaExec>("run") {
    systemProperty("example.fail", providers.gradleProperty("failExample").getOrElse("false"))
}
val tests = tasks.named<Test>("test") {
    useJUnitPlatform()
    systemProperty("example.fail", providers.gradleProperty("failExample").getOrElse("false"))
}

awsEmulator {
    useWith(run, applicationMode, createApplicationQueue)
    useWith(tests, EmulatorMode.MANAGED, createTestQueue)
}
View The HTTP Application And SQS Route
/*
 * 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 io.ktor.server.application.*
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withContext
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient
import software.amazon.awssdk.services.sqs.SqsClient
import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.time.Duration
import java.util.UUID

/** Starts a real HTTP server, exercises its SQS route, and shuts down. */
fun main() = runBlocking {
    val server = embeddedServer(Netty, host = "127.0.0.1", port = 0) { module() }.start(wait = false)
    try {
        val port = server.engine.resolvedConnectors().single().port
        val response = withContext(Dispatchers.IO) {
            HttpClient.newHttpClient().send(
                HttpRequest.newBuilder(URI("http://127.0.0.1:$port/message"))
                    .timeout(Duration.ofSeconds(30)).build(),
                HttpResponse.BodyHandlers.ofString()
            )
        }
        check(response.statusCode() == 200) { "Unexpected HTTP response: ${response.statusCode()}" }
        check(response.body().startsWith("Hello from Ktor: ")) { "Unexpected message: ${response.body()}" }
        println("Received from AWS Emulator: ${response.body()}")
        check(!java.lang.Boolean.getBoolean("example.fail")) { "Intentional application failure" }
    } finally {
        server.stop(0, 5000)
    }
}

/** The SDK reads the endpoint, region, credentials, and TLS settings supplied to this JVM. */
fun Application.module() {
    val sqs = SqsClient.builder().httpClientBuilder(UrlConnectionHttpClient.builder()).build()
    monitor.subscribe(ApplicationStopped) { sqs.close() }
    routing {
        get("/message") {
            val body = withContext(Dispatchers.IO) { roundTrip(sqs) }
            call.respondText(body)
        }
    }
}

private fun roundTrip(sqs: SqsClient): String {
    val url = sqs.getQueueUrl { it.queueName("ktor-example-events") }.queueUrl()
    val body = "Hello from Ktor: ${UUID.randomUUID()}"
    sqs.sendMessage { it.queueUrl(url).messageBody(body) }
    val message = sqs.receiveMessage { it.queueUrl(url).waitTimeSeconds(5) }.messages().firstOrNull()
        ?: error("Expected an SQS message")
    sqs.deleteMessage { it.queueUrl(url).receiptHandle(message.receiptHandle()) }
    check(message.body() == body) { "Unexpected SQS message: ${message.body()}" }
    return message.body()
}

Development, Debugging, And Failures

The example accepts -Pdevelopment=true for application runs:

./gradlew -p examples/ktor run -Pdevelopment=true --configuration-cache
./gradlew -p examples/ktor run -Pdevelopment=true --configuration-cache
./gradlew -p examples/ktor listSqsQueues
./gradlew -p examples/ktor stopAwsEmulator

The application still exits after its round trip. Its development emulator survives success or failure and is reused until explicitly stopped. test always uses a managed instance, even with -Pdevelopment=true. The example registers separate setup tasks so managed tests and development runs cannot accidentally target the same runtime.

To debug the example, run run --debug-jvm and attach to port 5005. Gradle suspends the JVM until a debugger connects. The emulator and queue are ready before the application JVM starts.

To exercise managed cleanup after application or test failure:

./gradlew -p examples/ktor run -PfailExample=true
./gradlew -p examples/ktor test -PfailExample=true

These commands intentionally fail after completing their SDK round trip.

Compatibility And Verification

Framework Docker-free compatibility fixtures Real-emulator fixtures

Ktor

3.5.2 and 3.6.1; Kotlin 2.4.21

Ktor 3.6.1

The Docker-free suite compiles the application and its tests, verifies setup ordering and runtime selection, and checks configuration-cache reuse without invoking Docker. It runs under the repository’s JDK/Gradle CI matrix. Override the example framework version with -PktorVersion=3.5.2 to reproduce the alternate fixture.

The real-emulator suite checks framework consumers, signed HTTPS, inherited credential/endpoint replacement, managed runtime sharing and failure cleanup, development reuse, and isolation between development runs and managed tests. Both suites copy the runnable example, so the documented sources are the compatibility fixture.

./gradlew :plugin:functionalTest --tests '*FrameworkCompatibilityFunctionalTest'
./gradlew :plugin:integrationTest --tests '*FrameworkIntegrationTest'

Verified support covers JVM run and Test consumers using AWS SDK for Java v2. Native images, Kotlin multiplatform or AWS SDK for Kotlin, and continuous restart or automatic reload workflows are outside this compatibility scope. IDE launches must delegate to the opted-in Gradle task to receive the generated connection. See Credentials & TLS for client-level overrides and trust configuration.