Skip to main content

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:132 is for the client. The engine attaches to it.
  • AS 2-ff00:0:212 is 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:

ValueWhat it is
testApiUrlhttps://localhost:<port>, the test API of the built-in server.
testApiCaPemThe CA of the test API.
gatewayPortThe port of the gateway, for ScionWebGateway(port = ...).
endhostApiUrlThe endhost API of the client AS.
serverEndhostApiUrlThe endhost API of the server AS, for your own server.
authTokenThe token for both endhost APIs and the control plane.
serverAddressThe 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 endhostApiUrl and a static token.
  • It sets the SCION address of localhost, and of each host of a gateway backend, to serverAddress. 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:

An API behind a gateway, in a test
The test process
ScionTestNetwork
a PocketSCION topology
HttpClient
the ScionHttp engine
1-ff00:0:132
the client attaches here
2-ff00:0:212
the gateway
The API
embeddedServer on TCP
underlay
SCION
TCP
HTTP/3 CONNECT tunnel
The tunnel runs over SCION, from the client to the gateway. The gateway connects it to the API over TCP.
Text is not SVG - cannot display

First, the test starts the API on a free port:

GreetingApiTest.kt
// 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:

GreetingApiTest.kt
// 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:

GreetingApiTest.kt
// 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:

GreetingApiTest.kt
@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​

PlatformGradle taskNotes
JVMjvmTestOn macOS arm64 and on Linux x86-64.
Android host testtestAndroidHostTest, or testReleaseUnitTestNeeds the setup below.
iOS simulatoriosSimulatorArm64TestOn a Mac.
Android deviceconnectedAndroidDeviceTest, or connectedAndroidTestNeeds 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:

build.gradle.kts
// 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:

build.gradle.kts
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:

build.gradle.kts
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​