npm - @uniflowed/test - Versions diffs - 0.0.0-alpha.1 → 0.0.0-alpha.4 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/internal/run.js CHANGED Viewed

@@ -9,40 +9,49 @@
 // driven by the worker, by a unit test, or by a future host that is not
 // Node.js, without any of them re-deciding what `.only` means.
+import * as output from "./output.js";
+import * as snapshot from "./snapshot.js";
 import { AssertionError } from "./expect.js";
 import { firstUserSite, userFrames } from "./frames.js";
 import { type Body, type Case, type Suite, collected } from "./registry.js";
 /** How one case ended. */
 export type Outcome =
-  | {| +status: "passed" |}
+  | {| readonly status: "passed" |}
   | {|
-      +status: "failed",
-      +message: string,
-      +stack: string | null,
-      +expected: string | null,
-      +received: string | null,
+      readonly status: "failed",
+      readonly message: string,
+      readonly stack: string | null,
+      readonly expected: string | null,
+      readonly received: string | null,
       /** Where the failing assertion was written, when the stack says. */
-      +site: {| +line: number, +column: number |} | null,
+      readonly site: {| readonly line: number, readonly column: number |} | null,
     |}
-  | {| +status: "skipped", +reason: "explicit" | "not-only" | "filtered" |}
-  | {| +status: "todo" |};
+  | {| readonly status: "skipped", readonly reason: "explicit" | "not-only" | "filtered" |}
+  | {| readonly status: "todo" |};
 /** One finished case, as the runner reports it. */
 export type Result = {|
-  +name: string,
-  +line: number,
-  +column: number,
-  +durationMicros: number,
-  +outcome: Outcome,
+  readonly name: string,
+  readonly line: number,
+  readonly column: number,
+  readonly durationMicros: number,
+  readonly outcome: Outcome,
 |};
 /** How a run is configured. */
 export type RunOptions = {|
   /** Keep only cases whose full name contains this, reporting the rest skipped. */
-  +filter?: string | null,
+  readonly filter?: string | null,
   /** Wall-clock budget for one case, in milliseconds. */
-  +timeoutMs?: number,
+  readonly timeoutMs?: number,
+  /**
+   * Absolute path of the file being run.
+   *
+   * Snapshots live beside the file that took them, so the runner has to say
+   * which file that is — a test's name alone does not locate it.
+   */
+  readonly file?: string,
 |};
 /** Default budget for one case, matching what most runners use. */
