You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a53996c
Browse filesBrowse the repository at this point in the historyBrowse files
docs(uts): document direct-sandbox tier and per-module test layout
Reflect the new test-source structure in the UTS guide, website, and the
uts-to-kotlin skill:
- Add the direct-sandbox (`integration/standard/<module>/`) tier alongside
the existing unit and proxy tiers, and document that every tier is now
organised by module (`realtime`, `liveobjects`, …).
- Update §2 tier table, §4.2 directory tree + mental model, §7.3 SandboxApp
(shared by both integration kinds), and §12 run commands in README.md, and
mirror all of it in index.html (tags verified balanced, sections intact).
- Generalise the skill's spec→test path mapping to `<module>`, add a
direct-sandbox row, and split integration specs into fault-injecting (proxy)
vs happy-path (direct sandbox) flows.
- Correct stale "both tiers" wording now that there are three tiers.
`<module>` is the SDK area — `realtime`, `rest`, `liveobjects`, … (existing folders: `unit/realtime/`,
73
+
`unit/liveobjects/`). The spec's own `<sub>` grouping (e.g. `connection/`) is **not** carried into a
74
+
sub-package — tests sit directly under the tier/module folder (e.g. `connection_recovery_test.md` →
75
+
`…/uts/unit/realtime/ConnectionRecoveryTest.kt`).
69
76
70
77
Class name: take the file name, strip `_test` suffix, convert `snake_case` → `PascalCase`, append `Test`.
71
78
72
-
**Integration specs that drive traffic through the programmable proxy** (they reference `create_proxy_session()`, proxy rules, or `uts/test/realtime/integration/helpers/proxy.md`) follow a different translation flow — see the **Proxy integration tests** section at the end of this skill instead of the unit-test rules below.
79
+
**Integration specs come in two kinds:**
80
+
- Those that **inject faults** (reference `create_proxy_session()`, proxy `rules`, `trigger_action`, `get_log`, or `uts/test/realtime/integration/helpers/proxy.md`) are **proxy** tests under `integration/proxy/<module>/` — follow the **Proxy integration tests** section at the end of this skill instead of the unit-test rules below.
81
+
- Those that exercise only **happy-path interop** against the real sandbox (no fault injection) are **direct sandbox** tests under `integration/standard/<module>/`. They use `SandboxApp` alone (no `ProxySession`), connecting straight to `ProxyManager.sandboxRealtimeHost` / `sandboxRestHost`. *(No example exists yet — model the suite setup/teardown on the proxy section but drop the `ProxySession`/`connectThroughProxy` wiring.)*
(`./gradlew :uts:test` still runs all tiers — unit, standard, and proxy.)
361
+
341
362
Handle test failures using this decision tree (see [reference doc](https://github.com/ably/specification/blob/main/uts/docs/writing-derived-tests.md) for full detail):
Append to `uts/src/test/kotlin/io/ably/lib/deviations.md`. Each entry needs:
403
+
Append to `uts/src/test/kotlin/io/ably/lib/uts/deviations.md`. Each entry needs:
383
404
1. The spec point (e.g. `RSA4c2`)
384
405
2. What the spec says
385
406
3. What the SDK does
@@ -417,7 +438,7 @@ For each test case, verify:
417
438
418
439
For any place where the generated test diverges from the spec pseudocode (adapted assertion, env-gated skip, or omitted step):
419
440
-[ ] A `// DEVIATION:` comment explains why
420
-
-[ ] The deviation is recorded in `uts/src/test/kotlin/io/ably/lib/deviations.md`
441
+
-[ ] The deviation is recorded in `uts/src/test/kotlin/io/ably/lib/uts/deviations.md`
421
442
422
443
If you find gaps during this review, fix them and re-run Steps 5–6 before finishing.
423
444
@@ -439,11 +460,13 @@ Recognise them by: a reference to `create_proxy_session()`, proxy `rules`, `trig
439
460
440
461
### Infrastructure
441
462
442
-
Three helpers live in `uts/src/test/kotlin/io/ably/lib/test/helper/`. **Read them before translating a proxy spec** — they hold the exact method signatures.
463
+
Three helpers live under `uts/src/test/kotlin/io/ably/lib/uts/infra/integration/`. **Read them before translating a proxy spec** — they hold the exact method signatures.
464
+
465
+
-**`ProxyManager`** (`infra/integration/proxy/ProxyManager.kt`, package `io.ably.lib.uts.infra.integration.proxy`) — downloads/starts the shared `uts-proxy` process and exposes the sandbox host. Call `ProxyManager.ensureProxy()` once per suite in setup. `ProxyManager.sandboxRealtimeHost` / `sandboxRestHost` are the upstream sandbox hosts (the default target of every session).
466
+
-**`ProxySession`** (`infra/integration/proxy/ProxySession.kt`, same package) — one programmable session wrapping the proxy control API; also defines the `connectThroughProxy` extension and the rule-builder helpers.
467
+
-**`SandboxApp`** (`infra/integration/SandboxApp.kt`, package `io.ably.lib.uts.infra.integration`) — provisions/deletes a sandbox test app from the shared `test-app-setup.json` in ably-common. `SandboxApp.create()` returns a `SandboxApp` with `appId`, `defaultKey`, and `keys` (`defaultKey` is a full-capability `appId.keyId:keySecret`); `app.delete()` tears it down. Provision in suite setup, delete in teardown.
443
468
444
-
-**`ProxyManager`** — downloads/starts the shared `uts-proxy` process and exposes the sandbox host. Call `ProxyManager.ensureProxy()` once per suite in setup. `ProxyManager.sandboxRealtimeHost` / `sandboxRestHost` are the upstream sandbox hosts (the default target of every session).
445
-
-**`ProxySession`** — one programmable session wrapping the proxy control API.
446
-
-**`SandboxApp`** — provisions/deletes a sandbox test app from the shared `test-app-setup.json` in ably-common. `SandboxApp.create()` returns a `SandboxApp` with `appId`, `defaultKey`, and `keys` (`defaultKey` is a full-capability `appId.keyId:keySecret`); `app.delete()` tears it down. Provision in suite setup, delete in teardown.
469
+
Import these into a proxy test from their packages, e.g. `io.ably.lib.uts.infra.integration.SandboxApp`, `io.ably.lib.uts.infra.integration.proxy.{ProxyManager, ProxySession, connectThroughProxy}`, plus `io.ably.lib.uts.infra.unit.TestRealtimeClient` and `io.ably.lib.uts.infra.{awaitState, pollUntil}`.
447
470
448
471
`ensureProxy()`, the `ProxySession` methods, and the `SandboxApp` methods are all **`suspend`** functions. Per-test bodies use `runTest { }`; JUnit5 `@BeforeAll`/`@AfterAll` (with `@TestInstance(Lifecycle.PER_CLASS)`) wrap their suspend calls in `runBlocking { }`.
|**Unit**|**Mocked** (`MockWebSocket`, `MockHttpClient`) | none | Client-side logic: state machines, request formation, response parsing, timer behaviour. Fast & deterministic. |`unit/realtime/ConnectionRecoveryTest.kt`|
84
-
|**Direct sandbox integration**| Real network | Real Ably sandbox | Happy-path interop: connect, publish, subscribe. No fault injection. |*(not in the two you asked about)*|
84
+
|**Direct sandbox integration**| Real network | Real Ably sandbox | Happy-path interop: connect, publish, subscribe. No fault injection. |`integration/standard/<module>/`*(tier exists; no tests yet)*|
85
85
|**Proxy integration**| Real network **through a programmable proxy**| Real Ably sandbox | Fault behaviour: dropped connections, injected errors, timeouts, re-auth. |`integration/proxy/realtime/AuthReauthTest.kt`|
86
86
87
+
Each tier folder is further organised **by module** (`realtime`, `liveobjects`, …): `unit/<module>/`,
88
+
`integration/standard/<module>/`, and `integration/proxy/<module>/`. So a feature's tests sit together
89
+
by SDK area — the two example tests live at `unit/realtime/` and `integration/proxy/realtime/`.
0 commit comments