TestApplicationEngine

class TestApplicationEngine : 
    BaseApplicationEngine,
    CoroutineScope

ktor test engine that provides way to simulate application calls to existing application module(s) without actual HTTP connection

Types

Configuration

class Configuration : Configuration

Test application engine configuration

Constructors

<init>

TestApplicationEngine(
    environment: ApplicationEngineEnvironment = createTestEnvironment(),
    configure: Configuration.() -> Unit = {})

ktor test engine that provides way to simulate application calls to existing application module(s) without actual HTTP connection

Properties

callInterceptor

var callInterceptor: PipelineInterceptor<Unit, ApplicationCall>

interceptor for engine calls. can be modified to emulate certain engine behaviour (e.g. error handling)

client

val client: HttpClient

A client instance connected to this test server instance. Only works until engine stop invocation.

coroutineContext

val coroutineContext: <ERROR CLASS>

Inherited Properties

environment

instance of ApplicationEngineEnvironment for this engine

pipeline

val pipeline: EnginePipeline

pipeline to use with this engine

Functions

createCall

fun createCall(
    readResponse: Boolean = false,
    setup: TestApplicationRequest.() -> Unit
): TestApplicationCall

Creates an instance of test call but doesn’t start request processing

handleRequest

fun handleRequest(
    setup: TestApplicationRequest.() -> Unit
): TestApplicationCall

Make a test request

handleWebSocket

fun handleWebSocket(
    uri: String,
    setup: TestApplicationRequest.() -> Unit
): TestApplicationCall

Make a test request that setup a websocket session and wait for completion

handleWebSocketConversation

fun handleWebSocketConversation(
    uri: String,
    setup: TestApplicationRequest.() -> Unit = {},
    callback: suspend TestApplicationCall.(incoming: ReceiveChannel<Frame>, outgoing: SendChannel<Frame>) -> Unit
): TestApplicationCall

Make a test request that setup a websocket session and invoke callback function that does conversation with server

hookRequests

fun hookRequests(
    processRequest: TestApplicationRequest.(setup: TestApplicationRequest.() -> Unit) -> Unit,
    processResponse: TestApplicationCall.() -> Unit,
    block: () -> Unit
): Unit

Install a hook for test requests

start

fun start(wait: Boolean): ApplicationEngine

Starts this ApplicationEngine

stop

fun stop(gracePeriodMillis: Long, timeoutMillis: Long): Unit

Stops this ApplicationEngine

Extension Functions

addShutdownHook

fun ApplicationEngine.addShutdownHook(stop: () -> Unit): Unit

Adds automatic JVM shutdown hooks management. Should be used before starting the engine. Once JVM termination noticed, stop block will be executed. Please note that a shutdown hook only registered when the application is running. If the application is already stopped then there will be no hook and no stop function invocation possible. So stop block will be called once or never.

cookiesSession

fun TestApplicationEngine.cookiesSession(
    callback: () -> Unit
): Unit

Keep cookies between requests inside the callback.

decodeChunked

fun CoroutineScope.decodeChunked(
    input: ByteReadChannel
): DecoderJob
fun CoroutineScope.decodeChunked(
    input: ByteReadChannel,
    contentLength: Long
): DecoderJob

Start a chunked stream decoder coroutine

embeddedServer

fun <TEngine : ApplicationEngine, TConfiguration : Configuration> CoroutineScope.embeddedServer(
    factory: ApplicationEngineFactory<TEngine, TConfiguration>,
    port: Int = 80,
    host: String = "0.0.0.0",
    watchPaths: List<String> = emptyList(),
    parentCoroutineContext: <ERROR CLASS> = EmptyCoroutineContext,
    configure: TConfiguration.() -> Unit = {},
    module: Application.() -> Unit
): TEngine

Creates an embedded server with the given factory, listening on host:port

handleRequest

fun TestApplicationEngine.handleRequest(
    method: HttpMethod,
    uri: String,
    setup: TestApplicationRequest.() -> Unit = {}
): TestApplicationCall

Make a test request

httpServer

fun CoroutineScope.httpServer(
    settings: HttpServerSettings,
    handler: HttpRequestHandler
): HttpServer

Start an http server with settings invoking handler for every request

