Skip to content

Commit 752b45e

Browse files
committed
feat(uts): add LiveObjects unit-test helpers (standard_test_pool) + map them
Translate objects/helpers/standard_test_pool.md into ably-java test helpers in uts/.../unit/liveobjects/helpers.kt: the standard object pool, the protocol- and object-message builders (emitting the integer-coded wire JSON the SDK's Gson expects), setupSyncedChannel/NoAck over the existing MockWebSocket, and buildPublicObjectMessage — which reaches the internal PAOM3/PAOOP3 construction (WireObjectMessage -> DefaultObjectMessage) by reflection, so it runs today even though the rest of :liveobjects is unimplemented. Add testRuntimeOnly(:liveobjects) so that reflection resolves while keeping the compile classpath decoupled. Wire the mapping reference at it: objects-mapping.md gains a "Unit-test helpers" section mapping each spec helper to its Kotlin name, and §11/§13 are corrected to note public_object_message.md is translatable via buildPublicObjectMessage rather than internal-only.
1 parent 0068fe9 commit 752b45e

3 files changed

Lines changed: 395 additions & 21 deletions

File tree

‎.claude/skills/uts-to-kotlin/references/objects-mapping.md‎

Lines changed: 53 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -395,12 +395,14 @@ delivered to subscription listeners) map to ably-java interfaces with getters (p
395395
`io.ably.lib.liveobjects.message`). The `PublicAPI::` prefix is dropped — ably-java exposes them as
396396
`ObjectMessage` / `ObjectOperation`.
397397

