[AIT-1081] Update liveobjects uts-to-kotlin skill to generate tests

[sacOO7]

• Fixes https://ably.atlassian.net/browse/AIT-1081
• Generated UTS markdown to have better understanding of existing UTS infra.
• This is also helpful for a relevant uts-to-kotlin skill to better generate ably-java tests
• Based on the doc, we have missing sandbox test, need to update the same

---

📚 Human-readable UTS guide + website

To make the UTS setup approachable, this PR adds a comprehensive guide and a self-contained website, kept in sync:

• uts/README.md — renders on the module's GitHub page.
• uts/index.html — a standalone, offline-friendly website (inline SVG flow diagrams, scroll-spy nav, light/dark theme; no external assets).

Both walk through: what UTS is → the three test tiers → the spec docs (linked to GitHub) → the uts/ module layout → the SDK hook points → the unit & proxy infrastructure → the two example tests → deviations → how to run → appendices (flow diagrams + per-file API reference + source map).

🗂️ Test package restructure

Test sources are reorganised under a domain-rooted io.ably.lib.uts package that cleanly separates infrastructure from tests, and unit from integration:

io/ably/lib/uts/
├── infra/                        # test infrastructure (no @Test methods)
│   ├── Utils.kt                  #   shared awaits (awaitState / pollUntil …)
│   ├── unit/                     #   mock transports + ConnectionDetails builder
│   └── integration/              #   SandboxApp
│       └── proxy/                #     ProxyManager, ProxySession
├── unit/realtime/                # UNIT tests          → ConnectionRecoveryTest
└── integration/proxy/realtime/   # INTEGRATION tests   → AuthReauthTest

The unit/ ↔ infra/unit/ and integration/ ↔ infra/integration/ pairing is what the new Gradle tasks key off.

Note: the ConnectionDetails test builder no longer lives in io.ably.lib.types, so it now obtains the package-private constructor reflectively (same approach as liveobjects/.../TestUtils.kt).

⚙️ Per-tier Gradle tasks + CI wiring

Added two package-filtered test tasks in uts/build.gradle.kts, mirroring runLiveObjectsUnitTests / runLiveObjectsIntegrationTests:

Task	Runs	CI
:uts:runUtsUnitTests	io.ably.lib.uts.unit.* (mocked, fast)	check.yml (PR gate)
:uts:runUtsIntegrationTests	io.ably.lib.uts.integration.* (real sandbox + proxy)	integration-test.yml → new check-uts job

✅ Validation

• ./gradlew :uts:runUtsUnitTests → 6/6 pass · :uts:runUtsIntegrationTests → 1/1 pass.
• Full CI gate checkWithCodenarc checkstyleMain checkstyleTest runUnitTests runLiveObjectsUnitTests :uts:runUtsUnitTests → BUILD SUCCESSFUL.

Summary by CodeRabbit

• New Features

  • Added a new UTS guide and reference docs for working with unit, integration, and proxy tests.
  • Introduced dedicated Gradle tasks for running UTS unit and integration test suites.
  • Added new integration coverage for channel history and token request flows.

• Bug Fixes

  • Improved reconnect test timing to better capture connection retries.
  • Updated test helpers and infrastructure packaging for clearer separation between unit and integration support.

[coderabbitai]

Walkthrough

Reorganizes the UTS test infrastructure into sub-packages (infra.unit, infra.integration, infra.integration.proxy), consolidates sandbox host constants into SandboxApp, adds new Gradle tasks (runUtsUnitTests, runUtsIntegrationTests) and a CI integration job, adds new integration tests and LiveObjects unit test helpers, and rewrites the AI skill with a module-directory resolution script, objects-mapping reference, and comprehensive developer documentation.

Changes

UTS infrastructure package reorganization and new tests

