Testing your app
ktor-client-scion-testing starts a SCION network in the test process. Your tests send real
requests over SCION, but they need no SCION network, no server, and no Rust toolchain. The same test
runs on the JVM, as an Android host test, on the iOS simulator, and on an Android device.
Add the engine to your project adds the library to
commonTest.
The test network
ScionTestNetwork.start() starts a PocketSCION topology, and returns when the topology serves:
- AS
1-ff00:0:132is for the client. The engine attaches to it. - AS
2-ff00:0:212is for the servers. A built-in server in this AS serves a test API, and plays a WebGateway. Your own server can also attach to this AS.
Each network has its own ports, its own token, and its own CA, so the tests can run at the same
time. close() stops the network. The garbage collector also stops a network that nothing refers
to, so keep a reference while your tests use it.
The network gives you these values:
| Value | What it is |
|---|---|
testApiUrl | https://localhost:<port>, the test API of the built-in server. |
testApiCaPem | The CA of the test API. |
gatewayPort | The port of the gateway, for ScionWebGateway(port = ...). |
endhostApiUrl | The endhost API of the client AS. |
serverEndhostApiUrl | The endhost API of the server AS, for your own server. |
authToken | The token for both endhost APIs and the control plane. |
serverAddress | The SCION address of a server in the server AS on this host. |
By default, the client and the server reach their AS over UDP, through a router. With
ScionTestNetwork.start { underlay = ScionUnderlay.Snap }, they use a SNAP instead.
Attach the engine
useTestNetwork(network) in the engine block attaches the engine to the network:
- It sets
endhostApiUrland a static token. - It sets the SCION address of
localhost, and of each host of a gateway backend, toserverAddress. To add other hosts, give them as more arguments:useTestNetwork(network, "api.example.com").
It does not set caCertificatesPem, because your server has its own CA. For the test API, set it to
testApiCaPem, as the first request does.
Test an API behind a gateway
In production, many APIs stay on TCP behind a WebGateway. The sample app-testing tests the API
client from the WebGateway page in the same way. The test runs the API on TCP, and
the network connects the gateway to it:
First, the test starts the API on a free port:
// The API of the app, on plain TCP. In production, it runs behind the
// gateway.
api = embeddedServer(CIO, host = "127.0.0.1", port = 0) {
routing {
get("/greeting") { call.respondText("Hello, ${call.parameters["name"]}!") }
}
}.start()
// Retrieve the port of the API, so the gateway can connect to it.
val apiPort = runBlocking { api.engine.resolvedConnectors().first().port }
Then it starts the network. gatewayBackend connects each tunnel for the API host to the API:
// The built-in server of the network plays the gateway. It connects
// each tunnel for API_HOST to the API.
network = ScionTestNetwork.start {
gatewayBackend(API_HOST, "127.0.0.1:$apiPort")
}
The client attaches to the network, and sends each request through the gateway:
// Build a client using the ScionHttp engine.
client = HttpClient(ScionHttp) {
engine {
// Use the test network, so the engine can reach the gateway.
useTestNetwork(network)
// Send each request through the gateway. In the test network,
// the gateway listens on gatewayPort, not on 443.
webGateway = ScionWebGateway(port = network.gatewayPort)
requestTimeoutMillis = 20_000
}
}
The test calls the API client of the app, and gets its answer over SCION:
@Test
fun greetsOverScion(): Unit = runBlocking {
// The scheme is http, because the API has no TLS.
val greeting = GreetingApi(client, "http://$API_HOST").greet("SCION")
assertEquals("Hello, SCION!", greeting)
}
Compare the client in the test with the production client: the test network replaces the AA and
the TSAR record, and the gateway listens on gatewayPort, not on 443. The API client of the app
stays the same.
Test an HTTP/3 server
Your own SCION server can attach to the server AS. It opens a SCION socket with
serverEndhostApiUrl and authToken, and gets the address serverAddress. To send the requests of
the engine to it, give its host to useTestNetwork, and set caCertificatesPem to the CA of your
server.
Where the tests run
| Platform | Gradle task | Notes |
|---|---|---|
| JVM | jvmTest | On macOS arm64 and on Linux x86-64. |
| Android host test | testAndroidHostTest, or testReleaseUnitTest | Needs the setup below. |
| iOS simulator | iosSimulatorArm64Test | On a Mac. |
| Android device | connectedAndroidDeviceTest, or connectedAndroidTest | Needs the setup below. The network runs in the app process. |
testAndroidHostTest and connectedAndroidDeviceTest are the task names with the plugin
com.android.kotlin.multiplatform.library. With com.android.library, the host test task has the
name of the build variant, for example testReleaseUnitTest, and the device test task is
connectedAndroidTest.
Android host tests
An Android host test runs on the desktop JVM of your computer or your CI. But it gets the Android artifacts of the engine, which contain only the Android libraries. Without more setup, the test fails with:
java.lang.UnsatisfiedLinkError: Unable to load library 'ktor_scion_testing'
To fix this, add the JVM artifacts to the host test. They contain the desktop libraries for macOS arm64 and Linux x86-64. Use the same version as for the engine:
// The desktop libraries for the Android host test, which runs on the JVM.
getByName("androidHostTest").dependencies {
runtimeOnly("net.anapaya.scion:ktor-client-scion-jvm:$sdkVersion")
runtimeOnly("net.anapaya.scion:ktor-client-scion-testing-jvm:$sdkVersion")
}
With the plugin com.android.library, the source set has the name androidUnitTest, not
androidHostTest.
Android device tests
With the plugin com.android.kotlin.multiplatform.library, a device test runs only the tests in
androidDeviceTest, not the tests in commonTest. To run commonTest on a device, set the source
set tree of the device test to test, and set the AndroidX test runner:
androidLibrary {
namespace = "net.anapaya.ktor.scion.consumer"
compileSdk = libs.versions.androidCompileSdk.get().toInt()
minSdk = libs.versions.androidMinSdk.get().toInt()
withHostTestBuilder {}
// Runs commonTest on a device too, not only the tests in androidDeviceTest.
withDeviceTestBuilder { sourceSetTreeName = "test" }.configure {
instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
}
}
The device test also needs the dependency on the runner:
getByName("androidDeviceTest").dependencies {
implementation(libs.androidx.test.runner)
}
The test network runs in the process of the test app on the device. So the device test needs no setup on the computer, and it works on an emulator and on a phone.
With the plugin com.android.library, set
instrumentedTestVariant.sourceSetTree.set(KotlinSourceSetTree.test) in androidTarget, and
testInstrumentationRunner in defaultConfig.
Where to go next
- The sample
app-testingatbindings/kmp-ktor-engine/samples/app-testingis the test of this page, ready to run. - The app
tests/consumeratbindings/kmp-ktor-engine/tests/consumerhas the Gradle setup of this page, with the plugincom.android.kotlin.multiplatform.library.