398-
> **Getter-only, no public constructor.** You obtain an `ObjectMessage` only from a subscription event
399-
> (`event.getMessage()`, §8) — there is no public factory. The spec's *explicit* construction-from-wire
400-
> (`PublicObjectMessage.fromObjectMessage(source, channel)` / `PublicObjectOperation.fromObjectOperation(op)`,
401-
> `PAOM3`/`PAOOP3`, in `public_object_message.md`) is internal in ably-java, so assert the getters on a
402-
> message received via `subscribe` rather than constructing one; treat a standalone construction-only test
403-
> as internal (§13).
398+
> **Getter-only, no *public* constructor — use the `buildPublicObjectMessage` helper.** In normal use you
399+
> obtain an `ObjectMessage` from a subscription event (`event.getMessage()`, §8); there is no public
400+
> factory. The spec's explicit construction-from-wire (`PublicObjectMessage.fromObjectMessage(source,
401+
> channel)` / `PublicObjectOperation.fromObjectOperation(op)`, `PAOM3`/`PAOOP3`, in
402+
> `public_object_message.md`) is `internal` to `:liveobjects` — but the unit helpers expose it **by
403+
> reflection** as `buildPublicObjectMessage(wireJson, channelName)` (§13). So `public_object_message.md` is
404+
> translatable: build the source with the op builders (`buildMapSet(...)`, `buildCounterInc(...)`, …) and
405+
> assert the public getters on the result.
404406
405407
`ObjectMessage`: `getId()`, `getClientId()`, `getConnectionId()`, `getTimestamp(): Long?`, `getChannel():
406408
String`, `getOperation(): ObjectOperation`, `getSerial()`, `getSerialTimestamp(): Long?`, `getSiteCode()`,
@@ -499,29 +501,59 @@ Several **unit** specs assert on the **internal CRDT graph**, not the public API
499501
- `realtime_object.md` — **mixed**: `get()` (`RTO23`, incl. the `40024`/`90001`/`92008` precondition cases)
500502
is public and maps via §2/§12, but `publish` / `publishAndApply` (`RTO15`/`RTO20`, marked `internal` in the
501503
IDL) and the OBJECT/ACK wire assertions are internal.
502-
- `public_object_message.md` — **mixed**: the `ObjectMessage` / `ObjectOperation` *getters* are public
503-
(assert them on a message received via `subscribe`, §11), but the explicit construction-from-wire it tests
504-
(`fromObjectMessage` / `fromObjectOperation`, `PAOM3`/`PAOOP3`) has no public factory and is internal.
504+
- `public_object_message.md` — **translatable** via the `buildPublicObjectMessage` helper (below), which
505+
reflectively performs the `PAOM3`/`PAOOP3` construction (`WireObjectMessage` → `DefaultObjectMessage`)
506+
that is otherwise `internal`. Build the source with the op builders and assert the public getters (§11).
505507

506508
In ably-java these are **not public**. They live in the `:liveobjects` module as `Default*` / `Wire*` /
507509
`ResolvedValue` / `Leaf` / `MapRef` / `CounterRef` classes (package `io.ably.lib.liveobjects.*`,
508-
implementation source set) — and the `uts` module currently depends only on `:java` (public API) and
509-
`:network-client-core`, **not** on `:liveobjects`. Consequences when translating:
510-
511-
- **Public-API unit specs** (`path_object*.md`, `instance.md`, `live_object_subscribe.md`, and the
512-
public-surface parts of `realtime_object.md`, `public_object_message.md` and `value_types.md`) translate
513-
cleanly against the §1–§12 map and compile against `:java`. (Note `path_object.md` / `instance.md` also
514-
contain `compact()` cases, which are deviations per §4/§5 since ably-java implements only `compactJson()`.)
515-
- **Internal-graph unit specs** can't be expressed through the public API. Before translating those, decide
516-
with the user whether to (a) add a `testImplementation(project(":liveobjects"))` dependency to
517-
`uts/build.gradle.kts` and target the `Default*`/internal classes directly, or (b) translate them inside
518-
the `:liveobjects` module's own test source set instead, or (c) skip them for the uts module. Flag this
519-
rather than forcing a public-API assertion that can't see internal state.
510+
implementation source set). The `uts` module keeps them **off its compile classpath** (it compiles against
511+
`:java` only) but now has `testRuntimeOnly(project(":liveobjects"))`, so the helpers reach the internal
512+
wire/message classes **by reflection** at runtime. Consequences when translating:
513+
514+
- **Public-API unit specs** (`path_object*.md`, `instance.md`, `live_object_subscribe.md`,
515+
`public_object_message.md`, and the public-surface parts of `realtime_object.md` and `value_types.md`)
516+
translate cleanly against the §1–§12 map + the helpers below, and compile against `:java`. (Note
517+
`path_object.md` / `instance.md` also contain `compact()` cases, which are deviations per §4/§5 since
518+
ably-java implements only `compactJson()`.)
519+
- **Internal-graph unit specs** (`objects_pool.md`, `parent_references.md`, the internal-state assertions in
520+
`live_counter.md` / `live_map.md`) assert on internal CRDT state the public API can't see. Options: (a)
521+
add reflective accessors to the helpers for the `Default*`/internal classes (the technique
522+
`buildPublicObjectMessage` and `infra/unit/Utils.kt` already use), (b) translate them in the
523+
`:liveobjects` module's own test source where the types are directly accessible, or (c) skip them. Flag
524+
rather than forcing a public-API assertion that can't reach internal state.
520525
- Spec name → ably-java impl (for orientation, not public use): `InternalLiveMap` → `DefaultLiveMap`,
521526
`InternalLiveCounter` → `DefaultLiveCounter`, the public-view impls are `DefaultPathObject` /
522527
`DefaultLiveMapPathObject` / `DefaultInstance` / …, wire form is `WireObjectMessage` /
523528
`WireObjectOperation` / `WireObjectState` etc.
524529

530+
### Unit-test helpers — `standard_test_pool.md` → `helpers.kt`
531+
532+
Every objects unit spec opens with `setup_synced_channel` and constructs protocol/object messages with the
533+
`build_*` helpers. These are implemented in
534+
`uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/helpers.kt` — **call them; don't hand-roll the mock
535+
setup or message JSON.**
536+
537+
| Spec helper | `helpers.kt` |
538+
|---|---|
539+
| `{ client, channel, root, mock_ws } = AWAIT setup_synced_channel("test")` | `val (client, channel, root, mockWs) = setupSyncedChannel("test")` (`suspend`, returns `SyncedChannel`) |
540+
| `setup_synced_channel_no_ack(...)` | `setupSyncedChannelNoAck(...)` |
541+
| `build_object_sync_message` / `build_object_message` / `build_ack_message` | `buildObjectSyncMessage` / `buildObjectMessage` / `buildAckMessage` → `ProtocolMessage` |
542+
| `build_counter_inc` / `build_map_set` / `build_map_remove` / `build_map_clear` / `build_object_delete` / `build_counter_create` / `build_map_create` | same names camelCased → wire `JsonObject` |
543+
| `build_object_state` / `build_object_message_with_state` | `buildObjectState` / `buildObjectMessageWithState` |
544+
| `build_public_object_message(msg, channel)` | `buildPublicObjectMessage(wireJson, channel)` (reflective; §11) |
545+
| `STANDARD_POOL_OBJECTS` | `STANDARD_POOL_OBJECTS` |
546+
| inline ObjectData / map-entry / state fragments | `dataString` / `dataNumber` / `dataBoolean` / `dataObjectId` / `dataBytes` / `dataJson`, `mapEntry`, `mapState`, `counterState`, `mapCreateOp`, `counterCreateOp` |
547+
548+
`mock_ws.send_to_client(...)` is the existing `mockWs.sendToClient(...)` (§ mock API in the main skill). The
549+
wire `action` / `semantics` are integer enum codes — the builders emit the codes for you.
550+
551+
> **Runtime caveat:** `setupSyncedChannel` returns only once `RealtimeObject.get()` resolves, which needs
552+
> the `:liveobjects` SDK's OBJECT_SYNC processing. Until that lands the helpers **compile** and the test
553+
> structure is correct, but the setup throws at runtime — i.e. translate-only today, runnable once the SDK
554+
> is implemented. (`buildPublicObjectMessage` does *not* depend on this — the message/operation layer is
555+
> implemented, so those tests can run now.)
556+
525557
---
526558

527559
## 14. Worked example <a id="14-worked-example"></a>

‎uts/build.gradle.kts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ plugins {
77
dependencies {
88
testImplementation(project(":java"))
99
testImplementation(project(":network-client-core"))
10+
// Runtime-only so compile-time stays decoupled from the plugin internals; the LiveObjects test
11+
// helpers reach the internal wire/message classes (e.g. for build_public_object_message) by reflection.
12+
testRuntimeOnly(project(":liveobjects"))
1013
testImplementation(kotlin("test"))
1114
testImplementation(libs.mockk)
1215
testImplementation(libs.coroutine.core)

0 commit comments

Comments
 (0)