Add protocol variant convention to UTS integration specs (G1)

Establish a convention for running data-path integration tests with both
JSON and msgpack protocols. Each annotated spec gets a Protocol Variants
section and uses PROTOCOL == "msgpack" instead of hardcoded
useBinaryProtocol: false.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: paddybyers

uts/docs/integration-testing.md

@@ -236,6 +236,66 @@ The goal is: every await in the test is bounded, and the suite timeout is genero
 - Proxy tests should use proxy event logs for verification rather than timing-dependent assertions
 - When tests pass in isolation but fail in the full suite, suspect sandbox rate limiting or connection exhaustion — increase the suite timeout rather than adding retries
 
+## Protocol Variants
+
+The Ably client library spec (G1) requires that tests run with all supported protocols. Integration tests that exercise the data encoding/decoding path must run with both JSON and msgpack to verify data integrity through the full encode-transmit-decode pipeline.
+
+### Which tests need both protocols?
+
+Only tests on the **data path** need both protocols. These are tests where messages, presence data, or other payloads pass through the SDK's encoding layer, through the server, and back. Examples include publish/subscribe round-trips, history retrieval, presence data, delta decoding, and mutable message operations.
+
+Tests for **connection lifecycle**, **authentication**, **channel attach/detach**, and other protocol-agnostic behaviours do not need protocol variants. These tests exercise control-plane operations whose correctness does not depend on the wire encoding of message payloads.
+
+**Proxy tests always use JSON.** The proxy only supports text WebSocket frames, so proxy-based tests cannot use msgpack.
+
+### Spec file convention
+
+A spec file that requires protocol variant testing includes a `## Protocol Variants` section immediately after `## Test Type`:
+
+```markdown
+## Test Type
+Integration test against Ably sandbox
+
+## Protocol Variants
+json, msgpack
+
+Each test in this file runs once per protocol variant. The `PROTOCOL` variable
+is set to `"json"` or `"msgpack"` for the current run. Client options should set
+`useBinaryProtocol: PROTOCOL == "msgpack"`.
+```
+
+The `PROTOCOL` variable is available in pseudocode and is set to `"json"` or `"msgpack"` for the current run. Client options use the standard pattern:
+
+```pseudo
+client = Rest(options: ClientOptions(
+  key: api_key,
+  endpoint: "nonprod:sandbox",
+  useBinaryProtocol: PROTOCOL == "msgpack"
+))
+```
+
+### Default behaviour
+
+Spec files **without** a `## Protocol Variants` section default to JSON only. No special handling is required in derived test implementations for these specs.
+
+### Annotated specs
+
+The following integration test specs are annotated with `## Protocol Variants`:
+
+**REST:**
+- `rest/integration/publish.md`
+- `rest/integration/history.md`
+- `rest/integration/presence.md`
+- `rest/integration/batch_presence.md`
+- `rest/integration/mutable_messages.md`
+
+**Realtime:**
+- `realtime/integration/channels/channel_publish_test.md`
+- `realtime/integration/channel_history_test.md`
+- `realtime/integration/presence_lifecycle_test.md`
+- `realtime/integration/mutable_messages_test.md`
+- `realtime/integration/delta_decoding_test.md`
+
 ## Writing Proxy Tests
 
 The proxy mediates between the SDK and the real Ably server. It is not a mock server. Tests should be written to rely on actual server responses as much as possible, with the proxy intervening only where necessary to create the specific fault or error condition under test.

uts/docs/writing-test-specs.md

@@ -15,6 +15,7 @@ This guide provides comprehensive guidance for writing portable test specificati
 - Run against `https://sandbox.realtime.ably-nonprod.net`
 - Provision apps via `POST /apps` with body from `ably-common/test-resources/test-app-setup.json`
 - Use `endpoint: "nonprod:sandbox"` in ClientOptions
