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

package/internal/expect.js

@@ -11,10 +11,66 @@
 // `.resolves` and `.rejects` settle the promise first and then apply the same
 // matcher table to what came out, so `await expect(p).resolves.toBe(1)` reads
 // the way the synchronous form does.
+//
+// # The names are written down, and the behaviour is not
+//
+// `expect` used to be `$FlowFixMe`, and so was everything it handed back. That
+// is a hole in the published type of the package a project writes every one of
+// its assertions against: `expect(user).toBaa(1)` was not a misspelling
+// anybody's checker would find, `expect(list).toHaveLength("3")` was not a type
+// error, and `expect(p).resolves` on a value that is not a promise was fine
+// until it ran. Every test in this repository is written against `expect`,
+// which is the largest surface in the packages and was the least checked.
+//
+// So [`Matchers`] below writes the names out, one signature per matcher, the
+// way `@uniflowed/react-testing`'s `Queries` writes out its thirty-six. Flow
+// has no template literal types and no way to read a name out of a value, so
+// the listing has to exist for the type to exist at all. What is *not*
+// repeated is any behaviour: [`verdicts`] is still the one place a matcher is
+// decided, and the listing is a naming that a reader can check against it by
+// eye.
+//
+// [`Matchers`] is generic in what a matcher *returns*, which is what lets
+// `.resolves` reuse the one listing: the same forty-one names, each handing
+// back a promise.
+//
+// # The received value's type is not carried, and that was tried
+//
+// ubugeeei-prod/uf#402 asked for a second parameter as well — the type handed
+// to `expect`, carried through the matchers so that `expect(count).toBe("two")`
+// is an error at the call. It is written here rather than left for somebody to
+// discover, because it looks obviously right and is not.
+//
+// `toBe` is `Object.is`, and identity is not assignability. Typing it
+// `(expected: T)` demands that the expected value be a subtype of the received
+// one, which is a direction the runtime has no opinion about and which ordinary
+// assertions fail in both:
+// `expect(document.activeElement).toBe(screen.getByRole("button"))` compares an
+// `HTMLElement | null` with an `Element`, neither is the other's subtype, and
+// that is the most common assertion in a DOM test. Jest and Vitest both type
+// this argument as `unknown` for the same reason.
+//
+// Worse, the parameter has to be *inferred*, and `expect(x)` is where a lot of
+// otherwise unconstrained expressions sit. `await
+// expect(client.request("/users/1")).resolves.toEqual({ id: 1 })` stops
+// checking and starts reporting that `request`'s own type parameter is
+// underconstrained, because a `mixed` parameter asked nothing of the argument
+// and a generic one asks it to be solved. `expect([])` becomes "cannot
+// determine type of empty array literal". Both are correct tests, and the type
+// that rejects them is worse than the type that missed a mistyped comparison.
+//
+// So the received value arrives as `mixed`, and what makes a matcher checked is
+// its own signature: `toHaveLength` wants a number, `toMatch` a pattern,
+// `toBeTypeOf` one of the eight words `typeof` answers with, and every name is
+// a name. The comparison between two unrelated types stays unchecked, and it is
+// the only part of the issue that does.
 
+import type { AsymmetricMatcher } from "./asymmetric.js";
+import type { AxeOptions } from "./axe.js";
 import type { SpyCall } from "./spy.js";
 import * as asymmetric from "./asymmetric.js";
 import * as snapshot from "./snapshot.js";
+import { auditElement, describeViolations, violationIds } from "./axe.js";
 import { isSpy } from "./spy.js";
 import { equals, matchesObject, render } from "./equality.js";
 
@@ -36,7 +92,14 @@ export class AssertionError extends Error {
   }
 }
 