parseMultipart

fun CoroutineScope.parseMultipart(
    input: ByteReadChannel,
    headers: HttpHeadersMap
): ReceiveChannel<MultipartEvent>
fun CoroutineScope.parseMultipart(
    input: ByteReadChannel,
    contentType: CharSequence,
    contentLength: Long?
): ReceiveChannel<MultipartEvent>
fun CoroutineScope.parseMultipart(
    boundaryPrefixed: ByteBuffer,
    input: ByteReadChannel,
    totalLength: Long?
): ReceiveChannel<MultipartEvent>

Starts a multipart parser coroutine producing multipart events

pinger

fun CoroutineScope.pinger(
    outgoing: SendChannel<Frame>,
    period: Duration,
    timeout: Duration,
    pool: ObjectPool<ByteBuffer> = KtorDefaultPool
): SendChannel<Pong>

Launch pinger coroutine on CoroutineScope that is sending ping every specified period to outgoing channel, waiting for and verifying client’s pong frames. It is also handling timeout and sending timeout close frame

fun CoroutineScope.pinger(
    outgoing: SendChannel<Frame>,
    periodMillis: Long,
    timeoutMillis: Long,
    pool: ObjectPool<ByteBuffer> = KtorDefaultPool
): SendChannel<Pong>

Launch pinger coroutine on CoroutineScope that is sending ping every specified periodMillis to outgoing channel, waiting for and verifying client’s pong frames. It is also handling timeoutMillis and sending timeout close frame

pinger

fun CoroutineScope.pinger(
    outgoing: SendChannel<Frame>,
    period: <ERROR CLASS>,
    timeout: <ERROR CLASS>,
    pool: ObjectPool<ByteBuffer> = KtorDefaultPool
): SendChannel<Pong>

Launch pinger coroutine on CoroutineScope that is sending ping every specified period to outgoing channel, waiting for and verifying client’s pong frames. It is also handling timeout and sending timeout close frame

ponger

fun CoroutineScope.ponger(
    outgoing: SendChannel<Pong>,
    pool: ObjectPool<ByteBuffer> = KtorDefaultPool
): SendChannel<Ping>

Launch a ponger actor job on the CoroutineScope sending pongs to outgoing channel. It is acting for every client’s ping frame and replying with corresponding pong

reader

fun CoroutineScope.reader(
    coroutineContext: <ERROR CLASS> = EmptyCoroutineContext,
    channel: ByteChannel,
    block: suspend ReaderScope.() -> Unit
): ReaderJob
fun CoroutineScope.reader(
    coroutineContext: <ERROR CLASS> = EmptyCoroutineContext,
    autoFlush: Boolean = false,
    block: suspend ReaderScope.() -> Unit
): ReaderJob

startConnectionPipeline

fun CoroutineScope.startConnectionPipeline(
    input: ByteReadChannel,
    output: ByteWriteChannel,
    timeout: WeakTimeoutQueue,
    handler: HttpRequestHandler
): Job

Start connection HTTP pipeline invoking handler for every request. Note that handler could be invoked multiple times concurrently due to HTTP pipeline nature

stop

fun ApplicationEngine.stop(
    gracePeriod: Long,
    timeout: Long,
    timeUnit: TimeUnit
): Unit

Stops this ApplicationEngine

stopServerOnCancellation

fun ApplicationEngine.stopServerOnCancellation(): CompletableJob

Stop server on job cancellation. The returned deferred need to be completed or cancelled.

writeMultipleRanges

fun CoroutineScope.writeMultipleRanges(
    channelProducer: (LongRange) -> ByteReadChannel,
    ranges: List<LongRange>,
    fullLength: Long?,
    boundary: String,
    contentType: String
): ByteReadChannel

Start multirange response writer coroutine

writer

fun CoroutineScope.writer(
    coroutineContext: <ERROR CLASS> = EmptyCoroutineContext,
    channel: ByteChannel,
    block: suspend WriterScope.() -> Unit
): WriterJob
fun CoroutineScope.writer(
    coroutineContext: <ERROR CLASS> = EmptyCoroutineContext,
    autoFlush: Boolean = false,
    block: suspend WriterScope.() -> Unit
): WriterJob