@uniflowed/test 0.0.0-alpha.1 → 0.0.0-alpha.4

package/index.js

@@ -15,7 +15,7 @@
 export type { Body as TestBody, Case, Modifier, Suite, TestOptions } from "./internal/registry.js";
 export type { Outcome, Result, RunOptions } from "./internal/run.js";
 export type { Site } from "./internal/frames.js";
-export type { SpyCall } from "./internal/expect.js";
+export type { SpyCall, SpyResult } from "./internal/spy.js";
 export type { Strictness } from "./internal/equality.js";
 
 export {
@@ -28,7 +28,24 @@ export {
   test,
 } from "./internal/registry.js";
 
-export { AssertionError, expect, fn } from "./internal/expect.js";
+export { AssertionError, expect } from "./internal/expect.js";
+
+export { fn, spyOn } from "./internal/spy.js";
+
+/**
+ * Spies, stubs, a controllable clock, and waiting — under uf's own name.
+ *
+ * The same operations Vitest groups under `vi`, so a suite being ported keeps
+ * its shape; the name is uf's, because borrowing another tool's brand for it
+ * would be claiming something uf has not earned.
+ *
+ * A namespace rather than loose named exports, because several of these names
+ * are generic enough to collide: `@uniflowed/testing` re-exports both this
+ * package and `@uniflowed/react-testing`, and both have a `waitFor`.
+ */
+export { UnsupportedError, uft } from "./internal/namespace.js";
+
+export { RunawayTimersError } from "./internal/timers.js";
 
 export { DEFAULT_TIMEOUT_MS, NAME_SEPARATOR } from "./internal/run.js";
 

package/internal/asymmetric.js

@@ -0,0 +1,184 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: `expect.any`, `expect.objectContaining`, and
+// the rest of the matchers that stand in for a value instead of being one.
+//
+// They exist because most assertions are about the parts of a value a test
+// controls, and equality is about all of it. `expect(user).toEqual({ id:
+// expect.any(String), name: "uf" })` says what the test means; spelling out the
+// id would either be a lie or a second source of truth.
+//
+// The mechanism is one method. A matcher is an object carrying
+// `asymmetricMatch(received)`, and `equals` asks any value it meets whether it
+// is one — so a matcher nested six levels down inside an expected object works
+// for the same reason a top-level one does, with no special case anywhere.
+// Vitest and Jest use the same protocol, which is why a matcher from either
+// works here.
+
+// `equality` and this module are mutually recursive, and that is the domain:
+// comparing two values has to recognise a matcher, and a matcher has to compare
+// recursively. ESM handles a cycle between hoisted function declarations — by
+// the time any matcher runs, both modules have finished evaluating — and the
+// alternative was wiring the comparison in at load, which is an import-time side
+// effect and the one thing every shipped module here is forbidden.
+import { equals } from "./equality.js";
+
+/** The brand every matcher carries, so `equals` can recognise one. */
+const ASYMMETRIC = "$$uf.asymmetricMatch";
+
+/** A stand-in for a value, rather than a value. */
+export type AsymmetricMatcher = {
+  readonly [typeof ASYMMETRIC]: true,
+  readonly asymmetricMatch: (received: mixed) => boolean,
+  readonly toString: () => string,
+};
+
+/**
+ * Whether `value` is a matcher rather than something to compare against.
+ *
+ * Duck-typed on `asymmetricMatch` as well as uf's own brand, so a matcher built
+ * by Jest or Vitest — or by a project's own helper — is recognised too. The
+ * protocol is the interface; the brand is only a fast path.
+ */
+export function isAsymmetric(value: mixed): boolean {
+  if (value == null || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value as $FlowFixMe;
+  return candidate[ASYMMETRIC] === true || typeof candidate.asymmetricMatch === "function";
+}
+
+/** Ask a matcher whether `received` satisfies it. */
+export function matchesAsymmetric(matcher: mixed, received: mixed): boolean {
+  return (matcher as $FlowFixMe).asymmetricMatch(received) === true;
+}
+
+/** Build a matcher from a predicate and how it describes itself. */
+function matcher(label: string, predicate: (received: mixed) => boolean): AsymmetricMatcher {
+  return {
+    [ASYMMETRIC]: true,
+    asymmetricMatch: predicate,
+    toString: () => label,
+  };
+}
+
+/**
+ * Anything constructed by `constructor`, or any value of a primitive's type.
+ *
+ * `expect.any(String)` accepts `"uf"` as well as `new String("uf")`, because a
+ * string literal is not an instance of anything and a test that wrote
+ * `expect.any(String)` meant the type rather than the wrapper. The same for
+ * `Number`, `Boolean`, `BigInt`, `Symbol` and `Function`.
+ */
+export function any(constructor: mixed): AsymmetricMatcher {
+  const name = (constructor as $FlowFixMe)?.name ?? String(constructor);
+  return matcher(`Any<${name}>`, (received) => {
+    switch (constructor) {
+      case String:
+        return typeof received === "string" || received instanceof String;
+      case Number:
+        return typeof received === "number" || received instanceof Number;
+      case Boolean:
+        return typeof received === "boolean" || received instanceof Boolean;
+      case BigInt:
+        return typeof received === "bigint";
+      case Symbol:
+        return typeof received === "symbol";
+      case Function:
+        return typeof received === "function";
+      case Object:
+        // `Object` means "any non-null object", which is what a test asking for
+        // one means — not "has Object.prototype in its chain", which a
+        // null-prototype object would fail and a test would find baffling.
+        return received != null && (typeof received === "object" || typeof received === "function");
+      default:
+        return typeof constructor === "function" && received instanceof constructor;
+    }
+  });
+}
+
+/** Anything at all except `null` and `undefined`. */
+export function anything(): AsymmetricMatcher {
+  return matcher("Anything", (received) => received != null);
+}
+
+/**
+ * An object with at least these properties, compared with `equals`.
+ *
+ * The comparison is recursive, so a matcher nested inside `expected` works.
+ */
+export function objectContaining(expected: interface {}): AsymmetricMatcher {
+  return matcher(`ObjectContaining(${describe(expected)})`, (received) => {
+    if (received == null || typeof received !== "object") {
+      return false;
+    }
+    const target = received as $FlowFixMe;
+    const source = expected as $FlowFixMe;
+    for (const key of Object.keys(source)) {
+      if (!(key in target) || !equals(target[key], source[key])) {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+
+/** An array holding at least these elements, in any order. */
+export function arrayContaining(expected: $ReadOnlyArray<mixed>): AsymmetricMatcher {
+  return matcher(`ArrayContaining(${describe(expected)})`, (received) => {
+    if (!Array.isArray(received)) {
+      return false;
+    }
+    return expected.every((wanted) => received.some((item) => equals(item, wanted)));
+  });
+}
+
+/** A string containing `substring`. */
+export function stringContaining(substring: string): AsymmetricMatcher {
+  return matcher(`StringContaining(${JSON.stringify(substring)})`, (received) => {
+    return typeof received === "string" && received.includes(substring);
+  });
+}
+
+/** A string the pattern matches. */
+export function stringMatching(pattern: string | RegExp): AsymmetricMatcher {
+  return matcher(`StringMatching(${String(pattern)})`, (received) => {
+    if (typeof received !== "string") {
+      return false;
+    }
+    return typeof pattern === "string" ? received.includes(pattern) : pattern.test(received);
+  });
+}
+
+/** Default digits of precision for `closeTo`, matching Jest and Vitest. */
+const CLOSE_TO_DIGITS = 2;
+
+/**
+ * A number within `10 ** -digits / 2` of `expected`.
+ *
+ * The same tolerance `toBeCloseTo` uses, so the asymmetric form and the matcher
+ * agree — a test that moves an assertion from one to the other should not have
+ * its verdict change.
+ */
+export function closeTo(expected: number, digits: number = CLOSE_TO_DIGITS): AsymmetricMatcher {
+  const tolerance = 10 ** -digits / 2;
+  return matcher(`CloseTo(${expected}, ${digits})`, (received) => {
+    return typeof received === "number" && Math.abs(received - expected) < tolerance;
+  });
+}
+
+/** A matcher that holds when `inner` does not. */
+export function not(inner: AsymmetricMatcher): AsymmetricMatcher {
+  return matcher(`Not(${inner.toString()})`, (received) => !matchesAsymmetric(inner, received));
+}
+
+/** A short rendering of an expected value, for a matcher's own name. */
+function describe(value: mixed): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    // A cyclic or otherwise unserialisable expectation still has to have a
+    // name; what it is called matters less than that naming it cannot throw.
+    return String(value);
+  }
+}

package/internal/equality.js

@@ -18,10 +18,12 @@
 // * `toEqual` ignores `undefined` properties and `toStrictEqual` does not,
 //   which is the one place the two matchers differ besides prototypes.
 
+import { isAsymmetric, matchesAsymmetric } from "./asymmetric.js";
+
 /** How strictly two values are compared. */
 export type Strictness = "loose" | "strict";
 
-type Pair = {| +left: mixed, +right: mixed |};
+type Pair = {| readonly left: mixed, readonly right: mixed |};
 
 /** Longest rendering of one value inside a failure message. */
 export const MAX_RENDER_BYTES: number = 4096;
@@ -58,10 +60,15 @@ function ownKeys(value: interface {}, strictness: Strictness): Array<string | sy
   }
   // `toEqual` treats an absent property and one set to `undefined` as the
   // same thing, so a key holding `undefined` is not a difference.
-  return keys.filter((key) => (value: $FlowFixMe)[key] !== undefined);
+  return keys.filter((key) => (value as $FlowFixMe)[key] !== undefined);
 }
 
-function sameSet(left: Set<mixed>, right: Set<mixed>, seen: Array<Pair>, strictness: Strictness): boolean {
+function sameSet(
+  left: Set<mixed>,
+  right: Set<mixed>,
+  seen: Array<Pair>,
+  strictness: Strictness,
+): boolean {
   if (left.size !== right.size) {
     return false;
   }
@@ -114,6 +121,16 @@ export function equals(
   if (Object.is(left, right)) {
     return true;
   }
+  // A matcher stands in for a value rather than being one, and either side may
+  // be the expectation depending on which way round the caller passed them.
+  // Asking here rather than at the top level is what makes a matcher nested six
+  // levels down work for the same reason a top-level one does.
+  if (isAsymmetric(right)) {
+    return matchesAsymmetric(right, left);
+  }
+  if (isAsymmetric(left)) {
+    return matchesAsymmetric(left, right);
+  }
   if (!isObject(left) || !isObject(right)) {
     return false;
   }
@@ -150,14 +167,14 @@ export function equals(
   }
   if (ArrayBuffer.isView(left) && ArrayBuffer.isView(right)) {
     const leftBytes = new Uint8Array(
-      (left: $FlowFixMe).buffer,
-      (left: $FlowFixMe).byteOffset,
-      (left: $FlowFixMe).byteLength,
+      (left as $FlowFixMe).buffer,
+      (left as $FlowFixMe).byteOffset,
+      (left as $FlowFixMe).byteLength,
     );
     const rightBytes = new Uint8Array(
-      (right: $FlowFixMe).buffer,
-      (right: $FlowFixMe).byteOffset,
-      (right: $FlowFixMe).byteLength,
+      (right as $FlowFixMe).buffer,
+      (right as $FlowFixMe).byteOffset,
+      (right as $FlowFixMe).byteLength,
     );
     if (leftBytes.length !== rightBytes.length) {
       return false;
@@ -176,8 +193,8 @@ export function equals(
     return false;
   }
 
-  const leftKeys = ownKeys((left: $FlowFixMe), strictness);
-  const rightKeys = ownKeys((right: $FlowFixMe), strictness);
+  const leftKeys = ownKeys(left as $FlowFixMe, strictness);
+  const rightKeys = ownKeys(right as $FlowFixMe, strictness);
   if (leftKeys.length !== rightKeys.length) {
     return false;
   }
@@ -185,7 +202,7 @@ export function equals(
     if (!Object.prototype.hasOwnProperty.call(right, key)) {
       return false;
     }
-    if (!equals((left: $FlowFixMe)[key], (right: $FlowFixMe)[key], nested, strictness)) {
+    if (!equals((left as $FlowFixMe)[key], (right as $FlowFixMe)[key], nested, strictness)) {
       return false;
     }
   }
@@ -199,6 +216,9 @@ export function equals(
  * fine, missing or different ones are not.
  */
 export function matchesObject(received: mixed, expected: mixed, seen: Array<Pair> = []): boolean {
+  if (isAsymmetric(expected)) {
+    return matchesAsymmetric(expected, received);
+  }
   if (!isObject(expected) || !isObject(received)) {
     return equals(received, expected, seen);
   }
@@ -215,11 +235,11 @@ export function matchesObject(received: mixed, expected: mixed, seen: Array<Pair
     }
     return expected.every((item, index) => matchesObject(received[index], item, nested));
   }
-  for (const key of ownKeys((expected: $FlowFixMe), "loose")) {
+  for (const key of ownKeys(expected as $FlowFixMe, "loose")) {
     if (!Object.prototype.hasOwnProperty.call(received, key)) {
       return false;
     }
-    if (!matchesObject((received: $FlowFixMe)[key], (expected: $FlowFixMe)[key], nested)) {
+    if (!matchesObject((received as $FlowFixMe)[key], (expected as $FlowFixMe)[key], nested)) {
       return false;
     }
   }
@@ -238,6 +258,33 @@ function quoteString(value: string): string {
  * or refuses. Depth, breadth and total size are bounded, because a failure
  * message that scrolls the terminal is a failure message nobody reads.
  */
+/**
+ * An element's opening tag, or `null` if this is not an element.
+ *
+ * Duck-typed rather than `instanceof Element`, because this module must not
+ * depend on a DOM existing: a test process without a document simply never has
+ * a value that answers to this shape.
+ */
+function elementTag(value: mixed): string | null {
+  const node: $FlowFixMe = value;
+  if (
+    node == null ||
+    typeof node.tagName !== "string" ||
+    typeof node.getAttribute !== "function" ||
+    node.nodeType !== 1
+  ) {
+    return null;
+  }
+  const name = node.tagName.toLowerCase();
+  const attributes = Array.from(node.attributes ?? [])
+    .slice(0, MAX_RENDER_ENTRIES)
+    .map((attribute: $FlowFixMe) => ` ${attribute.name}="${attribute.value}"`)
+    .join("");
+  const text = (node.textContent ?? "").replace(/\s+/g, " ").trim();
+  const shown = text.length > 40 ? `${text.slice(0, 40)}…` : text;
+  return shown === "" ? `<${name}${attributes} />` : `<${name}${attributes}>${shown}</${name}>`;
+}
+
 export function render(value: mixed, depth: number = 0, seen: Array<mixed> = []): string {
   const text = renderInner(value, depth, seen);
   return text.length > MAX_RENDER_BYTES ? `${text.slice(0, MAX_RENDER_BYTES)}… (elided)` : text;
@@ -262,7 +309,7 @@ function renderInner(value: mixed, depth: number, seen: Array<mixed>): string {
     case "symbol":
       return String(value);
     case "function": {
-      const name = (value: $FlowFixMe).name;
+      const name = (value as $FlowFixMe).name;
       return name === "" ? "[Function (anonymous)]" : `[Function ${name}]`;
     }
     default:
@@ -278,6 +325,14 @@ function renderInner(value: mixed, depth: number, seen: Array<mixed>): string {
   const nested = [...seen, value];
   const inner = (item: mixed) => renderInner(item, depth + 1, nested);
 
+  // An element, before the object branch reaches it. A DOM node's own
+  // properties are event-listener maps and parent pointers, so rendering it as
+  // an object buries the failure under a page of internals — and the whole
+  // document, through the parent chain. Its opening tag is what a reader needs.
+  const tag = elementTag(value);
+  if (tag != null) {
+    return tag;
+  }
   if (value instanceof Date) {
     return `Date(${value.toISOString()})`;
   }
@@ -289,19 +344,22 @@ function renderInner(value: mixed, depth: number, seen: Array<mixed>): string {
   }
   if (value instanceof Set) {
     const items = [...value].slice(0, MAX_RENDER_ENTRIES).map(inner);
-    const more = value.size > MAX_RENDER_ENTRIES ? `, …${value.size - MAX_RENDER_ENTRIES} more` : "";
+    const more =
+      value.size > MAX_RENDER_ENTRIES ? `, …${value.size - MAX_RENDER_ENTRIES} more` : "";
     return `Set { ${items.join(", ")}${more} }`;
   }
   if (value instanceof Map) {
     const items = [...value]
       .slice(0, MAX_RENDER_ENTRIES)
       .map(([key, item]) => `${inner(key)} => ${inner(item)}`);
-    const more = value.size > MAX_RENDER_ENTRIES ? `, …${value.size - MAX_RENDER_ENTRIES} more` : "";
+    const more =
+      value.size > MAX_RENDER_ENTRIES ? `, …${value.size - MAX_RENDER_ENTRIES} more` : "";
     return `Map { ${items.join(", ")}${more} }`;
   }
   if (Array.isArray(value)) {
     const items = value.slice(0, MAX_RENDER_ENTRIES).map(inner);
-    const more = value.length > MAX_RENDER_ENTRIES ? `, …${value.length - MAX_RENDER_ENTRIES} more` : "";
+    const more =
+      value.length > MAX_RENDER_ENTRIES ? `, …${value.length - MAX_RENDER_ENTRIES} more` : "";
     return `[${items.join(", ")}${more}]`;
   }
 
@@ -318,5 +376,7 @@ function renderInner(value: mixed, depth: number, seen: Array<mixed>): string {
     prototype != null && prototype.constructor != null && prototype.constructor.name !== "Object"
       ? `${prototype.constructor.name} `
       : "";
-  return entries.length === 0 ? `${constructorName}{}` : `${constructorName}{ ${entries.join(", ")}${more} }`;
+  return entries.length === 0
+    ? `${constructorName}{}`
+    : `${constructorName}{ ${entries.join(", ")}${more} }`;
 }