Layer / File(s)	Summary
Gradle tasks and CI workflow updates uts/build.gradle.kts, .github/workflows/check.yml, .github/workflows/integration-test.yml	Adds runUtsUnitTests and runUtsIntegrationTests tasks with package-filter patterns, adds :liveobjects runtime dependency and junit-jupiter-params, updates the check workflow to use the unit task, and adds a check-uts CI job that runs integration tests.
Infra package reorganization uts/src/test/kotlin/io/ably/lib/uts/infra/Utils.kt, uts/src/test/kotlin/io/ably/lib/uts/infra/unit/*, uts/src/test/kotlin/io/ably/lib/uts/infra/integration/SandboxApp.kt, uts/src/test/kotlin/io/ably/lib/uts/infra/integration/proxy/ProxyManager.kt, uts/src/test/kotlin/io/ably/lib/uts/infra/integration/proxy/ProxySession.kt	Moves all unit infra classes to io.ably.lib.uts.infra.unit, moves integration classes from io.ably.lib.test.helper to io.ably.lib.uts.infra.integration.*, introduces SandboxApp.sandboxHost constant, removes ProxyManager sandbox host constants, updates ProxySession.create defaults to use SandboxApp.sandboxHost, removes old ConnectionDetails DSL from types/Utils.kt, and adds a reflective replacement in infra/unit/Utils.kt. Adds parseQueryString helper and PendingConnection interface in the unit sub-package.
Existing test updates uts/src/test/kotlin/io/ably/lib/uts/unit/realtime/ConnectionRecoveryTest.kt, uts/src/test/kotlin/io/ably/lib/uts/integration/proxy/realtime/AuthReauthTest.kt	Updates package declarations and imports to reference the new infra sub-packages; adds a pollUntil gate in ConnectionRecoveryTest to wait for the second reconnect attempt before asserting query params, fixing a pre-existing race.
New direct-sandbox integration tests uts/src/test/kotlin/io/ably/lib/uts/integration/standard/realtime/ChannelHistoryTest.kt, uts/src/test/kotlin/io/ably/lib/uts/integration/standard/realtime/TokenRequestTest.kt	Adds ChannelHistoryTest (parameterized RTL10d cross-client history with newest-first ordering assertion) and TokenRequestTest (RSA9a/RSA9g/RSA9 token request auth via SandboxApp).
LiveObjects unit test helpers uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/Helpers.kt	Adds Gson DSL, wire JSON builders for object states/operations/protocol messages, reflective buildPublicObjectMessage, STANDARD_POOL_OBJECTS fixture, SyncedChannel container, and setupSyncedChannel/setupSyncedChannelNoAck suspend helpers using MockWebSocket.

UTS-to-Kotlin AI skill and reference documentation

Layer / File(s)	Summary
Package mapping JSON and resolver script .claude/skills/uts-to-kotlin/uts-package-mapping.json, .claude/skills/uts-to-kotlin/scripts/resolve_uts.py	Adds uts-package-mapping.json defining testRoot and per-module tier-to-path mappings; adds resolve_uts.py that validates module directories, reads/writes the mapping, discovers spec Markdown files by tier, derives Kotlin class names and package strings, and outputs structured JSON.
SKILL.md rewrite .claude/skills/uts-to-kotlin/SKILL.md	Replaces the single-spec workflow with a two-phase module-directory flow (Phase 1: resolve/validate/select; Phase 2: per-spec translate), updates KDoc/template conventions to use @UTS <uts-id>, adds tier-specific Gradle run commands, and rewrites integration tier and deviation honesty sections.
Objects UTS-to-ably-java translation reference .claude/skills/uts-to-kotlin/references/objects-mapping.md	New comprehensive reference covering three-layer type disambiguation, entry-point/channel access, Promise-to-CompletableFuture, PathObject/Instance typed hierarchy, LiveMapValue writes, subscriptions/events, ValueType, ObjectMessage/operation types, error codes, internal-graph caveats, worked example, and symbol index.
Developer guide (README and HTML) uts/README.md, uts/index.html	Adds full developer guide covering UTS concepts, three-tier structure, infra hook points, mock transport and proxy infrastructure, async helpers, three reference test walkthroughs, deviation handling, run instructions, cheat-sheet, and appendices; mirrored as a single-page HTML document with light/dark theming and scroll-spy sidebar.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• ably/ably-java#1209: Directly precedes this PR — removes ConnectionDetails(init) from io.ably.lib.types.Utils.kt and establishes LiveObjects groundwork that this PR builds on.
• ably/ably-java#1210: Adds the ProxyManager/ProxySession proxy test helpers that this PR refactors into new sub-packages and updates default host constants for.
• ably/ably-java#1216: Introduces the RealtimeObject API and ChannelBase.object accessor that the new Helpers.kt calls via channel.object.get().

Suggested reviewers

• lawrence-forooghian

Poem

🐇 Hoppity-hop through packages new,
infra.unit and integration too!
The resolver script maps every spec,
sandboxHost constant — what a tech!
Three tiers of tests, all neatly aligned,
This bunny thinks the stack looks fine! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 34.55% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the core change: updating the uts-to-kotlin skill to generate tests, though it omits the broader docs and refactor work.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/liveobjects-uts-tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

.claude/skills/uts-to-kotlin/SKILL.md (1)

353-374: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Make this template tier-specific and use explicit imports.

This scaffold is presented as the resolver-selected tier template, but it still hardcodes unit-only setup (infra.unit.*, MockWebSocket, ConnectionDetails) and star imports. That makes the integration/proxy path easy to start from the wrong skeleton even though later sections require SandboxApp / ProxySession wiring. Split this into per-tier templates (or relabel this one as unit-only) and list concrete imports instead of *.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude/skills/uts-to-kotlin/SKILL.md around lines 353 - 374, This template
is still unit-only even though it is presented as the resolver-selected tier
scaffold, and it also relies on star imports. Update the Skill.md template
around the test scaffold to either split it into separate tier-specific
templates or clearly label this one as unit-only, and replace the wildcard
imports with explicit imports for the exact symbols used. Make sure the correct
tier-specific setup is shown for the resolver path, especially the symbols that
differ between unit and integration/proxy flows such as SandboxApp and
ProxySession.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.claude/skills/uts-to-kotlin/references/objects-mapping.md:
- Around line 530-545: The helper reference in the objects-mapping docs uses the
wrong filename casing, so update the guidance to point consistently to
Helpers.kt instead of helpers.kt. Fix the prose and the table entry that
references uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/Helpers.kt so
readers can locate the actual helper file and related symbols like
setupSyncedChannel, setupSyncedChannelNoAck, buildObjectSyncMessage, and
buildPublicObjectMessage without path mismatches.
- Around line 137-147: Add language tags to the fenced code examples in the
objects-mapping reference so markdownlint stops flagging them and syntax
highlighting is restored. Update the affected examples in the translation
guidance sections around the root.entries()/root.keys() snippets and the other
noted example blocks to use an appropriate tag such as kotlin, markdown, or
text, keeping the existing content unchanged.

In `@uts/build.gradle.kts`:
- Around line 44-54: The custom Test tasks runUtsUnitTests and
runUtsIntegrationTests only set filters, so they are not actually wired to the
UTS test source set. Update these tasks in uts/build.gradle.kts to inherit the
same testClassesDirs and classpath as the built-in test task, and keep the
existing includeTestsMatching filters so they execute the intended
io.ably.lib.uts.unit and io.ably.lib.uts.integration tests instead of passing
empty.

In `@uts/README.md`:
- Around line 42-59: The README contains unlabeled fenced code blocks that
trigger markdownlint and lose syntax highlighting. Update the fenced blocks in
the affected diagram/example sections to include an appropriate language
identifier such as text or kotlin, using the same README content around the
spec/test hierarchy and other referenced fenced blocks, so the markdown stays
lint-clean and renders correctly.

---

Nitpick comments:
In @.claude/skills/uts-to-kotlin/SKILL.md:
- Around line 353-374: This template is still unit-only even though it is
presented as the resolver-selected tier scaffold, and it also relies on star
imports. Update the Skill.md template around the test scaffold to either split
it into separate tier-specific templates or clearly label this one as unit-only,
and replace the wildcard imports with explicit imports for the exact symbols
used. Make sure the correct tier-specific setup is shown for the resolver path,
especially the symbols that differ between unit and integration/proxy flows such
as SandboxApp and ProxySession.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 27e70f9e-9e77-46d5-a860-34d544c796f2

📥 Commits

Reviewing files that changed from the base of the PR and between b56407f and 0c59d15.

📒 Files selected for processing (32)

• .claude/skills/uts-to-kotlin/SKILL.md
• .claude/skills/uts-to-kotlin/references/objects-mapping.md
• .claude/skills/uts-to-kotlin/scripts/resolve_uts.py
• .claude/skills/uts-to-kotlin/uts-package-mapping.json
• .github/workflows/check.yml
• .github/workflows/integration-test.yml
• uts/README.md
• uts/build.gradle.kts
• uts/index.html
• uts/src/test/kotlin/io/ably/lib/types/Utils.kt
• uts/src/test/kotlin/io/ably/lib/uts/deviations.md
• uts/src/test/kotlin/io/ably/lib/uts/infra/Utils.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/integration/SandboxApp.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/integration/proxy/ProxyManager.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/integration/proxy/ProxySession.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/ClientFactories.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/DefaultPendingConnection.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/DefaultPendingRequest.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/FakeClock.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/MockEvent.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/MockHttpClient.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/MockHttpEngine.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/MockWebSocket.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/MockWebSocketEngineFactory.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/PendingConnection.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/PendingRequest.kt
• uts/src/test/kotlin/io/ably/lib/uts/infra/unit/Utils.kt
• uts/src/test/kotlin/io/ably/lib/uts/integration/proxy/realtime/AuthReauthTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/integration/standard/realtime/ChannelHistoryTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/integration/standard/realtime/TokenRequestTest.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/Helpers.kt
• uts/src/test/kotlin/io/ably/lib/uts/unit/realtime/ConnectionRecoveryTest.kt

💤 Files with no reviewable changes (1)

• uts/src/test/kotlin/io/ably/lib/types/Utils.kt

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add language tags to these fenced examples.

markdownlint is already flagging these code blocks. Adding kotlin, markdown, or text here will clear the lint noise and restore syntax highlighting in the main translation examples.

Also applies to: 191-198, 283-296, 316-323, 418-433, 563-592

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 137-137: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude/skills/uts-to-kotlin/references/objects-mapping.md around lines 137
- 147, Add language tags to the fenced code examples in the objects-mapping
reference so markdownlint stops flagging them and syntax highlighting is
restored. Update the affected examples in the translation guidance sections
around the root.entries()/root.keys() snippets and the other noted example
blocks to use an appropriate tag such as kotlin, markdown, or text, keeping the
existing content unchanged.

Source: Linters/SAST tools

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the helper filename casing.

This section points readers to .../unit/liveobjects/helpers.kt, but the helper added in this stack is uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/Helpers.kt. On Linux/macOS source navigation that path mismatch is enough to send people to a non-existent file, so the prose and table should use Helpers.kt consistently.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude/skills/uts-to-kotlin/references/objects-mapping.md around lines 530
- 545, The helper reference in the objects-mapping docs uses the wrong filename
casing, so update the guidance to point consistently to Helpers.kt instead of
helpers.kt. Fix the prose and the table entry that references
uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects/Helpers.kt so readers can
locate the actual helper file and related symbols like setupSyncedChannel,
setupSyncedChannelNoAck, buildObjectSyncMessage, and buildPublicObjectMessage
without path mismatches.

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

In Gradle Kotlin DSL, does a custom tasks.register("...")automatically inherittestClassesDirsandclasspathfrom the built-intesttask, or do those need to be set explicitly fromsourceSets["test"]?

💡 Result:

In Gradle, a custom task registered with tasks.register<Test>("...") does not automatically inherit testClassesDirs and classpath from the built-in test task [1][2]. By design, Gradle's JVM plugins automatically configure only the built-in test task to use the test source set [1][2]. When you create a custom Test task, you must explicitly configure both testClassesDirs and classpath using the appropriate sourceSets [1][2]. The recommended approach is to manually set these properties as shown below: val myCustomTest = tasks.register("myCustomTest") { testClassesDirs = sourceSets["test"].output.classesDirs classpath = sourceSets["test"].runtimeClasspath } If you are creating a custom test task for a different set of tests (e.g., integration tests), you should define a corresponding sourceSet and point the task properties to that specific source set instead: val integrationTest = tasks.register("integrationTest") { testClassesDirs = sourceSets["intTest"].output.classesDirs classpath = sourceSets["intTest"].runtimeClasspath } Relying on automatic inheritance is not supported, and attempting to do so will result in a task that does not correctly locate or execute your test classes [1][2].

Citations:

• 1: https://docs.gradle.org/current/userguide/java_testing.html
• 2: https://docs.gradle.org/9.5.0/userguide/java_testing.html

---

Wire the custom Test tasks to the test source set. tasks.register<Test>(...) here only adds the filter; it does not inherit testClassesDirs or classpath from the built-in test task, so these tasks can pass without running any UTS tests.

Suggested fix

+val testSourceSet = sourceSets["test"]
+
 tasks.register<Test>("runUtsUnitTests") {
+    testClassesDirs = testSourceSet.output.classesDirs
+    classpath = testSourceSet.runtimeClasspath
     filter {
         includeTestsMatching("io.ably.lib.uts.unit.*")
     }
 }
 
 tasks.register<Test>("runUtsIntegrationTests") {
+    testClassesDirs = testSourceSet.output.classesDirs
+    classpath = testSourceSet.runtimeClasspath
     filter {
         includeTestsMatching("io.ably.lib.uts.integration.*")
     }
 }

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	tasks.register<Test>("runUtsUnitTests") {
	filter {
	includeTestsMatching("io.ably.lib.uts.unit.*")
	}
	}
	tasks.register<Test>("runUtsIntegrationTests") {
	filter {
	includeTestsMatching("io.ably.lib.uts.integration.*")
	}
	}
	val testSourceSet = sourceSets["test"]
	tasks.register<Test>("runUtsUnitTests") {
	testClassesDirs = testSourceSet.output.classesDirs
	classpath = testSourceSet.runtimeClasspath
	filter {
	includeTestsMatching("io.ably.lib.uts.unit.*")
	}
	}
	tasks.register<Test>("runUtsIntegrationTests") {
	testClassesDirs = testSourceSet.output.classesDirs
	classpath = testSourceSet.runtimeClasspath
	filter {
	includeTestsMatching("io.ably.lib.uts.integration.*")
	}
	}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@uts/build.gradle.kts` around lines 44 - 54, The custom Test tasks
runUtsUnitTests and runUtsIntegrationTests only set filters, so they are not
actually wired to the UTS test source set. Update these tasks in
uts/build.gradle.kts to inherit the same testClassesDirs and classpath as the
built-in test task, and keep the existing includeTestsMatching filters so they
execute the intended io.ably.lib.uts.unit and io.ably.lib.uts.integration tests
instead of passing empty.

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add language identifiers to the fenced blocks.

These unlabeled fences are already tripping markdownlint. Please mark them as text, kotlin, or another appropriate language so the README stays lint-clean and renders with syntax highlighting.

Also applies to: 224-243, 850-878, 888-909

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 42-42: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@uts/README.md` around lines 42 - 59, The README contains unlabeled fenced
code blocks that trigger markdownlint and lose syntax highlighting. Update the
fenced blocks in the affected diagram/example sections to include an appropriate
language identifier such as text or kotlin, using the same README content around
the spec/test hierarchy and other referenced fenced blocks, so the markdown
stays lint-clean and renders correctly.

Source: Linters/SAST tools

[ttypic]

LGTM