@roku-sdk/device-test-client 0.0.0-stage → 2.18.0

package/docs/preconditions.md

@@ -0,0 +1,317 @@
+# Preconditions
+
+Preconditions let a test suite say "this test only makes sense on a
+Roku Ultra running firmware 14+ in `en_US`". The SDK exposes three
+forms:
+
+- `itOnDevice` / `describeOnDevice` — **registration-time** `it` /
+`describe` wrappers that call `it.skip()` / `describe.skip()` on
+mismatch. Preferred form.
+- `requirePrecondition` — **synchronous** in-body guard. Throws
+`PreconditionNotMetError` on mismatch (which Jest reports as a test
+**failure**, not a skip).
+
+> **Adoption in `device-tests/`.** The Solid-on-device suites
+> (`lifecycle/`, `deeplink/`, `focus-restore/`, `signals/`,
+> `transactions/`) each wrap their outer `describe` with
+> `describeOnDevice(..., { preconditions: { firmwareVersion: ">=11.0" } })`
+> (the `deeplink/` suite raises the floor to `">=12.0"` for the
+> two-phase `setLaunchParamsUpdateHandler` flow). This makes the
+> minimum-firmware contract executable — a CI runner pointed at
+> older firmware reports `(skipped: requires firmwareVersion>=11.0,
+> device has firmwareVersion=10.x)` in the Jest output instead of
+> flaking mid-deploy. See
+> `device-tests/preconditions/hdr-demo.test.ts` for the canonical
+> two-call showcase (one `describeOnDevice`, one `itOnDevice`).
+- [Core types](#core-types)
+- [Precondition fields](#precondition-fields)
+- [Device-class tiers](#device-class-tiers)
+- `[itOnDevice](#itondevice)`
+- `[describeOnDevice](#describeondevice)`
+- `[requirePrecondition](#requireprecondition)`
+- `[getDeviceClass](#getdeviceclass)`
+- [Skip vs fail](#skip-vs-fail)
+- [Fallback when no snapshot exists](#fallback-when-no-snapshot-exists)
+- [Errors thrown](#errors-thrown)
+
+## Core types
+
+```ts
+interface Precondition {
+    firmwareVersion?: string;          // semver range
+    modelFamily?: string;              // exact, against DeviceInfo.modelFamily
+    deviceClass?: DeviceClass;         // exact, against getDeviceClass(modelName)
+    videoMode?: string;                // prefix match
+    locale?: string;                   // exact
+    country?: string;                  // exact
+    library?: LibraryRequirement;      // NOT IMPLEMENTED — throws PreconditionNotImplementedError
+}
+
+interface LibraryRequirement {
+    name: string;
+    version: string;                   // semver range
+}
+
+type DeviceClass = "high-end" | "mid-range" | "low-end" | "unknown";
+
+interface OnDeviceTestOptions {
+    preconditions?: Precondition;
+    timeout?: number;
+}
+
+interface OnDeviceDescribeOptions {
+    preconditions?: Precondition;
+}
+```
+
+## Precondition fields
+
+
+| Field             | Match strategy                                                   | Example                                                             |
+| ----------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `firmwareVersion` | semver range (Roku 4-part versions coerced to MAJOR.MINOR.PATCH) | `">=14.0"`, `">=12 <14"`, `"^13.0.0"`                               |
+| `modelFamily`     | exact vs `DeviceInfo.modelFamily`                                | `"Roku Ultra"`                                                      |
+| `deviceClass`     | exact vs `getDeviceClass(DeviceInfo.modelName)`                  | `"high-end"`                                                        |
+| `videoMode`       | prefix match vs `DeviceInfo.videoMode`                           | `"1080p"` matches `1080p` and `1080p60`; use `"1080p60"` for strict |
+| `locale`          | exact vs `DeviceInfo.locale`                                     | `"en_US"`                                                           |
+| `country`         | exact vs `DeviceInfo.country`                                    | `"US"`                                                              |
+| `library`         | **not implemented** — always throws                              | —                                                                   |
+
+
+**Evaluation order** is object-key iteration order (insertion order
+for string keys). The caller controls which field produces the error
+when multiple mismatch.
+
+**Invalid semver ranges** throw
+`RkClientError("PRECONDITION_INVALID_SEMVER_RANGE")` loudly — a
+mangled range is a test bug, not a device mismatch.
+
+## Device-class tiers
+
+`DeviceInfo.deviceClass` is Roku's **form-factor** classifier
+(`"tv" | "stick" | "player"`). Tests usually want a performance tier
+instead, derived by `getDeviceClass(modelName)`:
+
+
+| modelName (case-insensitive, "Roku " prefix optional)                                                                                                                                                             | Tier        |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `Ultra`, `Reference RSG-4k`                                                                                                                                                                                       | `high-end`  |
+| `Express 4k`, `Express 4k+`, `Streaming Stick+`, `Streaming Stick 4k`, `Streaming Stick 4k+`, `Premiere`, `Premiere+`, `Ultra LT`, `Roku TV`, `4k Roku TV`, `Roku Ultra LT`, `Streambar Pro`, `Wireless Soundbar` | `mid-range` |
+| `Express`, `Streaming Stick`, `Reference RSG-HD`, `Streambar`                                                                                                                                                     | `low-end`   |
+| anything else                                                                                                                                                                                                     | `unknown`   |
+
+
+Unknown models fall through to `"unknown"` deliberately — a
+`deviceClass: "high-end"` precondition on a brand-new model will
+**skip** until the model has been classified (fail-closed). See
+`[device-class.ts](../src/device/device-class.ts)` for the full
+table.
+
+## `itOnDevice`
+
+```ts
+function itOnDevice(
+    name: string,
+    fn: () => void | Promise<void>,
+    opts?: OnDeviceTestOptions
+): void;
+```
+
+Registration-time wrapper. If the cached `DeviceInfo` snapshot
+(`test-results/device-env.json`, written by `createGlobalSetup`)
+fails the precondition, the test is registered as `it.skip(...)` with
+a `(skipped: requires X, device has Y)` suffix so Jest reporters
+render a useful one-line reason.
+
+**Example — semver gate.**
+
+```ts
+import { itOnDevice } from "@roku-sdk/device-test-client";
+
+itOnDevice(
+    "uses HDR API (14+)",
+    async () => {
+        // ...
+    },
+    { preconditions: { firmwareVersion: ">=14.0" } }
+);
+```
+
+**Example — videoMode + locale.**
+
+```ts
+itOnDevice(
+    "full-HD Spanish layout",
+    async () => {
+        // ...
+    },
+    {
+        preconditions: {
+            videoMode: "1080p",
+            locale: "es_MX"
+        },
+        timeout: 30_000
+    }
+);
+```
+
+**Example — device-class tier.**
+
+```ts
+itOnDevice(
+    "runs 60fps animation only on high-end devices",
+    async () => {
+        // ...
+    },
+    { preconditions: { deviceClass: "high-end" } }
+);
+```
+
+## `describeOnDevice`
+
+```ts
+function describeOnDevice(
+    name: string,
+    fn: () => void,
+    opts?: OnDeviceDescribeOptions
+): void;
+```
+
+Same contract as `itOnDevice`, but gates an entire `describe` block.
+
+**Example.**
+
+```ts
+import { describeOnDevice, itOnDevice } from "@roku-sdk/device-test-client";
+
+describeOnDevice(
+    "player 4K playback",
+    () => {
+        itOnDevice("plays HEVC", async () => { /* ... */ });
+        itOnDevice("plays AV1", async () => { /* ... */ });
+    },
+    { preconditions: { videoMode: "2160p" } }
+);
+```
+
+When the outer gate skips, every test inside the block is reported
+as skipped (standard Jest semantics for `describe.skip`).
+
+## `requirePrecondition`
+
+```ts
+function requirePrecondition(client: RkClient, requirements: Precondition): void;
+```
+
+**Synchronous.** Reads the live `RkClient.cachedDeviceInfo()`. Use it
+for mid-test gates — e.g. after a locale change during the test body
+you want to re-assert on the new locale.
+
+**Example.**
+
+```ts
+import { requirePrecondition } from "@roku-sdk/device-test-client";
+
+test("library screen on firmware 13+", async () => {
+    requirePrecondition(client, { firmwareVersion: ">=13.0" });
+    await client.keypress("Home");
+    // ...
+});
+```
+
+**Important.** A thrown `PreconditionNotMetError` in the test body is
+reported by Jest as a **failure**, not a skip — jest-circus does not
+have a mid-test skip primitive. Prefer `itOnDevice` /
+`describeOnDevice` whenever the intent is "skip on mismatch".
+
+If the cache is empty (no `beforeAll` yet, no `createGlobalSetup`
+snapshot) the call throws
+`RkClientError("PRECONDITION_NO_DEVICE_INFO")` with actionable
+remediation text.
+
+## `getDeviceClass`
+
+```ts
+function getDeviceClass(modelName: string): DeviceClass;
+```
+
+Pure — no I/O, safe from any phase. Occasionally useful in reporters
+or for custom gating.
+
+**Example.**
+
+```ts
+import { getDeviceClass } from "@roku-sdk/device-test-client";
+
+const tier = getDeviceClass("Roku Ultra");  // "high-end"
+```
+
+## Skip vs fail
+
+
+| Mechanism             | Mismatch =                                               |
+| --------------------- | -------------------------------------------------------- |
+| `itOnDevice`          | `it.skip(...)` — reported as **skipped**                 |
+| `describeOnDevice`    | `describe.skip(...)` — reported as **skipped**           |
+| `requirePrecondition` | throw `PreconditionNotMetError` — reported as **failed** |
+
+
+Side-by-side example — same gate, different outcomes:
+
+```ts
+// Skip when not Ultra — good hygiene for the full suite.
+itOnDevice("Ultra-only feature",
+    async () => { /* ... */ },
+    { preconditions: { modelFamily: "Roku Ultra" } }
+);
+
+// Fail when not Ultra — use when the test itself promises an invariant.
+test("Ultra-only feature (hard require)", async () => {
+    requirePrecondition(client, { modelFamily: "Roku Ultra" });
+    // ...
+});
+```
+
+## Fallback when no snapshot exists
+
+`itOnDevice` / `describeOnDevice` read from `test-results/device-env.json`
+**synchronously** at registration time. When the file is missing (e.g.
+a vanilla `jest` invocation without `globalSetup`), the wrapper:
+
+- emits a one-time `console.warn(...)` per test file,
+- registers the test **normally** (no skip).
+
+This mirrors the "tests boot without a device connected" philosophy
+of the rest of the framework — the first real ECP call fails fast
+with actionable remediation.
+
+To ensure the snapshot is always present in CI, call `createGlobalSetup`
+from your `jest.config.ts` (see
+[Jest integration](jest-integration.md)).
+
+## `library` — not implemented
+
+The `library` field **always throws** `PreconditionNotImplementedError`.
+Roku's ECP surface does not reliably report library versions, so we
+fail loudly rather than silently passing.
+
+`PreconditionNotImplementedError` extends `PreconditionNotMetError`,
+so `itOnDevice` / `describeOnDevice` route it through the same skip
+path — tests that gate on a library version are skipped with a
+"library version checks are not implemented" message.
+
+## Errors thrown
+
+- `PreconditionNotMetError` — a field mismatched. Fields: `field`,
+`expected`, `actual`, `reason`.
+- `PreconditionNotImplementedError` (extends
+`PreconditionNotMetError`) — the `library` field is always a
+not-implemented mismatch. Fields: `feature`, `field`, `expected`,
+`actual`.
+- `RkClientError("PRECONDITION_INVALID_SEMVER_RANGE")` — a
+`firmwareVersion` range failed `semver.validRange`.
+- `RkClientError("PRECONDITION_NO_DEVICE_INFO")` —
+`requirePrecondition` called before the cache was populated.
+
+Full field lists and recovery advice in
+`[errors.md](errors.md)`.