Run the UTS through the per-side package factories

[umair-ably]

Stacked on #2293 — closes the remaining half of the rollout plan's conformance step: "Test suite and UTS run against the new layout for both packages, plus an explicit assertion on the agent value per side". (The agent wire assertions landed on #2293 directly as packages/core/test/unit/pubsub_side_agent.test.js; this PR makes the UTS itself run through the per-side entry points.)

What

The UTS constructs every client through one seam — Ably.Rest / Ably.Realtime in helpers.ts (~1,200 call sites across 135 files, all unchanged). This PR makes that seam selectable via UTS_SIDE:

Mode	REST construction	Realtime construction
core (default)	core constructor (today's behavior; the entry shape of the existing ably package)	core constructor
device	the package's unstamped Rest re-export (it ships no HTTP factory)	@ably/pubsub-device createClient
server	@ably/pubsub-server createHttpClient	@ably/pubsub-server createRealtimeClient

A constructor-shaped wrapper keeps new Ably.Realtime(...), instanceof, and statics (PresenceMessage, Crypto, …) working unchanged in every mode.

How the factories reach the mocked core

The factories are imported from packages/{device,server}/src source, with @ably/pubsub-core mapped onto the core's Node.js source entry by a new UTS tsconfig (packages/core/test/uts/tsconfig.json, via TSX_TSCONFIG_PATH). This is load-bearing: the built wrapper dists resolve the core to build/ably-node.js, a second module instance whose Platform singleton the UTS mock installers never touch — pointing the suite at the dists would silently bypass every mock. (The dist artifacts stay covered end-to-end by test:package and the agent wire test on #2293.)

side_modes.test.ts is a harness self-test guarding exactly that failure mode: it asserts each mode's side-declaring agent stamp, so a broken seam or paths mapping fails the leg loudly instead of degrading the per-side runs into duplicates of the core run.

CI

The Test NodeJS (UTS) matrix gains the side dimension: {18.x, 20.x} × {core, device, server}, same two tiers per leg.

Verification

All three modes run locally with identical results: unit tier 1395 passing × 3, integration tier 244 passing × 3, plus the per-mode stamp self-tests. tsc --noEmit over the typedoc project (which includes test/uts) compiles clean, and everything is prettier-formatted.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Tests

  • Expanded unit and integration test coverage across core, device, and server client modes.
  • Added validation for mode-specific client headers and consistent behavior across package entry points.
  • Tests now run against the Node.js source implementation for more reliable results.

• Documentation

  • Documented the available test modes and how to run them.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 15677b34-2ffd-4fb1-847c-876c61cb150b

📥 Commits

Reviewing files that changed from the base of the PR and between 77274cc and 2d70f3f.

📒 Files selected for processing (6)

• .github/workflows/test-node-uts.yml
• package.json
• packages/core/test/uts/README.md
• packages/core/test/uts/helpers.ts
• packages/core/test/uts/side_modes.test.ts
• packages/core/test/uts/tsconfig.json

Disabled knowledge base sources:

• Jira integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

Walkthrough

The UTS harness now selects core, device, or server client construction through UTS_SIDE. A dedicated tsconfig loads Node.js source modules. New self-tests validate agent stamps, and CI runs unit and integration tests for all three modes.

Changes

Per-side UTS execution

Layer / File(s)	Summary
UTS source resolution and invocation packages/core/test/uts/tsconfig.json, package.json, packages/core/test/uts/README.md	UTS commands use a dedicated tsconfig that maps @ably/pubsub-core to the Node.js source entry point. The README documents source-based execution.
Per-side client construction packages/core/test/uts/helpers.ts, packages/core/test/uts/README.md	The helper selects core, device, or server factories from UTS_SIDE and preserves constructor behavior through sideConstructor.
Side validation in CI packages/core/test/uts/side_modes.test.ts, .github/workflows/test-node-uts.yml	The harness checks expected Ably-Agent stamps for each mode. CI runs unit and integration tests with core, device, and server matrix values.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Suggested reviewers: ttypic

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch uts-per-side

---

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

_{A rabbit hops through core and device,
Then server paths join the testing fête,
Agent stamps spring from every request,
Mocked replies arrive in proper state,
Three matrix lanes run clean and bright,
Source-linked tests complete the night.}

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

[ttypic]

LGTM, weirdly github shows no indents for me, but locally in git everything looks good