+- **Protocol variants:** Data-path tests (publish, history, presence, etc.) must run with both JSON and msgpack. Add a `## Protocol Variants` section after `## Test Type` and use `useBinaryProtocol: PROTOCOL == "msgpack"` in ClientOptions. See `docs/integration-testing.md` for the full convention. Specs without this header default to JSON only.
 
 ### Proxy Integration Tests (Ably Sandbox via Proxy)
 - Run against Ably Sandbox through a programmable proxy ([ably/uts-proxy](https://github.com/ably/uts-proxy))

uts/realtime/integration/channel_history_test.md

@@ -5,6 +5,13 @@ Spec points: `RTL10d`
 ## Test Type
 Integration test against Ably Sandbox endpoint
 
+## Protocol Variants
+json, msgpack
+
+Each test in this file runs once per protocol variant. The `PROTOCOL` variable
+is set to `"json"` or `"msgpack"` for the current run. Client options should set
+`useBinaryProtocol: PROTOCOL == "msgpack"`.
+
 ## Sandbox Setup
 
 Tests run against the Ably Sandbox at `https://sandbox.realtime.ably-nonprod.net`.

uts/realtime/integration/channels/channel_publish_test.md

@@ -5,6 +5,13 @@ Spec points: `RTL6`, `RTL6f`, `RSL4`, `RSL6`, `RSL6a2`
 ## Test Type
 Integration test against Ably sandbox
 
+## Protocol Variants
+json, msgpack
+
+Each test in this file runs once per protocol variant. The `PROTOCOL` variable
+is set to `"json"` or `"msgpack"` for the current run. Client options should set
+`useBinaryProtocol: PROTOCOL == "msgpack"`.
+
 ## Purpose
 
 End-to-end verification that messages published on one realtime connection are
@@ -50,14 +57,14 @@ publisher = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 subscriber = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 publisher.connect()
@@ -118,14 +125,14 @@ publisher = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 subscriber = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 publisher.connect()
@@ -190,14 +197,14 @@ publisher = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 subscriber = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 publisher.connect()
@@ -259,14 +266,14 @@ publisher = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 subscriber = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 publisher.connect()
@@ -325,14 +332,14 @@ publisher = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 subscriber = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
   autoConnect: false,
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 publisher.connect()

uts/realtime/integration/delta_decoding_test.md

@@ -5,6 +5,13 @@ Spec points: `PC3`, `PC3a`, `RTL18`, `RTL18b`, `RTL18c`, `RTL19b`, `RTL20`
 ## Test Type
 Integration test against Ably sandbox
 
+## Protocol Variants
+json, msgpack
+
+Each test in this file runs once per protocol variant. The `PROTOCOL` variable
+is set to `"json"` or `"msgpack"` for the current run. Client options should set
+`useBinaryProtocol: PROTOCOL == "msgpack"`.
+
 ## Purpose
 
 End-to-end verification of vcdiff delta decoding using real connections against the
@@ -30,7 +37,7 @@ order compared to `VD2a`.
 
 Tests run against the Ably Sandbox at `https://sandbox.realtime.ably-nonprod.net`.
 
-**Note:** `useBinaryProtocol: false` is required if the SDK does not implement msgpack.
+**Note:** `useBinaryProtocol: PROTOCOL == "msgpack"` is used so tests run with both protocols (see Protocol Variants).
 
 ### App Provisioning
 
@@ -93,7 +100,7 @@ counting_decoder = VCDiffDecoder(
 client = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
-  useBinaryProtocol: false,
+  useBinaryProtocol: PROTOCOL == "msgpack",
   plugins: { vcdiff: counting_decoder }
 ))
 ```
@@ -175,7 +182,7 @@ counting_decoder = VCDiffDecoder(
 client = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
-  useBinaryProtocol: false,
+  useBinaryProtocol: PROTOCOL == "msgpack",
   plugins: { vcdiff: counting_decoder }
 ))
 
@@ -257,7 +264,7 @@ counting_decoder = VCDiffDecoder(
 client = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
-  useBinaryProtocol: false,
+  useBinaryProtocol: PROTOCOL == "msgpack",
   plugins: { vcdiff: counting_decoder }
 ))
 ```
@@ -331,7 +338,7 @@ counting_decoder = VCDiffDecoder(
 client = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
-  useBinaryProtocol: false,
+  useBinaryProtocol: PROTOCOL == "msgpack",
   plugins: { vcdiff: counting_decoder }
 ))
 ```
@@ -428,7 +435,7 @@ failing_decoder = FailingVCDiffDecoder()
 client = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
-  useBinaryProtocol: false,
+  useBinaryProtocol: PROTOCOL == "msgpack",
   plugins: { vcdiff: failing_decoder }
 ))
 ```
@@ -507,14 +514,14 @@ channel_name = "delta-no-plugin-" + random_id()
 subscriber = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 
 # Publisher — separate connection, publishes without delta param
 publisher = Realtime(options: ClientOptions(
   key: api_key,
   endpoint: "nonprod:sandbox",
-  useBinaryProtocol: false
+  useBinaryProtocol: PROTOCOL == "msgpack"
 ))
 ```