io.ktor.server.testing / TestApplicationEngine

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>`
engine	`val engine: HttpClientEngine` An instance of client engine user to be used in client.

Inherited Properties

environment	`val environment: ApplicationEngineEnvironment` instance of ApplicationEngineEnvironment for this engine
pipeline	`val pipeline: EnginePipeline` pipeline to use with this engine

Functions

createCall	`fun createCall( readResponse: Boolean = false, closeRequest: Boolean = true, setup: TestApplicationRequest.() -> Unit ): TestApplicationCall` Creates an instance of test call but doesn’t start request processing
handleRequest	`fun handleRequest( closeRequest: Boolean = true, 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> = listOf(WORKING_DIRECTORY_PATH), 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
httpServer	`fun CoroutineScope.httpServer( settings: HttpServerSettings, handler: suspend CoroutineScope.(request: Request, input: ByteReadChannel, output: ByteWriteChannel, upgraded: CompletableDeferred<Boolean>?) -> Unit ): HttpServer` Start an http server with settings invoking handler for every request
mapEngineExceptions	`fun CoroutineScope.mapEngineExceptions( input: ByteReadChannel, request: HttpRequestData ): ByteReadChannel` Returns ByteReadChannel with ByteChannel.close handler that returns SocketTimeoutException instead of SocketTimeoutException. `fun CoroutineScope.mapEngineExceptions( output: ByteWriteChannel, request: HttpRequestData ): ByteWriteChannel` Returns ByteWriteChannel with ByteChannel.close handler that returns SocketTimeoutException instead of SocketTimeoutException.
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: suspend CoroutineScope.(request: Request, input: ByteReadChannel, output: ByteWriteChannel, upgraded: CompletableDeferred<Boolean>?) -> Unit ): Job` Start connection HTTP pipeline invoking handler for every request. Note that handler could be invoked multiple times concurrently due to HTTP pipeline nature
startServerConnectionPipeline	`fun CoroutineScope.startServerConnectionPipeline( connection: ServerIncomingConnection, 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`