@roku-sdk/device-test-client 2.18.0 → 2.19.0

package/BREAKING_CHANGES.md

@@ -0,0 +1,17 @@
+# Breaking Changes
+
+## `./internal/*` subpaths removed
+
+The `./internal/*` subpaths are removed. The harness helpers that were reachable only through `./internal/deploy`, `./internal/constants`
+and `./internal/paths` have documented entry points with the same contents:
+
+| Before | After |
+|--------|-------|
+| `@roku-sdk/device-test-client/internal/deploy` | `@roku-sdk/device-test-client/support/deploy` |
+| `@roku-sdk/device-test-client/internal/constants` | `@roku-sdk/device-test-client/support/constants` |
+| `@roku-sdk/device-test-client/internal/paths` | `@roku-sdk/device-test-client/support/paths` |
+
+`ARTIFACT_FILE` is also exported from the package root.
+
+**Migration.** Replace `/internal/` with `/support/` in these imports. The `support/constants`
+and `support/paths` entry points stay safe to import from a CommonJS-mode `jest.config.ts`.

package/docs/errors.md

@@ -132,12 +132,19 @@ Known `context.reason` values: `"readiness-timeout"`,
 
 `"never-left-home"` is special. It means the device answered ECP for
 the entire readiness budget but never foregrounded the sideloaded
