spring-kotlin docker-backed integrationTest design

[rossdanderson]

Question

What does the examples/spring-kotlin docker-backed integration test look like, and how is its
source set wired?

Model it on application-apis/.../example-adapter-kotlin/CalendarAdapterIntegrationTest (its
shape, not its build — that repo uses the asyncapi codegen plugin DataSource-Extensions lacks):
start a Liberator Testcontainer via the shared kotest module, run the spring-kotlin adapter against
the container's mapped DataSource port, subscribe as a StreamLink client, and assert data flows
end-to-end.

Decide and specify:

• What the adapter serves and what the client asserts — the concrete subject(s) and expected
  records, given whatever examples/spring-kotlin currently exposes (audit its controller/services).
• Source-set wiring: add an integrationTest JvmTestSuite to examples/spring-kotlin
  (which today is a plain kotlin("jvm") + spring-boot build, not the common-library convention).
  It depends on the kotest module, kotest-runner, turbine.
• CI exclusion: confirm the suite is not wired into check (so ./gradlew check in CI skips
  it), mirroring example-adapter-kotlin (which also disables Kover instrumentation for it). Decide
  whether a developer runs it via ./gradlew :examples:spring-kotlin:integrationTest.
• Whether the spring adapter needs any change to be startable against an arbitrary
  host/port from the test (cf. startCalendarAdapter(host, dataSourcePort)).

Output: the IT design + the build-file changes for the example.

---

Blocked by the shared kotest module shape.

[rossdanderson]

Resolution — spring-kotlin docker-backed integrationTest design

Prototype sketch below (illustrative — it can't compile until sl4jx-kotlin / datasourcex-kotest
exist and examples/spring-kotlin gains the source set).

What the adapter serves (audited)

StreamsController publishes Payload(version, userId?, sessionId?, parameter1, parameter2, uuid):

• /public/stream/{p1}/{p2} — infinite Payload stream; version from 0, params echoed, 1/sec.
• /user/{userId}/stream/{p1}/{p2} — userId from @IngressDestinationVariable(USER_ID).
• /session/{userId}/{sessionId}/stream/{p1}/{p2} — +PERSISTENT_SESSION_ID.
• /public/container/{p1}/{p2} (+ /user/...) — Bulk of 10 rows then random Upsert/Remove.

No production change needed

The adapter connects out via caplin.datasource.managed.peer.outgoing (default
ws://localhost:19000). The test overrides it to the container's mapped port at startup — no code
change to the example.

Source-set wiring (examples/spring-kotlin/build.gradle.kts)

Add an integrationTest JvmTestSuite (the example is a plain kotlin("jvm") build):

testing { suites { register<JvmTestSuite>("integrationTest") {
  useJUnitPlatform()
  dependencies {
    implementation(project())
    implementation(project(":datasourcex-kotest"))     // Liberator extension + StreamLink client
    implementation(libs.kotest.runner)
    implementation(libs.turbine)
  }
}}}
configurations {
  named("integrationTestImplementation") { extendsFrom(configurations.implementation.get()) }
  named("integrationTestRuntimeOnly") { extendsFrom(configurations.runtimeOnly.get()) }
}
kover { currentProject { instrumentation { disabledForTestTasks.add("integrationTest") } } }

CI exclusion: the suite is not wired into check, so ./gradlew check (CI) skips it; Kover
instrumentation is disabled for it. Developers run ./gradlew :spring-kotlin:integrationTest.

The test (Kotest, driven by the shared extension)

class SpringKotlinAdapterIntegrationTest : FunSpec({
  val liberator = install(LiberatorContainerExtension())   // datasourcex-kotest

  // Start the real Spring adapter, pointed at the container's mapped DataSource port.
  val ctx = SpringApplicationBuilder(SpringKotlinApplication::class.java)
      .properties(
          "caplin.datasource.managed.peer.outgoing=" +
              "ws://${liberator.containerState.host}:${liberator.dataSourcePort}")
      .run()
  autoClose(AutoCloseable { ctx.close() })

  val alice = liberator.connect("alice"); autoClose(alice)
  beforeSpec { alice.awaitConnected() }

  test("serves a public Payload stream end-to-end") {
    alice.getSubject<Payload>(Subject("public", "stream", "foo", "42"))
        .filterIsUpdate()
        .test(timeout = 30.seconds) {
          awaitItem().let {
            it.version shouldBe 0
            it.parameter1 shouldBe "foo"; it.parameter2 shouldBe 42
            it.uuid.shouldNotBeNull()
          }
          awaitItem().version shouldBe 1          // proves the stream advances
          cancelAndIgnoreRemainingEvents()
        }
  }

  test("serves a public container: Bulk of 10 rows") {
    alice.getContainer(Subject("public", "container", "foo", "42"))
        .test(timeout = 30.seconds) {
          awaitItem().shouldBeBulkOfSize(10)      // first event is the 10-row bulk
          cancelAndIgnoreRemainingEvents()
        }
  }

  test("injects the authenticated USER_ID into the payload") {
    alice.getSubject<Payload>(Subject("user", "alice", "stream", "foo", "42"))
        .filterIsUpdate()
        .test(timeout = 30.seconds) {
          awaitItem().userId shouldBe "alice"     // USER_ID ingress variable threaded through
          cancelAndIgnoreRemainingEvents()
        }
  }
  // session test analogous, asserting a non-null sessionId once a persistent session is established.
})

Execution risks / open items for the USER_ID + session coverage

The public stream + container assertions are deterministic and low-risk. The token-injection
coverage the ticket calls for depends on Liberator-side setup that must be validated during the
build, not on the example code:

1. USER_ID: proving injection overrides the path (rather than the client just supplying
   alice in the subject) requires a Liberator object-map override (%u) — the equivalent of the
   reference example's addObjectMapOverride("username", "%u", …). Without it, the test proves the
   adapter binds @IngressDestinationVariable(USER_ID) and echoes it, but not that Liberator
   substituted it. Decide during execution whether to add that mapping via
   DefaultContainerConfig(adapterConfig = …) or accept the weaker assertion.
2. PERSISTENT_SESSION_ID: needs the StreamLink client to establish a persistent session; confirm
   the extension's connect() path supports it, else extend datasourcex-kotest.
3. Payload deserialization uses the extension's default jacksonObjectMapper() (UUID is
   supported); no extra Jackson module needed (unlike the MrBean interface-schema reference).

These are validation steps for the executing session; they don't block the plan. No tickets
remain — the route to the destination is clear.

[rossdanderson]

Resolved — integrationTest JvmTestSuite on examples/spring-kotlin (not wired to check, Kover disabled → excluded from CI). Kotest spec starts the real adapter via SpringApplicationBuilder pointed at the mapped DataSource port (no production change) and asserts public stream + container + USER_ID/session token injection. Concrete sketch + auth/mapping risks in the comment above.