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

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

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,25 +193,41 @@ async function runCase(
   const timeoutMs = test.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   let outcome: Outcome = { status: "passed" };
-  try {
-    for (const hook of context.beforeEach) {
-      await withTimeout(hook, timeoutMs);
-    }
-    await withTimeout(test.body, timeoutMs);
-  } catch (thrown) {
-    outcome = failure(thrown);
-  }
-  // Teardown runs whatever happened above, and only reports its own failure
-  // when the body had not already failed.
-  for (const hook of context.afterEach) {
+  // Setup, body and teardown run *inside* the case's output context, and that
+  // nesting is the whole of the fix for #207. What names a printed line is no
+  // longer where the runner had got to when the line arrived — which named the
+  // next case for anything a `setTimeout` left behind — but which case's work
+  // the write descends from. A callback scheduled here keeps this name however
+  // late it fires.
+  //
+  // The cases above never reach this: nothing runs for a `todo`, a `skip` or a
+  // filtered-out case, so nothing of theirs can print.
+  await output.runInTest(name, async () => {
     try {
-      await withTimeout(hook, timeoutMs);
+      for (const hook of context.beforeEach) {
+        await withTimeout(hook, timeoutMs);
+      }
+      await withTimeout(test.body, timeoutMs);
     } catch (thrown) {
-      if (outcome.status === "passed") {
-        outcome = failure(thrown);
+      outcome = failure(thrown);
+    }
+    // Teardown runs whatever happened above, and only reports its own failure
+    // when the body had not already failed.
+    for (const hook of context.afterEach) {
+      try {
+        await withTimeout(hook, timeoutMs);
+      } catch (thrown) {
+        if (outcome.status === "passed") {
+          outcome = failure(thrown);
+        }
       }
     }
-  }
+  });
+  // The `await` above resumes outside the context it entered, so this line and
+  // everything after it belong to no case again — a line printed between cases
+  // is the file's, and a snapshot taken outside one fails with something better
+  // than a key belonging to whichever test happened to run last.
+  snapshot.exitTest();
   report(outcome);
   return outcome.status !== "failed";
 }
@@ -215,6 +244,7 @@ async function runSuite(
   onlyMode: boolean,
   emit: (result: Result) => void,
   state: {| bail: boolean |},
+  setUpAncestors: () => Promise<void>,
 ): Promise<boolean> {
   const skipped = context.skipped || node.modifier === "skip" || node.modifier === "todo";
   const onlyPath = !onlyMode || context.onlyPath || node.modifier === "only";
@@ -229,11 +259,18 @@ async function runSuite(
   // `beforeAll` is deferred until a case in this suite actually runs, so a
   // fully skipped suite never sets anything up. `afterAll` mirrors it.
+  //
+  // "In this suite" means anywhere under it. A suite whose children are all
+  // suites has no case of its own, and setting up only for a direct child left
+  // every `beforeAll` in an ordinary file — one where the tests live inside a
+  // `describe` — never running at all, silently. The chain is walked outermost
+  // first, so an inner suite's setup sees what the outer one did.
   let setUp = false;
   const setUpOnce = async () => {
     if (setUp) {
       return;
     }
+    await setUpAncestors();
     setUp = true;
     for (const hook of node.beforeAll) {
       await withTimeout(hook, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
@@ -276,7 +313,7 @@ async function runSuite(
       const ok = await runCase(child, childContext, options, emit);
       passed = passed && ok;
     } else {
-      const ok = await runSuite(child, inner, options, onlyMode, emit, state);
+      const ok = await runSuite(child, inner, options, onlyMode, emit, state, setUpOnce);
       passed = passed && ok;
     }
   }
@@ -310,5 +347,5 @@ export async function run(options: RunOptions, emit: (result: Result) => void):
     skipped: false,
     onlyPath: !onlyMode,
   };
-  await runSuite(root, context, options, onlyMode, emit, { bail: false });
+  await runSuite(root, context, options, onlyMode, emit, { bail: false }, async () => {});
 }

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");
+}