-channel — an **unrecoverable-on-this-VM** condition (a wedged
-device host). It latches the device **fatal**
-(`markDeviceFatal`), not merely unhealthy, so downstream deploys
-fast-skip and the recovery `beforeEach` refuses to revive it. See
+channel. On a device that has not been seen foregrounding a channel
+at all, that is an **unrecoverable-on-this-VM** condition (a wedged
+device host): it latches the device **fatal** (`markDeviceFatal`),
+not merely unhealthy, so downstream deploys fast-skip and the
+recovery `beforeEach` refuses to revive it. See
 [Fatal device wedge](#fatal-device-wedge) below.
 
+Once any deploy has put a channel on screen, the same observation
+carries the softer meaning — a launch slower than the budget looks
+identical from inside one deploy — so it only flips soft health and
+the deploy-guard retries that deploy. The `reason` tag reports what
+was observed either way; only the verdict differs.
+
 ---
 
 ## Lifecycle health
@@ -190,7 +197,12 @@ There are two device-health states, exposed as separate helper sets:
 
 `markDeviceFatal` also flips the soft flag, so the existing cascade
 keeps firing and you never need to call both. Currently only
-`DeployFailedError({ reason: "never-left-home" })` latches fatal.
+`DeployFailedError({ reason: "never-left-home" })` latches fatal, and
+only on a device with no record of foregrounding a channel. A deploy
+that put one on screen calls `markChannelForegrounded`, which keeps
+later stalled launches on that VM soft — the latch costs the whole
+shard plus a lease recycle, so it is reserved for the case the
+device's own history does not contradict.
 
 Consequences once fatal is latched (single `--runInBand` process):
 
@@ -431,7 +443,14 @@ class WaitForLogTimeoutError extends Error {
 }
 ```
 
-Thrown by `waitForLog` on timeout.
+Thrown by `waitForLog` on timeout. `linesChecked === 0` means no
+output at all reached the window, re-attach included. That narrows the
+cause but does not settle it: an app with nothing to log in those few
+seconds and a stream stalled at its far end look the same from here,
+and a short window around a quiet moment is the ordinary case. What it
+does rule out is a line lost between the server and this process,
+which the re-attach would have replayed. The message names both
+readings.
 
 ### `UnexpectedLogError`
 

package/docs/log-assertions.md

@@ -99,6 +99,9 @@ Resolves with the first line matching `pattern` whose seq >=
 - throws `LogStreamGapError` on timeout if any gap was recorded in
   the wait window — the missing lines might have included the
   marker, so the timeout is ambiguous, not a clean negative;
+- re-attaches the stream once, and waits a further
+  `LOG_STREAM_RESYNC_GRACE_MS`, when the window received no line at
+  all (see [Silent windows](#silent-windows));
 - throws `WaitForLogTimeoutError` on timeout with `recentLines`,
   `position`, `timeout`.
 
@@ -234,6 +237,38 @@ reconnect because its truth value is sensitive to lines we did not
 see. `logs` is a bulk read with no soundness contract beyond "what
 is in the buffer right now"; it does not throw on gaps.
 
+### Silent windows
+
+Gaps only describe reconnects the stream reported. A subscription can
+also stop delivering while both ends still consider it attached — the
+server's heartbeat probes the device over ECP, which keeps answering
+— and then nothing is reported, nothing is closed, and no gap is
+recorded. From inside a wait that is indistinguishable from a device
+with nothing to say.
+
+`waitForLog` treats a window in which **no line arrived at all** as
+exactly that: no evidence either way. Before calling the marker
+absent it asks `LogSession.resync()` for a fresh subscription and
+waits `LOG_STREAM_RESYNC_GRACE_MS` longer. `/logs/tail` replays the
+whole server-side buffer on attach and `lastServerSeq` drops the
+duplicates, so a line only the subscription leg lost arrives through
+the still-live subscription and resolves the wait. Nothing is
+recorded as a gap — a replay fills the window rather than losing it,
+and an open gap would mark the replayed lines themselves suspect.
+
+If the re-attach also delivers nothing, the timeout stands. What that
+rules out is a line lost between the server and this process, which
+the replay would have carried; what it leaves is an app with nothing
+to log in those few seconds and a stream stalled at its far end,
+which are indistinguishable from here. A short window around a quiet
+moment is much the commoner of the two, so the message names both
+rather than reporting a transport fault. The re-attach is kept
+regardless, so the next assertion in the file starts on a live
+subscription instead of inheriting the silence.
+
+`expectNoLog` does not yet do this, and a silent stream therefore
+satisfies it vacuously.
+
 ### Why the asymmetry is sound
 
 `since` is captured before the action, so any seq `>= since` is

package/docs/rkclient.md

@@ -646,7 +646,9 @@ advice live in `[errors.md](errors.md)`.
 The `never-left-home` reason latches the device **fatal**
 (`markDeviceFatal` / `isDeviceFatal` / `getFatalReason`) — an
 unrecoverable-on-this-VM wedge that disables recovery and fast-skips
-downstream deploys; see [errors.md](errors.md#fatal-device-wedge)
+downstream deploys — but only while no deploy has put a channel on
+screen; after that it stays soft and retryable. See
+[errors.md](errors.md#fatal-device-wedge)
 - Polling — `WaitForNodeTimeoutError`, `AppCrashedError`,
 `ScreenshotNotStableError`
 - Logs (see [log-assertions.md](log-assertions.md)) —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roku-sdk/device-test-client",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "Roku SDK on-device integration test client (RkClient, DOM/screenshot/log assertions, Jest wiring).",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,23 +13,24 @@
       "types": "./src/jest/device-test-environment.ts",
       "default": "./src/jest/device-test-environment.ts"
     },
-    "./internal/deploy": {
-      "types": "./internal/deploy.ts",
-      "default": "./internal/deploy.ts"
+    "./support/deploy": {
+      "types": "./support/deploy.ts",
+      "default": "./support/deploy.ts"
     },
-    "./internal/constants": {
-      "types": "./internal/constants.ts",
-      "default": "./internal/constants.ts"
+    "./support/constants": {
+      "types": "./support/constants.ts",
+      "default": "./support/constants.ts"
     },
-    "./internal/paths": {
-      "types": "./internal/paths.ts",
-      "default": "./internal/paths.ts"
+    "./support/paths": {
+      "types": "./support/paths.ts",
+      "default": "./support/paths.ts"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "src/**/*",
-    "internal/**/*",
+    "support/**/*",
+    "BREAKING_CHANGES.md",
     "docs/**/*",
     "README.md"
   ],
@@ -54,11 +55,11 @@
     "pixelmatch": "^5.3.0",
     "pngjs": "^7.0.0",
     "semver": "^7.6.0",
-    "@roku-sdk/tooling": "2.18.0"
+    "@roku-sdk/tooling": "2.19.0"
   },
   "peerDependencies": {
     "jest-environment-node": ">=29.7.0",
-    "@roku-sdk/tooling": "^2.18.0"
+    "@roku-sdk/tooling": "^2.19.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
@@ -72,8 +73,8 @@
     "ts-jest": "^29.4.6",
     "typescript": "5.5.4",
     "ulid": "^2.3.0",
-    "@roku-sdk/dev-tools": "2.18.0",
-    "@roku-sdk/tooling": "2.18.0"
+    "@roku-sdk/dev-tools": "2.19.0",
+    "@roku-sdk/tooling": "2.19.0"
   },
   "scripts": {
     "test": "jest",

package/src/client/build-cache.ts

@@ -77,10 +77,10 @@
  * to disk. Otherwise a later hit for the old key would skip rebuild
  * and sideload bytes produced by the newer sibling build.
  *
- * Exported via `./internal/deploy` (not the public barrel) because
- * it is an integration-test scaffolding helper, not a partner-
- * facing API. Treat any change here as a breaking change to that
- * internal subpath and the deploy-guard contract together.
+ * Exported via `./support/deploy` (not the public barrel) because
+ * it is a harness helper, not something test bodies call. Treat any
+ * change here as a change to that entry point and the deploy-guard
+ * contract together.
  */
 
 /**