@specific.dev/spectest 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./src/index.ts",

package/src/index.ts

@@ -1350,6 +1350,8 @@ interface Matchers {
   toBeFalsy(): void;
   toBeGreaterThan(n: number): void;
   toBeLessThan(n: number): void;
+  toBeGreaterThanOrEqual(n: number): void;
+  toBeLessThanOrEqual(n: number): void;
   toContain(expected: unknown): void;
   toMatch(re: RegExp): void;
   toHaveLength(n: number): void;
@@ -1359,12 +1361,19 @@ export interface Expectation extends Matchers {
   not: Matchers;
 }
 
-export function expect(actual: Provenanced): Expectation {
-  // The parameter is typed to the {@link Provenanced} family so a raw value
-  // (`expect(res.status === 200)`, `expect(2 + 2)`) is a *compile error* — every
-  // assertion that reaches the timeline this way carries a provenance link back
-  // to the op that produced it. Assert on a genuinely raw value with
-  // `expectRaw(message, value)` instead.
+export function expect(actual: Provenanced, message?: string): Expectation {
+  // The first parameter is typed to the {@link Provenanced} family so a raw
+  // value (`expect(res.status === 200)`, `expect(2 + 2)`) is a *compile error* —
+  // every assertion that reaches the timeline this way carries a provenance link
+  // back to the op that produced it. Assert on a genuinely raw value with
+  // `expectRaw(value, message)` instead.
+  //
+  // `message` is an **optional** human label for the assertion. The UI already
+  // renders the target, matcher, and expected value, so a message that just
+  // restates them is noise — supply one *only* when the check's intent isn't
+  // obvious from those alone (e.g.
+  // `expect(res.status, "blocked once the rate limit trips").toBe(429)`). When
+  // present it leads the assertion's summary, the same way `expectRaw`'s does.
   //
   // A `null`/`undefined` read off a wrapped op result reaches here untagged
   // (a symbol can't ride on nullish). `adoptNullishTag` recovers the tag from
@@ -1372,20 +1381,22 @@ export function expect(actual: Provenanced): Expectation {
   // `expect(dep.status.readyReplicas).toBeFalsy()` nests under its op just like
   // a non-nullish read. Done once here (not in `buildMatchers`) so the `.not`
   // re-pass reuses the same tagged holder instead of re-consuming the note.
-  return buildMatchers(adoptNullishTag(actual), false);
+  return buildMatchers(adoptNullishTag(actual), false, 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 and reads as the natural follow-on to "assert …" (e.g.
- * `expectRaw("id matches the generated value", id)`); 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.
+ * 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.)
  */
-export function expectRaw(message: string, actual: unknown): Expectation {
+export function expectRaw(actual: unknown, message: string): Expectation {
   // Force the raw form so no stray tag is read even if a wrapped value is
   // passed: an `expectRaw` assertion is *deliberately* unlinked, rendered at
   // top level under its own message rather than nested beneath an op.
@@ -1425,7 +1436,7 @@ function buildCore(
     cond: boolean,
     msg: string,
     expectedFor?: unknown,
-    opts?: { actual?: unknown; pathSuffix?: string },
+    opts?: { actual?: unknown },
   ): void => {
     // A failed upstream transform short-circuits every matcher to a failure —
     // there is no meaningful value to match, and negation can't rescue a value
@@ -1455,9 +1466,7 @@ function buildCore(
       error: passed ? undefined : msg,
       message,
       sourceSeq: tag?.sourceSeq,
-      path: tag
-        ? [...tag.path, ...(opts?.pathSuffix ? [opts.pathSuffix] : [])]
-        : undefined,
+      path: tag ? [...tag.path] : undefined,
     });
     if (!passed) throw new ExpectationError(msg);
   };
@@ -1516,6 +1525,22 @@ function buildCore(
         n,
       );
     },
+    toBeGreaterThanOrEqual(n) {
+      run(
+        "toBeGreaterThanOrEqual",
+        typeof actual === "number" && actual >= n,
+        `expected ${fmt(actual)}${negated ? " not" : ""} to be >= ${n}`,
+        n,
+      );
+    },
+    toBeLessThanOrEqual(n) {
+      run(
+        "toBeLessThanOrEqual",
+        typeof actual === "number" && actual <= n,
+        `expected ${fmt(actual)}${negated ? " not" : ""} to be <= ${n}`,
+        n,
+      );
+    },
     toContain(expected) {
       const exp = readRaw(expected);
       let contained = false;
@@ -1560,13 +1585,19 @@ function buildCore(
               typeof (actual as { length?: unknown }).length === "number"
             ? ((actual as { length: number }).length as number)
             : undefined;
+      // The provenance `path` stays the container's own path — `.length` is
+      // the matcher's internal read, not a property access the author wrote,
+      // so it doesn't belong in the path (recording it produced a redundant
+      // "length toHaveLength N" in the UI, since the matcher name already says
+      // "length"). `actual` is still the length number: that's what's worth
+      // showing on failure, and the `toHaveLength` matcher disambiguates it.
       run(
         "toHaveLength",
         len === n,
         `expected ${fmt(actual)}${negated ? " not" : ""} to have length ${n}` +
           (len === undefined ? " (value has no length)" : ` (got ${len})`),
         n,
-        { actual: len, pathSuffix: "length" },
+        { actual: len },
       );
     },
     get not(): Matchers {

package/src/inspect.ts

@@ -482,7 +482,7 @@ export interface Carrier<T> {
  * 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(message, value)` instead.
+ * WebSocket frame), use `expectRaw(value, message)` instead.
  */
 export type Provenanced = { unwrap(): unknown } | null | undefined;
 

package/src/recorder.ts

@@ -84,11 +84,13 @@ export interface AssertionEvent extends BaseEvent {
   /** Failure message produced by the matcher (only when `passed` is false). */
   error?: string;
   /**
-   * Author-supplied label for a raw assertion made via
-   * `expectRaw(message, …)`. Renders as the assertion's summary
-   * ("ASSERT <message>") and serves as its diff-alignment key, since a raw
-   * assertion has no provenance `path`. Absent for provenance-linked
-   * `expect(...)` assertions.
+   * Author-supplied label for the assertion. **Required** for a raw assertion
+   * (`expectRaw(value, message)`), where it renders as the summary
+   * ("ASSERT <message>") and serves as the diff-alignment key since a raw
+   * assertion has no provenance `path`. **Optional** for a provenance-linked
+   * `expect(value, message)`, where it leads the summary as a clarifying note
+   * alongside the rendered matcher/target. Absent when `expect(...)` was called
+   * without a message.
    */
   message?: string;
   /**