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

package/internal/expect.js

@@ -12,6 +12,10 @@
 // matcher table to what came out, so `await expect(p).resolves.toBe(1)` reads
 // the way the synchronous form does.
 
+import type { SpyCall } from "./spy.js";
+import * as asymmetric from "./asymmetric.js";
+import * as snapshot from "./snapshot.js";
+import { isSpy } from "./spy.js";
 import { equals, matchesObject, render } from "./equality.js";
 
 /** Thrown when a matcher does not hold. */
@@ -34,78 +38,26 @@ export class AssertionError extends Error {
 
 /** What a matcher decided, and how to say it either way. */
 type Verdict = {|
-  +pass: boolean,
-  +failure: () => string,
-  +negatedFailure: () => string,
-  +expected?: string,
-  +received?: string,
+  readonly pass: boolean,
+  readonly failure: () => string,
+  readonly negatedFailure: () => string,
+  readonly expected?: string,
+  readonly received?: string,
 |};
 
-/** One recorded call to a spy. */
-export type SpyCall = {|
-  +args: $ReadOnlyArray<mixed>,
-  +returned?: mixed,
-  +threw?: mixed,
-|};
-
-/**
- * A spy that records its calls.
- *
- * `fn()` records and returns `undefined`; `fn(implementation)` records and
- * delegates. A throw is recorded and then re-thrown, so wrapping a function in
- * a spy never changes whether the code under test fails.
- */
-export function fn(implementation?: (...args: $ReadOnlyArray<mixed>) => mixed): $FlowFixMe {
-  const calls: Array<SpyCall> = [];
-  let current = implementation;
-
-  const spy: $FlowFixMe = (...args: $ReadOnlyArray<mixed>) => {
-    try {
-      const returned = current == null ? undefined : current(...args);
-      calls.push({ args, returned });
-      return returned;
-    } catch (thrown) {
-      calls.push({ args, threw: thrown });
-      throw thrown;
-    }
-  };
-  spy.mock = { calls };
-  spy.mockClear = () => {
-    calls.length = 0;
-  };
-  spy.mockReturnValue = (value: mixed) => {
-    current = () => value;
-    return spy;
-  };
-  spy.mockResolvedValue = (value: mixed) => {
-    current = () => Promise.resolve(value);
-    return spy;
-  };
-  spy.mockRejectedValue = (reason: mixed) => {
-    current = () => Promise.reject(reason);
-    return spy;
-  };
-  spy.mockImplementation = (next: (...args: $ReadOnlyArray<mixed>) => mixed) => {
-    current = next;
-    return spy;
-  };
-  return spy;
-}
-
-function isSpy(value: mixed): boolean {
-  return typeof value === "function" && (value: $FlowFixMe).mock != null;
-}
-
-function propertyAt(value: mixed, path: string): {| +found: boolean, +value: mixed |} {
+function propertyAt(
+  value: mixed,
+  path: string,
+): {| readonly found: boolean, readonly value: mixed |} {
   let current = value;
   for (const key of path.split(".")) {
     if (current == null) {
       return { found: false, value: undefined };
     }
-    if (!Object.prototype.hasOwnProperty.call((current: $FlowFixMe), key)) {
+    if (!Object.prototype.hasOwnProperty.call(current as $FlowFixMe, key)) {
       return { found: false, value: undefined };
     }
-    current = (current: $FlowFixMe)[key];
+    current = (current as $FlowFixMe)[key];
   }
   return { found: true, value: current };
 }
@@ -126,7 +78,7 @@ function matchesThrown(thrown: mixed, expected: mixed): boolean {
     return message === expected.message;
   }
   if (typeof expected === "function") {
-    return thrown instanceof (expected: $FlowFixMe);
+    return thrown instanceof (expected as $FlowFixMe);
   }
   return equals(thrown, expected);
 }
@@ -136,8 +88,30 @@ function matchesThrown(thrown: mixed, expected: mixed): boolean {
  *
  * Every entry returns a [`Verdict`] rather than throwing, which is what lets
  * `.not` reuse all of them.
+ *
+ * # The `any` in the indexer
+ *
+ * The entries do not agree about their arguments — `toBe` takes a `mixed`,
+ * `toHaveLength` takes a `number`, `toBeCloseTo` takes two — and [`bind`]
+ * applies whichever one it was asked for to a `$ReadOnlyArray<mixed>` it
+ * collected from a caller. Parameters are contravariant, so one indexer cannot
+ * describe both ends: `(...args: $ReadOnlyArray<mixed>)` rejects every entry
+ * that wants a `number`, and `(...args: $ReadOnlyArray<empty>)` accepts every
+ * entry and rejects the call.
+ *
+ * `mixed` with a cast at the call would move the same unsoundness one line
+ * without checking anything, because the caller is `bind`, whose result is
+ * `$FlowFixMe` and whose result's result is `expect`, also `$FlowFixMe`. The
+ * type that makes any of this checked is a written-out matcher interface —
+ * one signature per matcher, plus `.not`, `.resolves` and `.rejects` — which
+ * is what `expect`'s own annotation is waiting for, and is
+ * ubugeeei-prod/uf#402. Until that exists, a narrower type here would be
+ * precision nobody can reach.
  */
-function verdicts(received: mixed): { +[string]: (...args: $ReadOnlyArray<any>) => Verdict } {
+function verdicts(received: mixed): {
+  // uf-lint-disable-next-line flow/unclear-type
+  readonly [string]: (...args: $ReadOnlyArray<any>) => Verdict,
+} {
   const shown = () => render(received);
   const simple = (pass: boolean, what: string, expected?: mixed): Verdict => ({
     pass,
@@ -146,7 +120,8 @@ function verdicts(received: mixed): { +[string]: (...args: $ReadOnlyArray<any>)
     failure: () => `expected ${shown()} ${what}`,
     negatedFailure: () => `expected ${shown()} not ${what}`,
   });
-  const spyCalls = (): Array<SpyCall> => (isSpy(received) ? (received: $FlowFixMe).mock.calls : []);
+  const spyCalls = (): Array<SpyCall> =>
+    isSpy(received) ? (received as $FlowFixMe).mock.calls : [];
   const requireSpy = (matcher: string) => {
     if (!isSpy(received)) {
       throw new AssertionError(
@@ -187,17 +162,33 @@ function verdicts(received: mixed): { +[string]: (...args: $ReadOnlyArray<any>)
     toBeDefined: () => simple(received !== undefined, "to be defined"),
     toBeNaN: () => simple(typeof received === "number" && Number.isNaN(received), "to be NaN"),
     toBeGreaterThan: (expected: mixed) =>
-      simple((received: $FlowFixMe) > (expected: $FlowFixMe), `to be greater than ${render(expected)}`, expected),
+      simple(
+        (received as $FlowFixMe) > (expected as $FlowFixMe),
+        `to be greater than ${render(expected)}`,
+        expected,
+      ),
     toBeGreaterThanOrEqual: (expected: mixed) =>
-      simple((received: $FlowFixMe) >= (expected: $FlowFixMe), `to be at least ${render(expected)}`, expected),
+      simple(
+        (received as $FlowFixMe) >= (expected as $FlowFixMe),
+        `to be at least ${render(expected)}`,
+        expected,
+      ),
     toBeLessThan: (expected: mixed) =>
-      simple((received: $FlowFixMe) < (expected: $FlowFixMe), `to be less than ${render(expected)}`, expected),
+      simple(
+        (received as $FlowFixMe) < (expected as $FlowFixMe),
+        `to be less than ${render(expected)}`,
+        expected,
+      ),
     toBeLessThanOrEqual: (expected: mixed) =>
-      simple((received: $FlowFixMe) <= (expected: $FlowFixMe), `to be at most ${render(expected)}`, expected),
+      simple(
+        (received as $FlowFixMe) <= (expected as $FlowFixMe),
+        `to be at most ${render(expected)}`,
+        expected,
+      ),
     toBeCloseTo: (expected: number, digits?: number) => {
       const places = digits ?? 2;
       const tolerance = 10 ** -places / 2;
-      const difference = Math.abs((received: $FlowFixMe) - expected);
+      const difference = Math.abs((received as $FlowFixMe) - expected);
       return simple(
         difference < tolerance,
         `to be within ${tolerance} of ${expected}, but it is off by ${difference}`,
@@ -216,7 +207,11 @@ function verdicts(received: mixed): { +[string]: (...args: $ReadOnlyArray<any>)
       return simple(pass, `to contain ${render(expected)}`, expected);
     },
     toContainEqual: (expected: mixed) => {
-      const items = Array.isArray(received) ? received : received instanceof Set ? [...received] : [];
+      const items = Array.isArray(received)
+        ? received
+        : received instanceof Set
+          ? [...received]
+          : [];
       return simple(
         items.some((item) => equals(item, expected)),
         `to contain something equal to ${render(expected)}`,
@@ -224,8 +219,12 @@ function verdicts(received: mixed): { +[string]: (...args: $ReadOnlyArray<any>)
       );
     },
     toHaveLength: (expected: number) => {
-      const length = received == null ? undefined : (received: $FlowFixMe).length;
-      return simple(length === expected, `to have length ${expected}, not ${render(length)}`, expected);
+      const length = received == null ? undefined : (received as $FlowFixMe).length;
+      return simple(
+        length === expected,
+        `to have length ${expected}, not ${render(length)}`,
+        expected,
+      );
     },
     toHaveProperty: (path: string, ...rest: $ReadOnlyArray<mixed>) => {
       const found = propertyAt(received, path);
@@ -240,21 +239,60 @@ function verdicts(received: mixed): { +[string]: (...args: $ReadOnlyArray<any>)
     },
     toMatch: (expected: mixed) => {
       const text = typeof received === "string" ? received : String(received);
-      const pass = typeof expected === "string" ? text.includes(expected) : (expected: $FlowFixMe).test(text);
+      const pass =
+        typeof expected === "string"
+          ? text.includes(expected)
+          : (expected as $FlowFixMe).test(text);
       return simple(pass, `to match ${render(expected)}`, expected);
     },
     toMatchObject: (expected: mixed) =>
       simple(matchesObject(received, expected), `to match ${render(expected)}`, expected),
     toBeInstanceOf: (expected: mixed) =>
       simple(
-        typeof expected === "function" && received instanceof (expected: $FlowFixMe),
+        typeof expected === "function" && received instanceof (expected as $FlowFixMe),
         `to be an instance of ${render(expected)}`,
         expected,
       ),
     toBeTypeOf: (expected: string) =>
-      simple(typeof received === expected, `to be of type ${expected}, not ${typeof received}`, expected),
+      simple(
+        typeof received === expected,
+        `to be of type ${expected}, not ${typeof received}`,
+        expected,
+      ),
     toSatisfy: (predicate: (value: mixed) => boolean) =>
       simple(predicate(received) === true, "to satisfy the predicate"),
+    toMatchSnapshot: (hint?: string): Verdict => {
+      const verdict = snapshot.matchSnapshot(received, hint);
+      return {
+        pass: verdict.pass,
+        expected: verdict.expected ?? "(no snapshot yet)",
+        received: verdict.received,
+        // The whole of both sides, because a mismatch that says only "the
+        // snapshot did not match" makes a reader open two files.
+        failure: () =>
+          `snapshot did not match.\n\nstored:\n${verdict.expected ?? "(none)"}\n\n` +
+          `received:\n${verdict.received}\n\n` +
+          "Run `uf test -u` if the new value is the right one.",
+        negatedFailure: () => "expected the value not to match its snapshot",
+      };
+    },
+    toMatchInlineSnapshot: (expected?: string): Verdict => {
+      const verdict = snapshot.matchInlineSnapshot(received, expected);
+      return {
+        pass: verdict.pass,
+        expected: verdict.expected ?? "(no inline snapshot yet)",
+        received: verdict.received,
+        failure: () =>
+          verdict.expected == null
+            ? // uf does not rewrite a test file — a tool that edits the file you
+              // are editing is a tool that loses work — so it reports what to
+              // paste in and leaves the decision to a person.
+              `no inline snapshot yet. Paste this into the call:\n\n\`\`\`\n${verdict.received}\n\`\`\``
+            : `inline snapshot did not match.\n\nstored:\n${verdict.expected}\n\n` +
+              `received:\n${verdict.received}`,
+        negatedFailure: () => "expected the value not to match its inline snapshot",
+      };
+    },
     toThrow: (...rest: $ReadOnlyArray<mixed>) => {
       const expected = rest[0];
       if (typeof received !== "function") {
@@ -314,7 +352,157 @@ function verdicts(received: mixed): { +[string]: (...args: $ReadOnlyArray<any>)
         args,
       );
     },
+
+    // ---------------------------------------------------------------- //
+    // Elements
+    //
+    // These read properties of whatever they are given, so this module still
+    // needs no DOM and no dependency on one: an element is an object with a
+    // `tagName`, and a process without a document simply never has one to
+    // pass in. `element` says so when it does not.
+    // ---------------------------------------------------------------- //
+
+    toBeInTheDocument: () => {
+      const node = element("toBeInTheDocument");
+      const root = node.ownerDocument;
+      return simple(root != null && root.contains(node), "to be in the document");
+    },
+    toBeVisible: () => {
+      const node = element("toBeVisible");
+      return simple(isVisible(node), "to be visible");
+    },
+    toBeDisabled: () => {
+      const node = element("toBeDisabled");
+      return simple(isDisabled(node), "to be disabled");
+    },
+    toBeEnabled: () => {
+      const node = element("toBeEnabled");
+      return simple(!isDisabled(node), "to be enabled");
+    },
+    toBeChecked: () => {
+      const node = element("toBeChecked");
+      const aria = node.getAttribute("aria-checked");
+      const checked = aria != null ? aria === "true" : (node as $FlowFixMe).checked === true;
+      return simple(checked, "to be checked");
+    },
+    toBeRequired: () => {
+      const node = element("toBeRequired");
+      return simple(
+        (node as $FlowFixMe).required === true || node.getAttribute("aria-required") === "true",
+        "to be required",
+      );
+    },
+    toHaveFocus: () => {
+      const node = element("toHaveFocus");
+      return simple(node.ownerDocument?.activeElement === node, "to have focus");
+    },
+    toHaveAttribute: (name: mixed, value?: mixed) => {
+      const node = element("toHaveAttribute");
+      const actual = node.getAttribute(String(name));
+      if (value === undefined) {
+        return simple(actual != null, `to have the attribute ${render(name)}`, name);
+      }
+      return {
+        pass: actual === String(value),
+        expected: render(value),
+        received: render(actual),
+        failure: () => `expected ${render(name)} to be ${render(value)}, not ${render(actual)}`,
+      };
+    },
+    toHaveClass: (...names: $ReadOnlyArray<mixed>) => {
+      const node = element("toHaveClass");
+      const classes = (node.getAttribute("class") ?? "").split(/\s+/).filter(Boolean);
+      const wanted = names.map(String);
+      return {
+        pass: wanted.every((name) => classes.includes(name)),
+        expected: render(wanted),
+        received: render(classes),
+        failure: () => `expected the class list ${render(classes)} to include ${render(wanted)}`,
+      };
+    },
+    toHaveTextContent: (expected: mixed) => {
+      const node = element("toHaveTextContent");
+      const text = (node.textContent ?? "").replace(/\s+/g, " ").trim();
+      const pass =
+        expected instanceof RegExp ? expected.test(text) : text.includes(String(expected));
+      return {
+        pass,
+        expected: render(expected),
+        received: render(text),
+        failure: () => `expected the text ${render(text)} to contain ${render(expected)}`,
+      };
+    },
+    toHaveValue: (expected: mixed) => {
+      const node = element("toHaveValue");
+      const actual = (node as $FlowFixMe).value;
+      return {
+        pass: equals(actual, expected),
+        expected: render(expected),
+        received: render(actual),
+        failure: () => `expected the value ${render(actual)} to be ${render(expected)}`,
+      };
+    },
   };
+
+  /**
+   * The received value as an element, or a failure that says what it was.
+   *
+   * An element matcher applied to a string is almost always a query whose
+   * result was used without being awaited, and "received a Promise" is a much
+   * better message than a `TypeError` about `getAttribute`.
+   */
+  function element(matcher: string): Element {
+    const node: $FlowFixMe = received;
+    if (node == null || typeof node.getAttribute !== "function") {
+      throw new AssertionError(`${matcher} needs an element, and received ${render(received)}`);
+    }
+    return node;
+  }
+}
+
+/**
+ * Whether a reader would see this element.
+ *
+ * Walks the ancestors, because `display: none` on a parent hides a child whose
+ * own style says nothing. `hidden`, `aria-hidden` and a `details` that is not
+ * open each hide their subtree too.
+ */
+function isVisible(node: Element): boolean {
+  let current: $FlowFixMe = node;
+  while (current != null && current.nodeType === 1) {
+    if (current.hasAttribute("hidden") || current.getAttribute("aria-hidden") === "true") {
+      return false;
+    }
+    if (current.tagName === "DETAILS" && !current.hasAttribute("open") && current !== node) {
+      return false;
+    }
+    const style = current.ownerDocument?.defaultView?.getComputedStyle?.(current);
+    if (style != null) {
+      if (style.display === "none" || style.visibility === "hidden") {
+        return false;
+      }
+      if (style.opacity === "0") {
+        return false;
+      }
+    }
+    current = current.parentElement;
+  }
+  return true;
+}
+
+/** Whether the control is disabled, by its own attribute or a fieldset's. */
+function isDisabled(node: Element): boolean {
+  let current: $FlowFixMe = node;
+  while (current != null && current.nodeType === 1) {
+    if (current.hasAttribute("disabled")) {
+      return true;
+    }
+    if (current.getAttribute("aria-disabled") === "true") {
+      return true;
+    }
+    current = current.parentElement;
+  }
+  return false;
 }
 
 /**
@@ -333,7 +521,12 @@ function bind(received: mixed, negated: boolean): $FlowFixMe {
         return undefined;
       }
       const message = negated ? verdict.negatedFailure() : verdict.failure();
-      throw new AssertionError(message, name, verdict.expected ?? "", verdict.received ?? render(received));
+      throw new AssertionError(
+        message,
+        name,
+        verdict.expected ?? "",
+        verdict.received ?? render(received),
+      );
     };
   }
   Object.defineProperty(bound, "not", { get: () => bind(received, !negated) });
@@ -351,7 +544,7 @@ function settled(promise: mixed, wanted: "resolve" | "reject", negated: boolean)
       let value: mixed;
       let rejected = false;
       try {
-        value = await (promise: $FlowFixMe);
+        value = await (promise as $FlowFixMe);
       } catch (error) {
         rejected = true;
         value = error;
@@ -399,9 +592,58 @@ function settled(promise: mixed, wanted: "resolve" | "reject", negated: boolean)
  * await expect(load()).resolves.toHaveLength(3);
  * ```
  */
-export function expect(received: mixed): $FlowFixMe {
+function expectValue(received: mixed): $FlowFixMe {
   const expectation: $FlowFixMe = bind(received, false);
-  Object.defineProperty(expectation, "resolves", { get: () => settled(received, "resolve", false) });
+  Object.defineProperty(expectation, "resolves", {
+    get: () => settled(received, "resolve", false),
+  });
   Object.defineProperty(expectation, "rejects", { get: () => settled(received, "reject", false) });
   return expectation;
 }
+
+/**
+ * Assert about a value.
+ *
+ * Declared with its matchers attached rather than assigned afterwards: a
+ * shipped module may only declare, import and export at its top level, and
+ * `expect.any = …` is a statement that runs when the module is imported.
+ *
+ * The `expect.*` half are the matchers that stand in for a value instead of
+ * being one. `expect(user).toEqual({ id: expect.any(String), name: "uf" })`
+ * says what a test means; spelling out the id would either be a lie or a second
+ * source of truth. They work at any depth, because `equals` asks every value it
+ * meets whether it is one.
+ *
+ * `expect.not.*` is the negated form, spelled the way Jest and Vitest spell it
+ * — `expect.not.objectContaining({ error: expect.anything() })` reads better
+ * than a negated assertion around the whole object, and is the form a suite
+ * being ported will already have.
+ */
+// `flow/unsafe-object-assign` asks for an object spread, and a spread cannot
+// produce this value: `expect` is a *function* with matchers hanging off it,
+// and `{ ...expectValue, ...matchers }` is a plain object that a test cannot
+// call. `Object.assign` onto a callable is the only expression that makes one,
+// and the alternative the rule is really warning about — `expect.any = …`
+// afterwards — is the top-level statement the comment above rules out. What it
+// mutates is a function this module declared six lines up and exports here; no
+// object belonging to anybody else is touched.
+// uf-lint-disable-next-line flow/unsafe-object-assign
+export const expect: $FlowFixMe = Object.assign(expectValue, {
+  any: asymmetric.any,
+  anything: asymmetric.anything,
+  objectContaining: asymmetric.objectContaining,
+  arrayContaining: asymmetric.arrayContaining,
+  stringContaining: asymmetric.stringContaining,
+  stringMatching: asymmetric.stringMatching,
+  closeTo: asymmetric.closeTo,
+  not: {
+    objectContaining: (expected: interface {}) =>
+      asymmetric.not(asymmetric.objectContaining(expected)),
+    arrayContaining: (expected: $ReadOnlyArray<mixed>) =>
+      asymmetric.not(asymmetric.arrayContaining(expected)),
+    stringContaining: (substring: string) => asymmetric.not(asymmetric.stringContaining(substring)),
+    stringMatching: (pattern: string | RegExp) =>
+      asymmetric.not(asymmetric.stringMatching(pattern)),
+    closeTo: (value: number, digits?: number) => asymmetric.not(asymmetric.closeTo(value, digits)),
+  },
+});

package/internal/frames.js

@@ -14,13 +14,26 @@
 // regex-shaped.
 
 /** A position in a source file, one-based line and column. */
-export type Site = {| +line: number, +column: number |};
+export type Site = {| readonly line: number, readonly column: number |};
 
-/** Frames belonging to the runner itself, which no test author wrote. */
+/**
+ * Frames belonging to the testing libraries, which no test author wrote.
+ *
+ * `@uniflowed/react-testing` is here for exactly the reason `@uniflowed/test`
+ * is, and was missing because it is a different package. Every `getBy…`
+ * failure is *constructed* inside it, so the first surviving frame of the
+ * commonest failure a component test can produce was `internal/queries.js` —
+ * and since a site is reported as a line of the file being run, the reader was
+ * sent to a line their own file does not have. That is ubugeeei-prod/uf#319.
+ * A library that raises on the caller's behalf is the runner as far as the
+ * report is concerned.
+ */
 const INTERNAL_MARKERS = [
   "/packages/test/internal/",
   "/packages/test/worker.js",
+  "/packages/react-testing/",
   "/@uniflowed/test/",
+  "/@uniflowed/react-testing/",
   "node:internal/",
 ];
 
@@ -53,8 +66,54 @@ export function frameSite(frame: string): Site | null {
   return { line: line.value, column: column.value };
 }
 
+/**
+ * The file a stack frame names, or `null`.
+ *
+ * The same scan as [`frameSite`], stopping one step earlier: everything before
+ * the `:line:column` is where the code is, and what that is depends on how V8
+ * wrote the frame — `at name (/path:1:2)` when it has a function name, and
+ * `at /path:1:2` or `at async file:///path:1:2` when it does not.
+ *
+ * What comes back is whatever the frame said, a path or a URL, because those
+ * are the two things it can be and a caller resolving a module specifier
+ * against it has to tell them apart anyway.
+ */
+export function frameFile(frame: string): string | null {
+  let end = frame.length;
+  while (end > 0 && (frame[end - 1] === " " || frame[end - 1] === ")")) {
+    end -= 1;
+  }
+
+  const column = digitsBefore(frame, end);
+  if (column == null || column.start === 0 || frame[column.start - 1] !== ":") {
+    return null;
+  }
+  const line = digitsBefore(frame, column.start - 1);
+  if (line == null || line.start === 0 || frame[line.start - 1] !== ":") {
+    return null;
+  }
+
+  let text = frame.slice(0, line.start - 1);
+  const open = text.lastIndexOf("(");
+  if (open !== -1) {
+    text = text.slice(open + 1);
+  } else {
+    const at = text.lastIndexOf(" at ");
+    text = at === -1 ? text : text.slice(at + 4);
+  }
+  text = text.trim();
+  // `at async /path:1:2` — the marker belongs to the frame, not to the file.
+  if (text.startsWith("async ")) {
+    text = text.slice("async ".length).trim();
+  }
+  return text === "" ? null : text;
+}
+
 /** The run of digits ending at `end`, with where it starts. */
-function digitsBefore(text: string, end: number): {| +value: number, +start: number |} | null {
+function digitsBefore(
+  text: string,
+  end: number,
+): {| readonly value: number, readonly start: number |} | null {
   let start = end;
   while (start > 0 && text[start - 1] >= "0" && text[start - 1] <= "9") {
     start -= 1;
@@ -71,7 +130,10 @@ function digitsBefore(text: string, end: number): {| +value: number, +start: num
  * `skipInternal` is false when the caller has already trimmed the runner's own
  * frames and wants the first frame whatever it is.
  */
-export function firstUserSite(stack: string | null | void, skipInternal: boolean = true): Site | null {
+export function firstUserSite(
+  stack: string | null | void,
+  skipInternal: boolean = true,
+): Site | null {
   if (stack == null) {
     return null;
   }
@@ -87,6 +149,36 @@ export function firstUserSite(stack: string | null | void, skipInternal: boolean
   return null;
 }
 
+/**
+ * The first position in `stack` that is in `file`, or `null`.
+ *
+ * The reporter draws a failure's position as `path:line:column`, and it takes
+ * the path from the file it asked the worker to run rather than from the
+ * frame. So a number lifted from any other file is not a vaguer answer than
+ * none — it is a wrong one, naming a line the reader can open and that has
+ * nothing to do with what failed. Restricting the search to the file that will
+ * be named makes the two halves of that position come from the same place.
+ *
+ * `null` when the file is on no frame, which is a failure raised from work the
+ * case left behind: no line of it is the one that failed, and printing none is
+ * the honest answer.
+ */
+export function siteInFile(stack: string | null | void, file: string): Site | null {
+  if (stack == null) {
+    return null;
+  }
+  for (const frame of stack.split("\n").slice(1)) {
+    if (!frame.includes(file)) {
+      continue;
+    }
+    const site = frameSite(frame);
+    if (site != null) {
+      return site;
+    }
+  }
+  return null;
+}
+
 /**
  * `stack` with the runner's own frames removed.
  *