@@ -128,11 +137,11 @@ function failure(thrown: mixed): Outcome {
 /** Everything one case needs from the suites above it. */
 type Context = {|
-  +path: $ReadOnlyArray<string>,
-  +beforeEach: $ReadOnlyArray<Body>,
-  +afterEach: $ReadOnlyArray<Body>,
-  +skipped: boolean,
-  +onlyPath: boolean,
+  readonly path: $ReadOnlyArray<string>,
+  readonly beforeEach: $ReadOnlyArray<Body>,
+  readonly afterEach: $ReadOnlyArray<Body>,
+  readonly skipped: boolean,
+  readonly onlyPath: boolean,
 |};
 /**
@@ -149,6 +158,10 @@ async function runCase(
   emit: (result: Result) => void,
 ): Promise<boolean> {
   const name = fullName([...context.path, test.name]);
+  // Snapshots are keyed by the running test, so the module has to be told which
+  // one it is — and told again that none is, so one taken outside a test fails
+  // with something better than a wrong key.
+  snapshot.enterTest(options.file ?? "", name);
   const started = performance.now();
   const report = (outcome: Outcome) => {
     emit({
@@ -180,6 +193,11 @@ async function runCase(
   const timeoutMs = test.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   let outcome: Outcome = { status: "passed" };
+  // From here to the end of teardown is exactly the window in which this
+  // case's own code runs, so it is exactly the window whose printing is this
+  // case's. The cases above never reach it: nothing runs for a `todo`, a
+  // `skip` or a filtered-out case, so nothing of theirs can print.
+  output.enterTest(name);
   try {
     for (const hook of context.beforeEach) {
       await withTimeout(hook, timeoutMs);
@@ -199,6 +217,11 @@ async function runCase(
       }
     }
   }
+  // No test is running once this one is reported, so a snapshot taken outside
+  // one fails with something better than a key belonging to whichever test
+  // happened to run last, and a line printed outside one is the file's.
+  output.exitTest();
+  snapshot.exitTest();
   report(outcome);
   return outcome.status !== "failed";
 }

package/internal/snapshot.js ADDED Viewed

@@ -0,0 +1,306 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: `toMatchSnapshot` and its inline sibling.
+//
+// A snapshot is an assertion whose expected value was written by the last run
+// rather than by a person. That is the whole idea and also the whole danger:
+// a snapshot nobody reads is a test that asserts whatever the code did, which
+// is not a test. Two things here take that seriously.
+//
+// **A missing snapshot is written; a different one is a failure.** Never
+// "updated because it changed" — that is how a snapshot suite becomes a diff
+// nobody looks at. Rewriting on mismatch happens only when a run was explicitly
+// asked to, through `UF_UPDATE_SNAPSHOTS`, which `uf test -u` sets.
+//
+// **The diff is in the failure.** A snapshot mismatch that says only "snapshot
+// did not match" makes a reader open two files; the whole expected and received
+// text is in the message, because that is what they were going to look at.
+//
+// # Where they live
+//
+// `__snapshots__/<file>.snap` beside the test file, one file per test file, in
+// the format Jest and Vitest both write: a module of `exports[key] = ...`. Not
+// because uf runs either, but because the format is diffable, the tooling that
+// reads it already exists, and inventing a different one would buy nothing.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { render } from "./equality.js";
+/**
+ * A backtick, by code point.
+ *
+ * Written this way rather than as a literal because this module is scanned by
+ * `uf_lib`'s surface tests, whose tokenizer does not model regex literals and
+ * reads a stray backtick as the start of a template. One constant is cheaper
+ * than teaching that scanner about regular expressions, and it is used often
+ * enough here to earn a name.
+ */
+const BACKTICK = String.fromCharCode(96);
+/** Which test is running, so a snapshot can be keyed by it. */
+type Current = {
+  /** Absolute path of the test file. */
+  readonly file: string,
+  /** The test's full name, suites included. */
+  readonly name: string,
+  /** How many snapshots this test has taken, so a second one gets `2`. */
+  taken: number,
+};
+let current: Current | null = null;
+/** Snapshots read from disk, by snapshot file, and whether they changed. */
+const loaded: Map<string, { entries: { [string]: string }, dirty: boolean }> = new Map();
+/** Whether this run may rewrite a snapshot that did not match. */
+function updating(): boolean {
+  const value = (globalThis: $FlowFixMe).process?.env?.UF_UPDATE_SNAPSHOTS;
+  return value != null && value !== "" && value !== "0";
+}
+/**
+ * Say which test is running.
+ *
+ * Called by the runner around each case. `null` between them, so a snapshot
+ * taken outside a test fails with something better than a wrong key.
+ */
+export function enterTest(file: string, name: string): void {
+  current = { file, name, taken: 0 };
+}
+/** Say that no test is running. */
+export function exitTest(): void {
+  current = null;
+}
+/** Raised when a snapshot is taken where it cannot be keyed or stored. */
+export class SnapshotError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SnapshotError";
+  }
+}
+/** The snapshot file for a test file. */
+function snapshotPath(file: string): string {
+  return path.join(path.dirname(file), "__snapshots__", `${path.basename(file)}.snap`);
+}
+/**
+ * Read a snapshot file, or start an empty one.
+ *
+ * Parsed rather than imported: the file is data, and importing it would run it
+ * — which is a fine way to execute whatever a snapshot happens to contain.
+ */
+function entriesFor(file: string): { entries: { [string]: string }, dirty: boolean } {
+  const target = snapshotPath(file);
+  const already = loaded.get(target);
+  if (already != null) {
+    return already;
+  }
+  const state = { entries: (Object.create(null): $FlowFixMe), dirty: false };
+  if (existsSync(target)) {
+    parseInto(readFileSync(target, "utf8"), state.entries);
+  }
+  loaded.set(target, state);
+  return state;
+}
+/** The literal text an entry opens with, before its key. */
+const ENTRY_OPEN = "exports[" + BACKTICK;
+/** The literal text between an entry's key and its value. */
+const ENTRY_MIDDLE = BACKTICK + "] = " + BACKTICK;
+/**
+ * Read `exports[<key>] = <value>;` entries out of a snapshot file.
+ *
+ * A scanner rather than a regular expression, for two reasons. A snapshot's
+ * value holds newlines and backticks of its own, so the terminator has to be
+ * found by walking the escapes rather than by matching a pattern. And a regular
+ * expression for this would have to contain a backtick, which is the one
+ * character `code_only` in `uf_lib`'s surface tests cannot see past — the
+ * scanner there does not model regex literals, and a backtick inside one reads
+ * as the start of a template.
+ */
+function parseInto(source: string, into: { [string]: string }): void {
+  let at = 0;
+  for (;;) {
+    const open = source.indexOf(ENTRY_OPEN, at);
+    if (open < 0) {
+      break;
+    }
+    const keyFrom = open + ENTRY_OPEN.length;
+    const keyEnd = findClose(source, keyFrom);
+    if (keyEnd < 0) {
+      break;
+    }
+    if (!source.startsWith(ENTRY_MIDDLE, keyEnd)) {
+      at = keyFrom;
+      continue;
+    }
+    const valueFrom = keyEnd + ENTRY_MIDDLE.length;
+    const valueEnd = findClose(source, valueFrom);
+    if (valueEnd < 0) {
+      break;
+    }
+    into[unescape(source.slice(keyFrom, keyEnd))] = unescape(source.slice(valueFrom, valueEnd));
+    at = valueEnd + 1;
+  }
+}
+/** The index of the unescaped backtick closing a value that starts at `from`. */
+function findClose(source: string, from: number): number {
+  for (let at = from; at < source.length; at += 1) {
+    if (source[at] === "\\") {
+      at += 1;
+      continue;
+    }
+    if (source[at] === "`") {
+      return at;
+    }
+  }
+  return -1;
+}
+/** Undo what `escapeValue` did. */
+function unescape(value: string): string {
+  let out = "";
+  for (let at = 0; at < value.length; at += 1) {
+    if (value[at] === "\\" && at + 1 < value.length) {
+      at += 1;
+    }
+    out += value[at];
+  }
+  return out;
+}
+/**
+ * Make a value safe inside a template literal.
+ *
+ * A backtick would end it, a backslash would eat the next character, and `${`
+ * would start a substitution that runs code — which matters because a snapshot
+ * file is written by a test and read by whatever opens it next.
+ */
+function escapeValue(value: string): string {
+  let out = "";
+  for (let at = 0; at < value.length; at += 1) {
+    const char = value[at];
+    if (char === "\\" || char === BACKTICK) {
+      out += "\\";
+    } else if (char === "$" && value[at + 1] === "{") {
+      out += "\\";
+    }
+    out += char;
+  }
+  return out;
+}
+/** Write a snapshot file back, in key order so a diff is readable. */
+function flush(target: string, entries: { [string]: string }): void {
+  const keys = Object.keys(entries).sort();
+  const body = keys
+    .map((key) => `exports[\`${escapeValue(key)}\`] = \`${escapeValue(entries[key])}\`;\n`)
+    .join("\n");
+  mkdirSync(path.dirname(target), { recursive: true });
+  writeFileSync(
+    target,
+    `// uf snapshot file. Read the diff — a snapshot nobody reads is not a test.\n\n${body}`,
+    "utf8",
+  );
+}
+/** Write every snapshot file this run changed. */
+export function writeChangedSnapshots(): void {
+  for (const [target, state] of loaded) {
+    if (state.dirty) {
+      flush(target, state.entries);
+      state.dirty = false;
+    }
+  }
+}
+/** What a snapshot comparison decided. */
+export type SnapshotVerdict = {
+  readonly pass: boolean,
+  /** The stored snapshot, or `null` when there was none. */
+  readonly expected: string | null,
+  /** What this run produced. */
+  readonly received: string,
+  /** Whether the file was written, and why. */
+  readonly wrote: "created" | "updated" | null,
+};
+/**
+ * Compare `value` against the stored snapshot for the running test.
+ *
+ * A missing snapshot is written and passes — the first run of a new assertion
+ * has nothing to compare against, and failing it would mean every new snapshot
+ * test fails once by design. A *different* one fails unless the run was asked
+ * to update.
+ */
+export function matchSnapshot(value: mixed, hint?: string): SnapshotVerdict {
+  if (current == null) {
+    throw new SnapshotError(
+      "toMatchSnapshot was called outside a test, so there is nothing to key it by",
+    );
+  }
+  current.taken += 1;
+  const suffix = hint != null && hint !== "" ? `: ${hint}` : "";
+  const key = `${current.name}${suffix} ${current.taken}`;
+  const state = entriesFor(current.file);
+  const received = render(value);
+  if (!Object.hasOwn(state.entries, key)) {
+    state.entries[key] = received;
+    state.dirty = true;
+    return { pass: true, expected: null, received, wrote: "created" };
+  }
+  const expected = state.entries[key];
+  if (expected === received) {
+    return { pass: true, expected, received, wrote: null };
+  }
+  if (updating()) {
+    state.entries[key] = received;
+    state.dirty = true;
+    return { pass: true, expected, received, wrote: "updated" };
+  }
+  return { pass: false, expected, received, wrote: null };
+}
+/**
+ * Compare `value` against a snapshot written in the test file itself.
+ *
+ * Nothing is written back: uf does not rewrite a test file, because a tool that
+ * edits the file you are editing is a tool that loses work. A missing inline
+ * snapshot reports what to paste in, which is the same information with the
+ * decision left to a person.
+ */
+export function matchInlineSnapshot(value: mixed, expected?: string): SnapshotVerdict {
+  const received = render(value);
+  if (expected == null) {
+    return { pass: false, expected: null, received, wrote: null };
+  }
+  // The stored form is indented to sit inside the call, so both sides are
+  // compared with that indentation removed.
+  return {
+    pass: dedent(expected) === dedent(received),
+    expected,
+    received,
+    wrote: null,
+  };
+}
+/** Strip the common leading whitespace, so indentation is not the assertion. */
+export function dedent(value: string): string {
+  const lines = value.replace(/^\n/, "").replace(/\s+$/, "").split("\n");
+  const indents = lines
+    .filter((line) => line.trim() !== "")
+    .map((line) => line.length - line.trimStart().length);
+  const common = indents.length === 0 ? 0 : Math.min(...indents);
+  return lines.map((line) => line.slice(common)).join("\n");
+}