-/** What a matcher decided, and how to say it either way. */
+/**
+ * What a matcher decided, and how to say it either way.
+ *
+ * A matcher may answer with a promise of one. Only one does — the accessibility
+ * audit, whose engine has no synchronous entry point — and [`bind`] is where
+ * the two cases are told apart; see the note there for why the promise is not
+ * hidden from the caller.
+ */
 type Verdict = {|
   readonly pass: boolean,
   readonly failure: () => string,
@@ -45,6 +108,166 @@ type Verdict = {|
   readonly received?: string,
 |};
 
+/** What `typeof` can answer, for the matcher that compares against it. */
+type TypeName =
+  | "bigint"
+  | "boolean"
+  | "function"
+  | "number"
+  | "object"
+  | "string"
+  | "symbol"
+  | "undefined";
+
+/**
+ * Every matcher, each returning `R`.
+ *
+ * Generic in the return type because the surface exists twice and that is the
+ * only thing that differs: `expect(x)` raises where a matcher fails and hands
+ * back nothing, while `expect(p).resolves` settles first and so hands back a
+ * promise. Writing the forty-one names once and saying what changes is the
+ * whole reason for the parameter — the alternative was the same list twice,
+ * with `=> void` on one copy and `=> Promise<void>` on the other, and a reader
+ * left to diff them.
+ *
+ * Where an argument is `mixed` it is because the runtime genuinely takes
+ * anything there and the checker would be lying to say otherwise: `toEqual`
+ * accepts an asymmetric matcher standing in for a value at any depth, and
+ * `toHaveValue` compares whatever a control is holding. Where it is not —
+ * `toHaveLength` wants a number, `toMatch` a string or a pattern, `toBeTypeOf`
+ * one of the eight words `typeof` produces — the narrower type is what the
+ * implementation already assumes, and saying it out loud is the point of the
+ * exercise.
+ *
+ * `not` is the same list again because negation is the only thing it changes.
+ * `resolves` and `rejects` are deliberately not here: they belong to
+ * [`Expectation`], because `expect(p).resolves.not` exists and
+ * `expect(x).not.resolves` does not.
+ */
+export type Matchers<R> = {
+  readonly toBe: (expected: mixed) => R,
+  readonly toEqual: (expected: mixed) => R,
+  readonly toStrictEqual: (expected: mixed) => R,
+  readonly toBeTruthy: () => R,
+  readonly toBeFalsy: () => R,
+  readonly toBeNull: () => R,
+  readonly toBeUndefined: () => R,
+  readonly toBeDefined: () => R,
+  readonly toBeNaN: () => R,
+  readonly toBeGreaterThan: (expected: number) => R,
+  readonly toBeGreaterThanOrEqual: (expected: number) => R,
+  readonly toBeLessThan: (expected: number) => R,
+  readonly toBeLessThanOrEqual: (expected: number) => R,
+  readonly toBeCloseTo: (expected: number, digits?: number) => R,
+  readonly toContain: (expected: mixed) => R,
+  readonly toContainEqual: (expected: mixed) => R,
+  readonly toHaveLength: (expected: number) => R,
+  readonly toHaveProperty: (path: string, ...rest: $ReadOnlyArray<mixed>) => R,
+  readonly toMatch: (expected: string | RegExp) => R,
+  readonly toMatchObject: (expected: mixed) => R,
+  readonly toBeInstanceOf: (expected: mixed) => R,
+  readonly toBeTypeOf: (expected: TypeName) => R,
+  readonly toSatisfy: (predicate: (value: mixed) => boolean) => R,
+  readonly toMatchSnapshot: (hint?: string) => R,
+  readonly toMatchInlineSnapshot: (expected?: string) => R,
+  readonly toThrow: (...rest: $ReadOnlyArray<mixed>) => R,
+  readonly toHaveBeenCalled: () => R,
+  readonly toHaveBeenCalledTimes: (count: number) => R,
+  readonly toHaveBeenCalledWith: (...args: $ReadOnlyArray<mixed>) => R,
+  readonly toHaveBeenLastCalledWith: (...args: $ReadOnlyArray<mixed>) => R,
+  readonly toBeInTheDocument: () => R,
+  readonly toBeVisible: () => R,
+  readonly toBeDisabled: () => R,
+  readonly toBeEnabled: () => R,
+  readonly toBeChecked: () => R,
+  readonly toBeRequired: () => R,
+  readonly toHaveFocus: () => R,
+  readonly toHaveAttribute: (name: string, value?: mixed) => R,
+  readonly toHaveClass: (...names: $ReadOnlyArray<string>) => R,
+  readonly toHaveTextContent: (expected: string | RegExp) => R,
+  readonly toHaveValue: (expected: mixed) => R,
+  /**
+   * Run axe-core over this element's subtree and require it to find nothing.
+   *
+   * `Promise<void>` rather than `R`, and it is the one matcher in this listing
+   * that is not generic: axe has no synchronous entry point, so the answer is
+   * a promise however the expectation was reached, and `await` is not optional.
+   *
+   *     await expect(container).toHaveNoAxeViolations();
+   *     await expect(container).toHaveNoAxeViolations({ tags: ["wcag2a"] });
+   *
+   * The rule set comes from `accessibility.axe` in `uf.config.js`; the argument
+   * narrows it for one assertion. See `./axe.js`.
+   */
+  readonly toHaveNoAxeViolations: (options?: AxeOptions) => Promise<void>,
+  readonly not: Matchers<R>,
+  ...
+};
+
+/**
+ * What `expect(received)` hands back.
+ *
+ * The matchers, plus the two that settle a promise before applying them. An
+ * intersection rather than a copy of the list with two lines added, and
+ * rather than an object spread, because a spread of an object type drops the
+ * `readonly` off every property it carries over — Flow computes a fresh object
+ * from the spread and the fresh one is writable, which would publish forty-one
+ * assignable matchers.
+ *
+ * # What is still not checked
+ *
+ * `expect(5).resolves` types, and fails when it runs. Saying otherwise needs
+ * `expect` to have two call signatures — one for a promise handing back a
+ * shape with `resolves`, one for everything else handing back a shape without
+ * — and Flow then requires the single function behind them to satisfy both,
+ * which no single function does. The overload is written down here rather than
+ * attempted because "it did not type" is the kind of thing that gets tried
+ * twice.
+ */
+export type Expectation = Matchers<void> & {
+  readonly resolves: Matchers<Promise<void>>,
+  readonly rejects: Matchers<Promise<void>>,
+  ...
+};
+
+/**
+ * `expect` itself: callable, and carrying the matchers that stand in for a
+ * value instead of being one.
+ *
+ * Inexact, and it has to be. The value is a function, every function has
+ * `name`, `length`, `call`, `apply` and `bind`, and an exact object type
+ * refuses one for exactly that reason. Inexactness costs nothing that matters
+ * here: Flow still reports a read of a property this type does not list, which
+ * is what makes `expect.anythign()` an error.
+ */
+export type Expect = {
+  (received: mixed): Expectation,
+  // `flow/unclear-type` reads source text rather than an AST, and the shape it
+  // recognises as a property key rather than a type is a name at the start of
+  // a line or straight after `{`, `,` or `;`. `readonly any:` is neither, so
+  // the rule reports Jest's, Vitest's and Sinon's name for this matcher as an
+  // `any` type. The rule's own comment already lists `@uniflowed/test`'s
+  // `expect.any` among the false positives it exists to avoid; this is the one
+  // spelling it still cannot see past.
+  // uf-lint-disable-next-line flow/unclear-type
+  readonly any: (constructor: mixed) => AsymmetricMatcher,
+  readonly anything: () => AsymmetricMatcher,
+  readonly objectContaining: (expected: interface {}) => AsymmetricMatcher,
+  readonly arrayContaining: (expected: $ReadOnlyArray<mixed>) => AsymmetricMatcher,
+  readonly stringContaining: (substring: string) => AsymmetricMatcher,
+  readonly stringMatching: (pattern: string | RegExp) => AsymmetricMatcher,
+  readonly closeTo: (value: number, digits?: number) => AsymmetricMatcher,
+  readonly not: {
+    readonly objectContaining: (expected: interface {}) => AsymmetricMatcher,
+    readonly arrayContaining: (expected: $ReadOnlyArray<mixed>) => AsymmetricMatcher,
+    readonly stringContaining: (substring: string) => AsymmetricMatcher,
+    readonly stringMatching: (pattern: string | RegExp) => AsymmetricMatcher,
+    readonly closeTo: (value: number, digits?: number) => AsymmetricMatcher,
+    ...
+  },
+  ...
+};
+
 function propertyAt(
   value: mixed,
   path: string,
@@ -88,9 +311,37 @@ function matchesThrown(thrown: mixed, expected: mixed): boolean {
  *
  * Every entry returns a [`Verdict`] rather than throwing, which is what lets
  * `.not` reuse all of them.
+ *
+ * # Every entry takes `mixed`, and that is what makes the indexer sayable
+ *
+ * [`bind`] reaches an entry by a computed key and applies it to the
+ * `$ReadOnlyArray<mixed>` it collected from the caller, so the indexer has to
+ * describe a function that will accept those arguments. Parameters are
+ * contravariant, so an entry that demanded a `number` could not be described
+ * by one — `(...args: $ReadOnlyArray<mixed>)` rejects it, and
+ * `(...args: $ReadOnlyArray<empty>)` accepts it and rejects the call. That
+ * disagreement is why this indexer used to be written `$ReadOnlyArray<any>`,
+ * with a `flow/unclear-type` suppression on it.
+ *
+ * So the disagreement is gone instead of papered over: every entry here takes
+ * `mixed` and coerces what it needs, the way most of them — `toBe`,
+ * `toBeGreaterThan`, `toHaveAttribute` — already did. Nothing a caller can see
+ * got wider: `toHaveLength` still refuses a string and `toBeTypeOf` still
+ * refuses a word `typeof` never says, because those are [`Matchers`]'s
+ * signatures and [`Matchers`] is the published type. What changed is that the
+ * table behind them stopped claiming a narrower argument than the one `bind`
+ * can hand it, which is a claim that was never true. The `String(…)` and
+ * `Number(…)` calls that appeared with it are the coercion the runtime was
+ * already doing, said out loud, and each produces the same message the implicit
+ * one did for the same input.
+ *
+ * The alternative — narrowing the indexer by writing `bind`'s forty-one
+ * wrappers out to avoid the computed lookup — is a second copy of the listing
+ * to keep in step with [`Matchers`], and is a worse trade than either. See
+ * ubugeeei-prod/uf#402.
  */
 function verdicts(received: mixed): {
-  readonly [string]: (...args: $ReadOnlyArray<any>) => Verdict,
+  readonly [string]: (...args: $ReadOnlyArray<mixed>) => Verdict | Promise<Verdict>,
 } {
   const shown = () => render(received);
   const simple = (pass: boolean, what: string, expected?: mixed): Verdict => ({
@@ -165,14 +416,15 @@ function verdicts(received: mixed): {
         `to be at most ${render(expected)}`,
         expected,
       ),
-    toBeCloseTo: (expected: number, digits?: number) => {
-      const places = digits ?? 2;
+    toBeCloseTo: (expected: mixed, digits?: mixed) => {
+      const target = Number(expected);
+      const places = digits === undefined ? 2 : Number(digits);
       const tolerance = 10 ** -places / 2;
-      const difference = Math.abs((received as $FlowFixMe) - expected);
+      const difference = Math.abs((received as $FlowFixMe) - target);
       return simple(
         difference < tolerance,
-        `to be within ${tolerance} of ${expected}, but it is off by ${difference}`,
-        expected,
+        `to be within ${tolerance} of ${target}, but it is off by ${difference}`,
+        target,
       );
     },
     toContain: (expected: mixed) => {
@@ -198,22 +450,23 @@ function verdicts(received: mixed): {
         expected,
       );
     },
-    toHaveLength: (expected: number) => {
+    toHaveLength: (expected: mixed) => {
       const length = received == null ? undefined : (received as $FlowFixMe).length;
       return simple(
         length === expected,
-        `to have length ${expected}, not ${render(length)}`,
+        `to have length ${String(expected)}, not ${render(length)}`,
         expected,
       );
     },
-    toHaveProperty: (path: string, ...rest: $ReadOnlyArray<mixed>) => {
-      const found = propertyAt(received, path);
+    toHaveProperty: (path: mixed, ...rest: $ReadOnlyArray<mixed>) => {
+      const at = String(path);
+      const found = propertyAt(received, at);
       if (rest.length === 0) {
-        return simple(found.found, `to have a property at \`${path}\``);
+        return simple(found.found, `to have a property at \`${at}\``);
       }
       return simple(
         found.found && equals(found.value, rest[0]),
-        `to have \`${path}\` equal to ${render(rest[0])}, not ${render(found.value)}`,
+        `to have \`${at}\` equal to ${render(rest[0])}, not ${render(found.value)}`,
         rest[0],
       );
     },
@@ -233,16 +486,24 @@ function verdicts(received: mixed): {
         `to be an instance of ${render(expected)}`,
         expected,
       ),
-    toBeTypeOf: (expected: string) =>
+    toBeTypeOf: (expected: mixed) => {
+      const name = String(expected);
+      return simple(
+        typeof received === name,
+        `to be of type ${name}, not ${typeof received}`,
+        name,
+      );
+    },
+    toSatisfy: (predicate: mixed) =>
       simple(
-        typeof received === expected,
-        `to be of type ${expected}, not ${typeof received}`,
-        expected,
+        typeof predicate === "function" && predicate(received) === true,
+        "to satisfy the predicate",
       ),
-    toSatisfy: (predicate: (value: mixed) => boolean) =>
-      simple(predicate(received) === true, "to satisfy the predicate"),
-    toMatchSnapshot: (hint?: string): Verdict => {
-      const verdict = snapshot.matchSnapshot(received, hint);
+    toMatchSnapshot: (hint?: mixed): Verdict => {
+      const verdict = snapshot.matchSnapshot(
+        received,
+        hint === undefined ? undefined : String(hint),
+      );
       return {
         pass: verdict.pass,
         expected: verdict.expected ?? "(no snapshot yet)",
@@ -256,8 +517,11 @@ function verdicts(received: mixed): {
         negatedFailure: () => "expected the value not to match its snapshot",
       };
     },
-    toMatchInlineSnapshot: (expected?: string): Verdict => {
-      const verdict = snapshot.matchInlineSnapshot(received, expected);
+    toMatchInlineSnapshot: (expected?: mixed): Verdict => {
+      const verdict = snapshot.matchInlineSnapshot(
+        received,
+        expected === undefined ? undefined : String(expected),
+      );
       return {
         pass: verdict.pass,
         expected: verdict.expected ?? "(no inline snapshot yet)",
@@ -308,10 +572,14 @@ function verdicts(received: mixed): {
       requireSpy("toHaveBeenCalled");
       return simple(spyCalls().length > 0, "to have been called");
     },
-    toHaveBeenCalledTimes: (count: number) => {
+    toHaveBeenCalledTimes: (count: mixed) => {
       requireSpy("toHaveBeenCalledTimes");
       const actual = spyCalls().length;
-      return simple(actual === count, `to have been called ${count} times, not ${actual}`, count);
+      return simple(
+        actual === count,
+        `to have been called ${String(count)} times, not ${actual}`,
+        count,
+      );
     },
     toHaveBeenCalledWith: (...args: $ReadOnlyArray<mixed>) => {
       requireSpy("toHaveBeenCalledWith");
@@ -422,6 +690,23 @@ function verdicts(received: mixed): {
         failure: () => `expected the value ${render(actual)} to be ${render(expected)}`,
       };
     },
+    toHaveNoAxeViolations: async (options: mixed) => {
+      const node = element("toHaveNoAxeViolations");
+      const found = await auditElement(node, (options: $FlowFixMe));
+      const named = violationIds(found);
+      return {
+        pass: found.length === 0,
+        expected: "no accessibility violations",
+        received: found.length === 0 ? "none" : named,
+        failure: () =>
+          `expected no accessibility violations, and axe-core reported ` +
+          `${String(found.length)}:\n${describeViolations(found)}`,
+        // A passing audit is not proof of an accessible component — axe finds
+        // what a machine can find — so the negated message says what was
+        // actually established rather than implying the opposite verdict.
+        negatedFailure: () => "expected axe-core to report a violation, and it reported none",
+      };
+    },
   };
 
   /**
@@ -434,7 +719,16 @@ function verdicts(received: mixed): {
   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)}`);
+      // All four arguments, unlike the first version of this: the runner
+      // renders `expected` and `received` beside the message, and a one
+      // argument call left both of them `undefined` on screen for the one
+      // failure whose whole content is what was received instead.
+      throw new AssertionError(
+        `${matcher} needs an element, and received ${render(received)}`,
+        matcher,
+        "an element",
+        render(received),
+      );
     }
     return node;
   }
@@ -446,14 +740,42 @@ function verdicts(received: mixed): {
  * 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.
+ *
+ * # The one thing a closed `<details>` still shows
+ *
+ * Its `<summary>`. A closed disclosure renders exactly one child and hides the
+ * rest, so the rule is "everything under a closed `<details>` except its
+ * summary" — and saying that needs the child the walk arrived from, not only
+ * the ancestor it is standing on. Without it the rule was written as "unless
+ * the `<details>` is the element being asked about", which exempted the
+ * disclosure from its own rule and left the summary inside it invisible:
+ * `expect(screen.getByText("More")).toBeVisible()` failed for the one thing on
+ * the screen, while the reader was looking at it.
+ *
+ * # Why this is not the walk in `react-testing`
+ *
+ * `packages/react-testing/internal/queries.js` has one that looks like this
+ * and answers a different question. `exposed` asks whether the accessibility
+ * tree announces the element, so it ignores `opacity: 0` — a screen reader
+ * reads text at zero opacity, which is exactly why hiding text that way is a
+ * bug rather than a technique — and it takes `aria-hidden` as decisive. This
+ * one asks whether a reader would *see* it, so the two answers part company
+ * there on purpose. The `<details>` half is the half they agree on, and it is
+ * written the same way in both.
  */
 function isVisible(node: Element): boolean {
+  let child: $FlowFixMe = null;
   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) {
+    if (
+      child != null &&
+      current.tagName === "DETAILS" &&
+      !current.hasAttribute("open") &&
+      child.tagName !== "SUMMARY"
+    ) {
       return false;
     }
     const style = current.ownerDocument?.defaultView?.getComputedStyle?.(current);
@@ -465,6 +787,7 @@ function isVisible(node: Element): boolean {
         return false;
       }
     }
+    child = current;
     current = current.parentElement;
   }
   return true;
@@ -490,13 +813,23 @@ function isDisabled(node: Element): boolean {
  *
  * `negated` decides which message a failing verdict raises, which is all of
  * what `.not` is.
+ *
+ * # Why the object is built rather than written
+ *
+ * `.not` has to be reached lazily or building an expectation would build its
+ * negation, which would build *its* negation, forever. A lazily installed
+ * property is not something an object literal carries, so the value is
+ * completed with `Object.defineProperty` after it exists — and an object
+ * completed after the fact is not one Flow can check a literal against. That
+ * is what this `$FlowFixMe` is, and it now covers a construction rather than a
+ * published type: [`expectValue`] states the real one, and the checker holds
+ * every caller to it.
  */
 function bind(received: mixed, negated: boolean): $FlowFixMe {
   const table = verdicts(received);
   const bound: $FlowFixMe = {};
   for (const name of Object.keys(table)) {
-    bound[name] = (...args: $ReadOnlyArray<mixed>) => {
-      const verdict = table[name](...args);
+    const decide = (verdict: Verdict) => {
       if (verdict.pass !== negated) {
         return undefined;
       }
@@ -508,6 +841,29 @@ function bind(received: mixed, negated: boolean): $FlowFixMe {
         verdict.received ?? render(received),
       );
     };
+    bound[name] = (...args: $ReadOnlyArray<mixed>) => {
+      const verdict = table[name](...args);
+      // A matcher whose engine is asynchronous answers with a promise of a
+      // verdict, and the promise is handed straight back rather than hidden.
+      //
+      // Hiding it was the alternative and it cannot be done: the only way to
+      // present an asynchronous answer synchronously is to decide before it
+      // arrives, which is deciding without it. What the promise costs is a
+      // forgotten `await`, and that case is not silent either — the rejection
+      // reaches the worker's unhandled-rejection handler, which fails the file
+      // the promise was created in and prints this same message. A missing
+      // `await` on a passing audit is the one case nothing reports, and it is
+      // the case where nothing happened.
+      //
+      // `instanceof Promise` rather than a `then` test, and it is safe for a
+      // reason that would not survive being generalised: every entry in the
+      // table is written in this file, so the only promise that can arrive
+      // here is one an `async` function in this module made, in this realm. A
+      // matcher registered from outside — which `@uniflowed/test` has no API
+      // for, deliberately — could hand back a foreign thenable, and this line
+      // would be the thing to revisit.
+      return verdict instanceof Promise ? verdict.then(decide) : decide(verdict);
+    };
   }
   Object.defineProperty(bound, "not", { get: () => bind(received, !negated) });
   return bound;
@@ -555,7 +911,12 @@ function settled(promise: mixed, wanted: "resolve" | "reject", negated: boolean)
               throw value;
             }
           : value;
-      bind(subject, negated)[name](...args);
+      // Returned rather than called and dropped: the wrapper is `async`, so
+      // returning an asynchronous matcher's promise is what awaits it. Without
+      // this, `await expect(p).resolves.toHaveNoAxeViolations()` awaited the
+      // settling and not the audit, and a violation surfaced as an unhandled
+      // rejection under whichever file was running by then.
+      return bind(subject, negated)[name](...args);
     };
   }
   Object.defineProperty(bound, "not", { get: () => settled(promise, wanted, !negated) });
@@ -571,8 +932,12 @@ function settled(promise: mixed, wanted: "resolve" | "reject", negated: boolean)
  * expect(() => parse("")).toThrow(/empty/);
  * await expect(load()).resolves.toHaveLength(3);
  * ```
+ *
+ * Takes a `mixed` and hands back a written-out [`Expectation`]. What each
+ * matcher will accept is decided by its own signature rather than by what was
+ * received, for the reasons this module's header sets out.
  */
-function expectValue(received: mixed): $FlowFixMe {
+function expectValue(received: mixed): Expectation {
   const expectation: $FlowFixMe = bind(received, false);
   Object.defineProperty(expectation, "resolves", {
     get: () => settled(received, "resolve", false),
@@ -582,11 +947,45 @@ function expectValue(received: mixed): $FlowFixMe {
 }
 
 /**
- * Assert about a value.
+ * Build the callable that carries the asymmetric matchers.
+ *
+ * The statics are attached inside a builder rather than at the module's top
+ * level, the way `internal/registry.js` builds `describe`: a shipped module
+ * may only declare, import and export at its top level, and `expect.any = …`
+ * out here is a statement that runs when the module is imported.
  *
- * 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.
+ * It was `Object.assign(expectValue, { … })`, which is what a reader expects
+ * and what does not type. Flow models `Object.assign` as returning the
+ * *target*, so the result of assigning matchers onto a function is still a
+ * function with no matchers on it — eight `prop-missing` errors saying so, and
+ * a `flow/unsafe-object-assign` suppression on top of them. Attaching to a
+ * local before it is returned is the same runtime value with none of that: the
+ * checker sees the statics arrive and holds the result to [`Expect`].
+ */
+function expecting(): Expect {
+  const api = (received: mixed): Expectation => expectValue(received);
+  api.any = asymmetric.any;
+  api.anything = asymmetric.anything;
+  api.objectContaining = asymmetric.objectContaining;
+  api.arrayContaining = asymmetric.arrayContaining;
+  api.stringContaining = asymmetric.stringContaining;
+  api.stringMatching = asymmetric.stringMatching;
+  api.closeTo = asymmetric.closeTo;
+  api.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)),
+  };
+  return api;
+}
+
+/**
+ * Assert about a value.
  *
  * 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" })`
@@ -599,22 +998,4 @@ function expectValue(received: mixed): $FlowFixMe {
  * than a negated assertion around the whole object, and is the form a suite
  * being ported will already have.
  */
-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)),
-  },
-});
+export const expect: Expect = expecting();