@specific.dev/spectest 0.35.0 → 0.35.1

package/dist/index.d.ts

@@ -1390,16 +1390,43 @@ export declare function expect(actual: Locator, message?: string): LocatorAssert
 export declare function expect(actual: Browser, message?: string): BrowserAssertion;
 export declare function expect(actual: Provenanced, message?: string): Expectation;
 /**
- * Assert on a value with **no provenance** — a computed number, a raw
- * WebSocket frame, anything that didn't flow from a recorded op. `message` is
- * required (it's the second argument) and reads as the natural follow-on to
- * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
- * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
- * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
- * the value carries provenance — only reach for this when the type gate would
- * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
- * mandatory, since the label is the only human-meaningful summary a raw
- * assertion has.)
+ * Assert on a value with **no provenance** — a computed number, a frame read
+ * off a raw `WebSocket` you opened yourself, anything that never flowed from a
+ * recorded op. `message` is required (it's the second argument) and reads as
+ * the natural follow-on to "assert …" (e.g.
+ * `expectRaw(id, "id matches the generated value")`); it renders as the
+ * assertion's label in the CLI/dashboard ("ASSERT <message>") since a raw
+ * assertion has no op to nest under. (`expect`'s own `message` is optional;
+ * here it is mandatory, since the label is the only human-meaningful summary a
+ * raw assertion has.)
+ *
+ * **This is an escape hatch, and reaching for it is almost always a mistake.**
+ * A raw assertion is *deliberately* unlinked: it renders as a disconnected
+ * top-level row with no op above it, so whoever reads the failure can't see the
+ * request, query, or command the value came from. Using it to get past
+ * `expect`'s compile-time provenance gate is an anti-pattern — the gate rejects
+ * a value precisely because its provenance was destroyed on the way in, and
+ * this doesn't restore it, it just accepts the loss.
+ *
+ * Nearly every real use is a *wrapped* value that got flattened by `.unwrap()`,
+ * `String(x)`, `JSON.parse(x)`, `x.length`, or a home-grown coercion helper.
+ * Keep it wrapped instead:
+ *
+ * ```ts
+ * // ✗ flattened, then asserted raw — the link to the op is gone
+ * expectRaw(JSON.parse(res.body.unwrap()).tier, "tier is pro").toBe("pro");
+ * expectRaw(rows.length, "one row").toBe(1);
+ *
+ * // ✓ same checks, still nested under the http / db step
+ * expect(res.body.transform<{ tier: string }>("json", (s) => JSON.parse(s)).tier).toBe("pro");
+ * expect(rows).toHaveLength(1);
+ * ```
+ *
+ * `.transform(label, fn)` carries the source op's tag through a decode,
+ * `toHaveLength` reads a length without severing it, and a nullish leaf read
+ * inline in `expect(...)` (or via `field`) recovers its own tag. If the value
+ * came from a `fetch`/db/exec/browser/fake/kube op at any point, there is a
+ * wrapped way to assert on it — see the `/tests` docs page.
  */
 export declare function expectRaw(actual: unknown, message: string): Expectation;
 /** `node:assert/strict` re-exported for users who prefer Node's built-in API. */

package/dist/index.js

@@ -657,16 +657,43 @@ function buildBrowserMatchers(session, negated, message) {
     };
 }
 /**
- * Assert on a value with **no provenance** — a computed number, a raw
- * WebSocket frame, anything that didn't flow from a recorded op. `message` is
- * required (it's the second argument) and reads as the natural follow-on to
- * "assert …" (e.g. `expectRaw(id, "id matches the generated value")`); it
- * renders as the assertion's label in the CLI/dashboard ("ASSERT <message>")
- * since a raw assertion has no op to nest under. Prefer `expect(...)` whenever
- * the value carries provenance — only reach for this when the type gate would
- * (rightly) reject the value. (`expect`'s own `message` is optional; here it is
- * mandatory, since the label is the only human-meaningful summary a raw
- * assertion has.)
+ * Assert on a value with **no provenance** — a computed number, a frame read
+ * off a raw `WebSocket` you opened yourself, anything that never flowed from a
+ * recorded op. `message` is required (it's the second argument) and reads as
+ * the natural follow-on to "assert …" (e.g.
+ * `expectRaw(id, "id matches the generated value")`); it renders as the
+ * assertion's label in the CLI/dashboard ("ASSERT <message>") since a raw
+ * assertion has no op to nest under. (`expect`'s own `message` is optional;
+ * here it is mandatory, since the label is the only human-meaningful summary a
+ * raw assertion has.)
+ *
+ * **This is an escape hatch, and reaching for it is almost always a mistake.**
+ * A raw assertion is *deliberately* unlinked: it renders as a disconnected
+ * top-level row with no op above it, so whoever reads the failure can't see the
+ * request, query, or command the value came from. Using it to get past
+ * `expect`'s compile-time provenance gate is an anti-pattern — the gate rejects
+ * a value precisely because its provenance was destroyed on the way in, and
+ * this doesn't restore it, it just accepts the loss.
+ *
+ * Nearly every real use is a *wrapped* value that got flattened by `.unwrap()`,
+ * `String(x)`, `JSON.parse(x)`, `x.length`, or a home-grown coercion helper.
+ * Keep it wrapped instead:
+ *
+ * ```ts
+ * // ✗ flattened, then asserted raw — the link to the op is gone
+ * expectRaw(JSON.parse(res.body.unwrap()).tier, "tier is pro").toBe("pro");
+ * expectRaw(rows.length, "one row").toBe(1);
+ *
+ * // ✓ same checks, still nested under the http / db step
+ * expect(res.body.transform<{ tier: string }>("json", (s) => JSON.parse(s)).tier).toBe("pro");
+ * expect(rows).toHaveLength(1);
+ * ```
+ *
+ * `.transform(label, fn)` carries the source op's tag through a decode,
+ * `toHaveLength` reads a length without severing it, and a nullish leaf read
+ * inline in `expect(...)` (or via `field`) recovers its own tag. If the value
+ * came from a `fetch`/db/exec/browser/fake/kube op at any point, there is a
+ * wrapped way to assert on it — see the `/tests` docs page.
  */
 export function expectRaw(actual, message) {
     // Force the raw form so no stray tag is read even if a wrapped value is

package/dist/inspect.d.ts

@@ -106,8 +106,14 @@ export interface Carrier<T> {
  * `null`/`undefined` are also admitted: a nullish leaf can't carry the symbol
  * tag, but `adoptNullishTag` recovers its provenance at runtime, so
  * `expect(rows[0]?.text)` and `expect(dep.status.readyReplicas)` stay on
- * `expect`. To assert on a value with no provenance (a computed number, a raw
- * WebSocket frame), use `expectRaw(value, message)` instead.
+ * `expect`.
+ *
+ * When this gate rejects a value, the fix is usually to stop flattening it —
+ * `.transform(label, fn)` instead of a decode-then-`.unwrap()`, `toHaveLength`
+ * instead of `.length` — not to switch to `expectRaw`, which accepts anything
+ * but renders the assertion unlinked. Reach for `expectRaw(value, message)`
+ * only when the value never flowed from a recorded op at all (a computed
+ * number, a frame off a raw WebSocket); see its own doc comment.
  */
 export type Provenanced = {
     unwrap(): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.35.0",
+  "version": "0.35.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",