package/internal/spy.js ADDED Viewed

@@ -0,0 +1,236 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: the spy behind `fn` and `uft.spyOn`.
+//
+// Shaped after Vitest's, because a project moving to uf should not have to
+// rewrite its assertions. That means `mock.calls`, `mock.results`,
+// `mock.lastCall`, the `Once` variants, and `mockReset` and `mockRestore`
+// meaning the two different things they mean there.
+//
+// The three reset verbs are easy to conflate and are genuinely different:
+//
+// * `mockClear` forgets the calls, and keeps the implementation.
+// * `mockReset` forgets the calls *and* the implementation, leaving the
+//   original one a `spyOn` captured — or nothing, for a bare `fn`.
+// * `mockRestore` does what `mockReset` does and then puts the real method
+//   back on the object, which only a `spyOn` has to put back.
+//
+// Every spy is registered, so `uft.clearAllMocks` and its siblings can reach the
+// ones a test never held a reference to.
+/** One call: what went in, and what came out. */
+export type SpyCall = {
+  readonly args: $ReadOnlyArray<mixed>,
+  readonly returned?: mixed,
+  readonly threw?: mixed,
+};
+/** One call's outcome, in the shape Vitest reports it. */
+export type SpyResult =
+  | { readonly type: "return", readonly value: mixed }
+  | { readonly type: "throw", readonly value: mixed };
+/** Every spy made in this process, so the `All` verbs can reach them. */
+const registry: Array<$FlowFixMe> = [];
+/** How a spy puts back what it replaced, when it replaced something. */
+type Restore = null | (() => void);
+/**
+ * A spy, optionally standing in for something it can put back.
+ *
+ * `restore` is what separates `fn()` from `spyOn(object, "method")`: the second
+ * took something off an object and owes it back.
+ */
+function makeSpy(implementation: mixed, restore: Restore, name: string): $FlowFixMe {
+  const calls: Array<SpyCall> = [];
+  const results: Array<SpyResult> = [];
+  const instances: Array<mixed> = [];
+  // Implementations queued by the `Once` variants, taken from the front.
+  const queued: Array<mixed> = [];
+  const original = implementation;
+  let current = implementation;
+  let mockName = name;
+  const spy: $FlowFixMe = function (...args: $ReadOnlyArray<mixed>) {
+    // `this` is recorded because a spy on a method is often called as one, and
+    // `mock.instances` is how a test asserts on the receiver.
+    instances.push(this);
+    const body = queued.length > 0 ? queued.shift() : current;
+    try {
+      const returned = typeof body === "function" ? body.apply(this, args) : undefined;
+      calls.push({ args, returned });
+      results.push({ type: "return", value: returned });
+      return returned;
+    } catch (thrown) {
+      calls.push({ args, threw: thrown });
+      results.push({ type: "throw", value: thrown });
+      throw thrown;
+    }
+  };
+  spy.mock = {
+    calls,
+    results,
+    instances,
+    get lastCall(): $ReadOnlyArray<mixed> | void {
+      return calls.length === 0 ? undefined : calls[calls.length - 1].args;
+    },
+  };
+  spy.mockClear = () => {
+    calls.length = 0;
+    results.length = 0;
+    instances.length = 0;
+    return spy;
+  };
+  spy.mockReset = () => {
+    spy.mockClear();
+    queued.length = 0;
+    current = original;
+    return spy;
+  };
+  spy.mockRestore = () => {
+    spy.mockReset();
+    if (restore != null) {
+      restore();
+    }
+    return spy;
+  };
+  spy.mockImplementation = (next: mixed) => {
+    current = next;
+    return spy;
+  };
+  spy.mockImplementationOnce = (next: mixed) => {
+    queued.push(next);
+    return spy;
+  };
+  spy.withImplementation = (next: mixed, body: () => mixed) => {
+    const previous = current;
+    current = next;
+    try {
+      const out = body();
+      // An async body has to put the implementation back when it settles, not
+      // when it starts, or the next test runs against this one's stand-in.
+      if (out != null && typeof (out: $FlowFixMe).then === "function") {
+        return (out: $FlowFixMe).finally(() => {
+          current = previous;
+        });
+      }
+      current = previous;
+      return out;
+    } catch (thrown) {
+      current = previous;
+      throw thrown;
+    }
+  };
+  spy.mockReturnValue = (value: mixed) => spy.mockImplementation(() => value);
+  spy.mockReturnValueOnce = (value: mixed) => spy.mockImplementationOnce(() => value);
+  spy.mockResolvedValue = (value: mixed) => spy.mockImplementation(() => Promise.resolve(value));
+  spy.mockResolvedValueOnce = (value: mixed) =>
+    spy.mockImplementationOnce(() => Promise.resolve(value));
+  spy.mockRejectedValue = (reason: mixed) => spy.mockImplementation(() => Promise.reject(reason));
+  spy.mockRejectedValueOnce = (reason: mixed) =>
+    spy.mockImplementationOnce(() => Promise.reject(reason));
+  spy.mockReturnThis = () =>
+    spy.mockImplementation(function () {
+      return this;
+    });
+  spy.mockName = (next: string) => {
+    mockName = next;
+    return spy;
+  };
+  spy.getMockName = () => mockName;
+  registry.push(spy);
+  return spy;
+}
+/**
+ * A spy with no original behind it.
+ *
+ * `fn()` records and returns `undefined`; `fn(body)` records and runs `body`.
+ */
+export function fn(implementation?: mixed): $FlowFixMe {
+  return makeSpy(implementation, null, "spy");
+}
+/**
+ * Replace `object[method]` with a spy that calls through to it.
+ *
+ * Calls through by default, which is what makes `spyOn` an observation rather
+ * than a replacement — a test that only wants to know a method was called does
+ * not have to reimplement it. `mockImplementation` is how a test says it wants
+ * the other thing.
+ *
+ * The original is put back by `mockRestore`, and by `uft.restoreAllMocks`.
+ */
+export function spyOn(object: mixed, method: string): $FlowFixMe {
+  if (object == null || (typeof object !== "object" && typeof object !== "function")) {
+    throw new TypeError(`uft.spyOn: cannot spy on ${describe(object)}`);
+  }
+  const target = object as $FlowFixMe;
+  const original = target[method];
+  if (typeof original !== "function") {
+    throw new TypeError(
+      `uft.spyOn: ${method} is ${describe(original)}, and only a method can be spied on`,
+    );
+  }
+  const owned = Object.hasOwn(target, method);
+  const spy = makeSpy(
+    original,
+    () => {
+      // Deleting rather than reassigning when the method was inherited: writing
+      // the original onto the instance would leave a copy the prototype no longer
+      // controls, and the next change to the prototype would not be seen.
+      if (owned) {
+        target[method] = original;
+      } else {
+        delete target[method];
+      }
+    },
+    method,
+  );
+  target[method] = spy;
+  return spy;
+}
+/** Whether `value` is one of these spies. */
+export function isSpy(value: mixed): boolean {
+  return typeof value === "function" && (value: $FlowFixMe).mock != null;
+}
+/** Forget every spy's calls, keeping their implementations. */
+export function clearAllMocks(): void {
+  for (const spy of registry) {
+    spy.mockClear();
+  }
+}
+/** Forget every spy's calls and implementations. */
+export function resetAllMocks(): void {
+  for (const spy of registry) {
+    spy.mockReset();
+  }
+}
+/** Put back everything `spyOn` replaced. */
+export function restoreAllMocks(): void {
+  for (const spy of registry) {
+    spy.mockRestore();
+  }
+}
+/** A readable name for a value, for an error message. */
+function describe(value: mixed): string {
+  if (value === null) {
+    return "null";
+  }
+  return typeof value;
+}