@uniflowed/test 0.0.0-alpha.15 → 0.0.0-alpha.16

package/in-source.js

@@ -0,0 +1,169 @@
+// @flow
+//
+// In-source tests: `if (import.meta.uf.test) { … }` in the file being tested.
+//
+// A three-line test for a three-line pure function does not want a file of its
+// own, an import of the thing it tests, and a path that has to be kept in step
+// with it. `import.meta.uf.test` is the block that holds it, and it is the
+// same idea as Vitest's `import.meta.vitest` for the same reason.
+//
+// # What a block looks like
+//
+//     import { expect, it } from "@uniflowed/test";
+//
+//     export function add(a: number, b: number): number {
+//       return a + b;
+//     }
+//
+//     if (import.meta.uf.test) {
+//       it("adds", () => {
+//         expect(add(1, 2)).toBe(3);
+//       });
+//     }
+//
+// An ordinary import for the bindings, because that is what makes them typed:
+// Flow has no `typeof import("…")` for a library definition to use, so a
+// marker that carried the API could not be described to the checker. The
+// marker's *value* is the API anyway — `const { it } = import.meta.uf.test` is
+// what somebody arriving from Vitest writes and it works — but it is untyped,
+// and the import is the form uf recommends.
+//
+// The import costs nothing in a build. The branch folds to `if (void 0)` and
+// goes, `@uniflowed/test` declares `sideEffects: false` so the now-unused
+// import goes with it, and the package carries a `browser` field mapping the
+// six `node:` builtins its edges import at `./internal/browser/node.js` — so
+// the bundler does not even print a warning about modules it is in the middle
+// of removing.
+//
+// # What makes the block disappear
+//
+// `uf` compiles the marker away rather than leaving it to be falsy at runtime:
+// `crates/uf_transform`'s printer substitutes `void 0` for
+// `import.meta.uf.test` in every transform except the ones `uf test` asks for,
+// so `uf build` sees `if (void 0)` and the bundler removes the block. There is
+// no `import.meta.uf` at runtime, in any host, which is also why the block
+// cannot throw in a browser that never heard of uf.
+//
+// `tests/library/in-source.test.js` and `tests/library/in-source-subject.js`
+// are the block running. The other half is in `crates/uf_cli/tests/vite.rs`,
+// which builds a fixture whose block holds a string that appears nowhere else
+// and reads the emitted client bundle back looking for it — in the same file
+// the module's other marker has to be present in, because "a string is
+// missing" is only evidence when something establishes the module is not.
+//
+// # Why the marker is a call, and what it is called with
+//
+// Under `uf test` the printer substitutes
+// `globalThis.__ufInSourceTests?.(import.meta.url)`, and this module is what
+// answers it. The argument is the module asking, because a source file with an
+// in-source block is an ordinary module and is imported more than once in a
+// normal run: `uf test` imports `add.js` as the file it is running, and
+// `add.test.js` imports it again for the function. Both evaluations reach the
+// marker. Only the first is the file the run is reporting on, so only the
+// first is given the API — otherwise every in-source case would register twice
+// and the second copy would be filed under whichever test file imported it.
+
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  it,
+  test,
+} from "./internal/registry.js";
+import { fn, spyOn } from "./internal/spy.js";
+
+import type { Expect } from "./internal/expect.js";
+import type { Uft } from "./internal/namespace.js";
+import { expect } from "./internal/expect.js";
+import { uft } from "./internal/namespace.js";
+
+/**
+ * The name `uf` compiles `import.meta.uf.test` into a call on.
+ *
+ * Exported so the worker and the tests name it once; it is spelled out in `crates/uf_transform/src/print.rs` as well, and
+ * `tests/library/in-source.test.js` is what keeps the two spellings equal.
+ */
+export const IN_SOURCE_GLOBAL: "__ufInSourceTests" = "__ufInSourceTests";
+
+/**
+ * What an in-source block is handed.
+ *
+ * The subset of `@uniflowed/test` a test body needs, and deliberately not all
+ * of it: a block that wants module mocking or a snapshot is a block that has
+ * outgrown living inside the file it tests, and `import { uft } from
+ * "@uniflowed/test"` in a file of its own is the answer to that. `uft` is here
+ * anyway because spies and the fake clock are ordinary for a unit test.
+ */
+export type InSourceTests = {
+  readonly describe: typeof describe,
+  readonly it: typeof it,
+  readonly test: typeof test,
+  readonly expect: Expect,
+  readonly beforeAll: typeof beforeAll,
+  readonly beforeEach: typeof beforeEach,
+  readonly afterAll: typeof afterAll,
+  readonly afterEach: typeof afterEach,
+  readonly fn: typeof fn,
+  readonly spyOn: typeof spyOn,
+  readonly uft: Uft,
+};
+
+/**
+ * The API every in-source block in a run shares.
+ *
+ * One frozen object rather than one per file: the bindings are the module's
+ * own singletons — `it` registers into the one registry the worker resets
+ * between files — so a copy per file would only be a copy of the same
+ * references.
+ */
+const API: InSourceTests = Object.freeze({
+  describe,
+  it,
+  test,
+  expect,
+  beforeAll,
+  beforeEach,
+  afterAll,
+  afterEach,
+  fn,
+  spyOn,
+  uft,
+});
+
+/**
+ * The module URL, without whatever a host appended to it.
+ *
+ * The worker busts its import cache with `?uf-run=<generation>` so a watch
+ * rerun sees the edited file, which means the file being run reports an
+ * `import.meta.url` that its own path does not match. Comparing the part
+ * before the query is comparing the module.
+ *
+ * A hash is stripped for the same reason and never appears in practice; it
+ * costs one `indexOf` to not have to think about it again.
+ */
+function moduleUrl(url: string): string {
+  const end = url.search(/[?#]/);
+  return end === -1 ? url : url.slice(0, end);
+}
+
+/**
+ * Hand in-source blocks their API for the file `url`, and nothing to any other
+ * module.
+ *
+ * Returns the function that puts the global back as it was, which the worker
+ * calls when the file is over. Restoring rather than leaving it set is the
+ * same rule the worker applies to environment stubs and module mocks: a file
+ * may not change what the next file on this worker sees.
+ */
+export function installInSourceTests(url: string): () => void {
+  const wanted = moduleUrl(url);
+  const globals: { [string]: mixed } = globalThis as $FlowFixMe;
+  const previous = globals[IN_SOURCE_GLOBAL];
+  globals[IN_SOURCE_GLOBAL] = (asking: string): InSourceTests | void =>
+    moduleUrl(asking) === wanted ? API : undefined;
+  return () => {
+    globals[IN_SOURCE_GLOBAL] = previous;
+  };
+}

package/index.js

@@ -13,6 +13,7 @@
 // The whole surface is importable from here, so a test file has one import.
 
 export type { Expect, Expectation, Matchers } from "./internal/expect.js";
+export type { InSourceTests } from "./in-source.js";
 export type { Body as TestBody, Case, Modifier, Suite, TestOptions } from "./internal/registry.js";
 export type { ModuleFactory, ModuleNamespace } from "./internal/modules.js";
 export type { Uft } from "./internal/namespace.js";

package/internal/axe.js

@@ -0,0 +1,279 @@
+// @flow
+//
+// The accessibility audit behind `expect(container).toHaveNoAxeViolations()`.
+//
+// `@uniflowed/react-testing` renders into a real DOM, which is the expensive
+// half of an accessibility assertion — and nothing was reading it. axe-core is
+// the engine every other testing stack uses for that, it is the engine the
+// browsers' own developer tools use, and reimplementing its four hundred-odd
+// checks would be a small lookalike of exactly the kind uf's guide says not to
+// ship. So uf runs axe-core rather than competing with it. See
+// ubugeeei-prod/uf#511.
+//
+// # Why the import is dynamic, and why the specifier is a constant
+//
+// Dynamic, because `@uniflowed/test` is imported by every test file in every
+// project and most of them will never audit anything: a static import would
+// put a megabyte of rule definitions into the start-up of every worker to
+// serve the files that ask for it. It is declared as an *optional* peer
+// dependency for the same reason — a project that never writes the matcher
+// should not be made to install the engine — and a project that writes it
+// without installing it is told so in one sentence rather than by
+// `ERR_MODULE_NOT_FOUND` from inside a matcher.
+//
+// A constant specifier, because the alternative is a module path read from
+// configuration and handed to `import()`. `docs/security.md` is about exactly
+// that shape: `uf.config.js` is a file a cloned repository brings with it, and
+// "which module does the test runner load" is not a question it should get to
+// answer. What a project *may* configure is which rules run, which is data.
+//
+// # What is configured once rather than per test
+//
+// The rule set. A project that has decided `color-contrast` cannot be judged
+// by a DOM with no layout has decided it for the whole suite, and repeating
+// that decision in every assertion is how two tests come to disagree about
+// what "accessible" means. `uf.config.js`'s `accessibility.axe` block is the
+// answer, delivered to workers in the environment (`UF_AXE`) the same way
+// `UF_UPDATE_SNAPSHOTS` delivers the other run-wide decision. A call may still
+// pass overrides, and they are merged over the project's — narrowing one
+// assertion is legitimate, and it is visible on the line that does it.
+
+/** How serious a violation is, weakest first. */
+export type AxeImpact = "minor" | "moderate" | "serious" | "critical";
+
+/** What a test or a project may say about a run. */
+export type AxeOptions = {
+  /** Run only rules carrying one of these axe tags; all rules when empty. */
+  readonly tags?: $ReadOnlyArray<string>,
+  /** Rule ids to turn off, by id. */
+  readonly disabledRules?: $ReadOnlyArray<string>,
+  /** Weakest impact that counts as a failure. */
+  readonly minImpact?: AxeImpact,
+};
+
+/** One thing axe found, reduced to what a failure message needs. */
+export type AxeViolation = {
+  readonly id: string,
+  readonly impact: AxeImpact | null,
+  readonly help: string,
+  readonly helpUrl: string,
+  readonly nodes: $ReadOnlyArray<string>,
+};
+
+/** Impacts in order, so a floor can be compared rather than matched. */
+const IMPACTS: $ReadOnlyArray<AxeImpact> = ["minor", "moderate", "serious", "critical"];
+
+/** Most violations one message names; the rest are counted. */
+const MAX_VIOLATIONS_SHOWN = 10;
+
+/** Most offending elements one violation names. */
+const MAX_NODES_SHOWN = 3;
+
+/** Longest excerpt of one element's markup a message quotes. */
+const MAX_NODE_CHARS = 120;
+
+/**
+ * The engine, loaded at most once per process.
+ *
+ * A promise rather than a module, so two assertions in flight at the same time
+ * share one load rather than racing to start two.
+ */
+let engine: Promise<$FlowFixMe> | null = null;
+
+/**
+ * axe-core, or a refusal that says what to install.
+ *
+ * The `$FlowFixMe` is the module's own shape: axe-core ships TypeScript
+ * declarations and no Flow ones, so what comes back is untyped whatever this
+ * file writes. It is confined to this one binding — everything the rest of the
+ * module reads out of a result goes through the readers below, which narrow
+ * rather than assert.
+ */
+function axeEngine(): Promise<$FlowFixMe> {
+  if (engine == null) {
+    engine = import("axe-core").then(
+      (module) => {
+        const loaded: $FlowFixMe = (module as $FlowFixMe).default ?? module;
+        if (loaded == null || typeof loaded.run !== "function") {
+          throw new Error("`axe-core` is installed but has no `run`, so uf cannot audit with it");
+        }
+        return loaded;
+      },
+      () => {
+        throw new Error(
+          "`toHaveNoAxeViolations` needs axe-core, which this project does not have. " +
+            "Add it — `uf add -D axe-core` — and the matcher, and `uf dev`'s audit, " +
+            "start working; uf does not install it for you because a project that " +
+            "never audits should not carry the engine.",
+        );
+      },
+    );
+  }
+  return engine;
+}
+
+/** A string field, or `""`. */
+function stringAt(value: mixed, key: string): string {
+  if (value == null || typeof value !== "object") return "";
+  const found = value[key];
+  return typeof found === "string" ? found : "";
+}
+
+/** An array field, or an empty one. */
+function arrayAt(value: mixed, key: string): $ReadOnlyArray<mixed> {
+  if (value == null || typeof value !== "object") return [];
+  const found = value[key];
+  return Array.isArray(found) ? found : [];
+}
+
+/** The impact named at `key`, when it is one of the four. */
+function impactAt(value: mixed, key: string): AxeImpact | null {
+  const impact = stringAt(value, key);
+  return IMPACTS.find((known) => known === impact) ?? null;
+}
+
+/** The impact axe gave a violation, when it gave one it knows. */
+function impactOf(value: mixed): AxeImpact | null {
+  return impactAt(value, "impact");
+}
+
+/**
+ * The project's settings, read once from the environment.
+ *
+ * Absent, unreadable or the wrong shape all mean the same thing: no project
+ * settings, run every rule. A malformed value is not worth failing a suite
+ * over — the setting is a narrowing, and the widest answer is the safe one.
+ */
+function projectOptions(): AxeOptions {
+  const raw =
+    typeof process === "undefined" ? undefined : ((process.env as $FlowFixMe)?.UF_AXE ?? undefined);
+  if (typeof raw !== "string" || raw === "") return {};
+  let parsed: mixed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {};
+  }
+  if (parsed == null || typeof parsed !== "object") return {};
+  const tags = arrayAt(parsed, "tags").filter((tag) => typeof tag === "string");
+  const disabled = arrayAt(parsed, "disabledRules").filter((rule) => typeof rule === "string");
+  const impact = impactAt(parsed, "minImpact") ?? undefined;
+  return {
+    tags: tags as $FlowFixMe,
+    disabledRules: disabled as $FlowFixMe,
+    minImpact: impact,
+  };
+}
+
+/** The project's settings, with a call's own merged over them. */
+function resolveOptions(overrides: AxeOptions | void): AxeOptions {
+  const project = projectOptions();
+  return {
+    tags: overrides?.tags ?? project.tags,
+    disabledRules: overrides?.disabledRules ?? project.disabledRules,
+    minImpact: overrides?.minImpact ?? project.minImpact,
+  };
+}
+
+/** Those settings in axe's own vocabulary. */
+function axeRunOptions(options: AxeOptions): { [string]: mixed } {
+  const run: { [string]: mixed } = {};
+  const tags = options.tags ?? [];
+  if (tags.length > 0) run.runOnly = { type: "tag", values: [...tags] };
+  const disabled = options.disabledRules ?? [];
+  if (disabled.length > 0) {
+    const rules: { [string]: mixed } = {};
+    for (const rule of disabled) rules[rule] = { enabled: false };
+    run.rules = rules;
+  }
+  return run;
+}
+
+/**
+ * Whether a violation is at or above the configured floor.
+ *
+ * A violation axe could not rate is kept: "we do not know how bad this is" is
+ * not a reason to drop it, and dropping it is how a floor set to `critical`
+ * would quietly hide everything unrated.
+ */
+function meetsFloor(violation: AxeViolation, floor: AxeImpact | void): boolean {
+  if (floor == null || violation.impact == null) return true;
+  return IMPACTS.indexOf(violation.impact) >= IMPACTS.indexOf(floor);
+}
+
+/** One element, as short a piece of markup as still identifies it. */
+function excerpt(html: string): string {
+  const line = html.split("\n")[0].trim();
+  return line.length > MAX_NODE_CHARS ? `${line.slice(0, MAX_NODE_CHARS)}…` : line;
+}
+
+/**
+ * Audit `node` and report what it found, weakest results already dropped.
+ *
+ * Rejects when axe-core is not installed or the host has no document to audit.
+ * Both are "this assertion cannot be made here" rather than "this assertion
+ * failed", and both are ordinary errors rather than an [`AssertionError`]: the
+ * runner prints an assertion failure as a comparison, and there is nothing
+ * here to compare — what a reader needs is the sentence saying what to
+ * install.
+ */
+export async function auditElement(
+  node: mixed,
+  overrides?: AxeOptions,
+): Promise<$ReadOnlyArray<AxeViolation>> {
+  if (typeof globalThis.document === "undefined") {
+    throw new Error(
+      "`toHaveNoAxeViolations` needs a document, and this host has none. " +
+        "Render with `@uniflowed/react-testing`, or run the file with `uf test --browser`.",
+    );
+  }
+  const axe = await axeEngine();
+  const options = resolveOptions(overrides);
+  const results = await axe.run(node, axeRunOptions(options));
+  const found: Array<AxeViolation> = [];
+  for (const raw of arrayAt(results, "violations")) {
+    const violation: AxeViolation = {
+      id: stringAt(raw, "id"),
+      impact: impactOf(raw),
+      help: stringAt(raw, "help"),
+      helpUrl: stringAt(raw, "helpUrl"),
+      nodes: arrayAt(raw, "nodes").map((one) => excerpt(stringAt(one, "html"))),
+    };
+    if (meetsFloor(violation, options.minImpact)) found.push(violation);
+  }
+  return found;
+}
+
+/**
+ * What a reader is told when the audit found something.
+ *
+ * The rule id, what it wants, the elements that broke it, and the page Deque
+ * publishes about it — which is the part that turns "aria-required-children"
+ * into something a person can act on without a search engine.
+ *
+ * Bounded, because a container rendered from bad markup can violate a hundred
+ * rules and a failure that fills a terminal is a failure nobody reads.
+ */
+export function describeViolations(violations: $ReadOnlyArray<AxeViolation>): string {
+  const lines: Array<string> = [];
+  for (const violation of violations.slice(0, MAX_VIOLATIONS_SHOWN)) {
+    const impact = violation.impact == null ? "" : ` (${violation.impact})`;
+    lines.push(`  ${violation.id}${impact} — ${violation.help}`);
+    for (const node of violation.nodes.slice(0, MAX_NODES_SHOWN)) {
+      lines.push(`    ${node}`);
+    }
+    if (violation.nodes.length > MAX_NODES_SHOWN) {
+      lines.push(`    …and ${violation.nodes.length - MAX_NODES_SHOWN} more elements`);
+    }
+    if (violation.helpUrl !== "") lines.push(`    ${violation.helpUrl}`);
+  }
+  if (violations.length > MAX_VIOLATIONS_SHOWN) {
+    lines.push(`  …and ${violations.length - MAX_VIOLATIONS_SHOWN} more rules`);
+  }
+  return lines.join("\n");
+}
+
+/** The rule ids a set of violations covers, for the `expected`/`received` pair. */
+export function violationIds(violations: $ReadOnlyArray<AxeViolation>): string {
+  return violations.map((violation) => violation.id).join(", ");
+}

package/internal/browser/node.js

@@ -0,0 +1,375 @@
+// @flow
+//
+// The `node:` builtins `@uniflowed/test` reaches for, as a browser can have
+// them.
+//
+// # Why a package the browser never runs needs a browser build
+//
+// A module with an in-source test block imports `@uniflowed/test` at its top
+// level, and that block is compiled away by `uf build` — `import.meta.uf.test`
+// becomes `void 0`, the bundler drops the branch, and the import goes with it
+// because the package declares `sideEffects: false`. But a bundler *resolves*
+// a graph before it shakes it, so the six builtins this package's edges import
+// were resolved on the way to being discarded: `node:fs` and `node:path` for
+// snapshot files, `node:module` and `node:url` for module mocking,
+// `node:async_hooks` and `node:util` for output capture. Each one printed
+//
+//     Module "node:fs" has been externalized for browser compatibility
+//
+// so a project with one three-line in-source test got six warnings about
+// modules `uf build` was in the middle of removing.
+//
+// `package.json`'s `browser` field maps all six here. Node ignores that field
+// and every bundler honours it, so nothing about running a test on a host
+// changes and the build is quiet.
+//
+// One file rather than six of four lines, because the question a reader has is
+// "what does a browser not have", and that is answered better in one place
+// than in six.
+//
+// # Why the shims work rather than only resolve
+//
+// Nothing here is reached by the build that made it necessary: the module that
+// imports it is removed. What makes the implementations below worth writing is
+// the case where the package *is* evaluated in a browser — a runner that ran a
+// test file in a real page, which `docs/roadmap.md` still lists as not done, or
+// an application that genuinely imports `@uniflowed/test` into client code.
+// A file that exists only to be resolved would be a file that fails the moment
+// somebody's build stops shaking it out, and that failure would arrive as a
+// missing export rather than as a sentence.
+//
+// # Two kinds of shim, and the difference is the point
+//
+// Some of these are **implementations**: `format`, `inspect`, `pathToFileURL`
+// and the path helpers do in a browser what they do in Node, closely enough
+// for the one caller each has. `AsyncLocalStorage` is an implementation with a
+// named limitation.
+//
+// The rest are **refusals**: the filesystem is not something a page has, and
+// `createRequire` cannot invent a synchronous module loader. Each one throws a
+// sentence naming what is not available and what to do instead. A shim that
+// answered plausibly — an `existsSync` that said `false`, say — would be worse
+// than no browser mode at all: `toMatchSnapshot` would read "no snapshot yet",
+// record one it could not write, and pass. That is the runner lying, which is
+// the failure `uf test` exists not to have.
+//
+// Each refusal names what is not available and what to do instead, so a
+// boundary is a sentence rather than a surprise in a stack trace.
+
+/** How a refusal is worded, so all of them read the same way. */
+function unavailable(what: string, instead: string): Error {
+  return new Error(
+    `${what} is not available in \`uf test --browser\`: a page has no ${what}. ${instead}`,
+  );
+}
+
+// ---------------------------------------------------------------------- //
+// node:fs — refused
+// ---------------------------------------------------------------------- //
+
+/** Snapshot files live on a disk the page cannot see. */
+export function existsSync(_path: mixed): empty {
+  throw unavailable(
+    "the filesystem",
+    "Snapshots (`toMatchSnapshot`) are written by the host that runs the file; assert with `toMatchInlineSnapshot`, which needs no file, or run the file on Node.",
+  );
+}
+
+/** @see existsSync */
+export function readFileSync(_path: mixed, _encoding?: mixed): empty {
+  return existsSync(_path);
+}
+
+/** @see existsSync */
+export function writeFileSync(_path: mixed, _contents: mixed): empty {
+  return existsSync(_path);
+}
+
+/** @see existsSync */
+export function mkdirSync(_path: mixed, _options?: mixed): empty {
+  return existsSync(_path);
+}
+
+// ---------------------------------------------------------------------- //
+// node:module — refused, with one door left open
+// ---------------------------------------------------------------------- //
+
+/**
+ * Modules the page has already imported, by the specifier they answer to.
+ *
+ * The one thing `createRequire` is used for that a browser *can* do. It is
+ * `@uniflowed/react-testing`'s `render`, which loads `react-dom/client` through
+ * `createRequire` rather than an import because `render` is synchronous and an
+ * import is not — a decision that is right on Node and impossible here.
+ *
+ * So the page's entry module imports `react-dom/client` itself, before any
+ * test file runs, and puts it here. `render` then finds it synchronously, and
+ * the import that made that possible happened at a moment when being
+ * asynchronous cost nothing.
+ */
+const provided: Map<string, mixed> = new Map();
+
+/**
+ * Register a module the page has already imported.
+ *
+ * Called by whatever brought this package into a page, never by a test.
+ */
+export function provideModule(specifier: string, module: mixed): void {
+  provided.set(specifier, module);
+}
+
+/**
+ * A `require` that answers for what the page brought with it and refuses the
+ * rest.
+ *
+ * Refusing loudly rather than returning `undefined`: a caller that gets
+ * `undefined` back fails later, somewhere else, with a message about a
+ * property of `undefined`.
+ */
+export function createRequire(_from: mixed): (specifier: string) => mixed {
+  return (specifier: string) => {
+    if (provided.has(specifier)) return provided.get(specifier);
+    throw unavailable(
+      `a synchronous \`require("${specifier}")\``,
+      "Import it from the test file instead; a browser resolves modules asynchronously and cannot be asked to do it in the middle of a call.",
+    );
+  };
+}
+
+// ---------------------------------------------------------------------- //
+// node:url — implemented
+// ---------------------------------------------------------------------- //
+
+/** A path as the `file:` URL Node would produce. */
+export function pathToFileURL(filePath: string): URL {
+  const withSlashes = filePath.replace(/\\/g, "/");
+  const absolute = withSlashes.startsWith("/") ? withSlashes : `/${withSlashes}`;
+  return new URL(`file://${absolute.split("/").map(encodeURIComponent).join("/")}`);
+}
+
+/** The path inside a `file:` URL. */
+export function fileURLToPath(url: string | URL): string {
+  const href = typeof url === "string" ? url : url.href;
+  if (!href.startsWith("file://")) {
+    throw new TypeError(`not a file URL: ${href}`);
+  }
+  return decodeURIComponent(href.slice("file://".length));
+}
+
+// ---------------------------------------------------------------------- //
+// node:util — implemented
+// ---------------------------------------------------------------------- //
+
+/**
+ * `util.inspect`, to the depth a test's `console.log` needs.
+ *
+ * Not Node's algorithm — no getters, no circular references marked, no colour.
+ * What it has to be is *stable* and *readable*, because its output is what a
+ * failing test's printing looks like in the terminal, and `JSON.stringify`
+ * with a replacer that names functions and symbols is both.
+ */
+export function inspect(value: mixed): string {
+  if (typeof value === "string") return `'${value}'`;
+  return renderValue(value, new Set());
+}
+
+function renderValue(value: mixed, seen: Set<mixed>): string {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (typeof value === "string") return `'${value}'`;
+  if (typeof value === "bigint") return `${String(value)}n`;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (typeof value === "symbol") return String(value);
+  if (typeof value === "function") {
+    const name = (value as $FlowFixMe).name;
+    return name === "" ? "[Function (anonymous)]" : `[Function: ${String(name)}]`;
+  }
+  if (value instanceof Error) return `${value.name}: ${value.message}`;
+  if (typeof value !== "object") return String(value);
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return `[ ${value.map((item: mixed) => renderValue(item, seen)).join(", ")} ]`;
+    }
+    const entries = Object.entries(value).map(
+      ([key, item]) => `${key}: ${renderValue(item, seen)}`,
+    );
+    return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+/**
+ * `util.format`, with the `%s`/`%d`/`%i`/`%j`/`%o`/`%O`/`%%` substitutions
+ * `console.log` uses.
+ *
+ * Everything left over is appended, space separated, exactly as Node does —
+ * which is the behaviour `console.log("a", 1, { b: 2 })` depends on.
+ */
+export function format(first: mixed, ...rest: $ReadOnlyArray<mixed>): string {
+  const args = [...rest];
+  let out = "";
+  if (typeof first === "string") {
+    let at = 0;
+    while (at < first.length) {
+      const ch = first[at];
+      if (ch !== "%" || at + 1 >= first.length) {
+        out += ch;
+        at += 1;
+        continue;
+      }
+      const kind = first[at + 1];
+      if (kind === "%") {
+        out += "%";
+        at += 2;
+        continue;
+      }
+      if (!"sdifjoO".includes(kind) || args.length === 0) {
+        out += ch;
+        at += 1;
+        continue;
+      }
+      const value = args.shift();
+      if (kind === "s") out += typeof value === "string" ? value : renderValue(value, new Set());
+      else if (kind === "d" || kind === "f") out += String(Number(value));
+      else if (kind === "i") out += String(Math.trunc(Number(value)));
+      else if (kind === "j") out += safeJson(value);
+      else out += renderValue(value, new Set());
+      at += 2;
+    }
+  } else {
+    out = renderValue(first, new Set());
+  }
+  for (const value of args) {
+    out += ` ${typeof value === "string" ? value : renderValue(value, new Set())}`;
+  }
+  return out;
+}
+
+function safeJson(value: mixed): string {
+  try {
+    return JSON.stringify(value) ?? "undefined";
+  } catch {
+    return "[Circular]";
+  }
+}
+
+// ---------------------------------------------------------------------- //
+// node:async_hooks — implemented, with a limitation that is written down
+// ---------------------------------------------------------------------- //
+
+/**
+ * A single-value stand-in for Node's asynchronous storage.
+ *
+ * The real one follows a value through every continuation of the work that
+ * entered it; this one holds whichever `run` is on the stack. A browser has no
+ * asynchronous context tracking to build the real thing on — the platform
+ * proposal for it is not shipped anywhere — and the alternative to an
+ * approximation is that `@uniflowed/test`'s output capture cannot be imported
+ * at all.
+ *
+ * What it costs is bounded by what the store is used for here.
+ * `internal/output.js` reads it to attribute a `console.log` to the case that
+ * printed it, and cases run one at a time, so the answer is right for
+ * everything a case prints while it is running. It is wrong for a `setTimeout`
+ * a finished case left behind: the print is still reported, attributed to the
+ * file rather than to the case. On Node that same straggler is attributed to
+ * its case; here it is attributed one level up.
+ *
+ * That is the whole of the difference, and it is a difference in a label on a
+ * line of output — not in what passes.
+ */
+export class AsyncLocalStorage<T> {
+  #store: T | void = undefined;
+
+  /** Run `body` with `value` readable from `getStore`. */
+  run<R>(value: T, body: () => R): R {
+    const previous = this.#store;
+    this.#store = value;
+    try {
+      return body();
+    } finally {
+      this.#store = previous;
+    }
+  }
+
+  /** The value of the nearest enclosing `run`, or `undefined`. */
+  getStore(): T | void {
+    return this.#store;
+  }
+
+  /** Run `body` with no value readable. */
+  exit<R>(body: () => R): R {
+    const previous = this.#store;
+    this.#store = undefined;
+    try {
+      return body();
+    } finally {
+      this.#store = previous;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------- //
+// node:path — implemented, posix only
+// ---------------------------------------------------------------------- //
+
+/**
+ * The path operations `internal/snapshot.js` performs on a snapshot path.
+ *
+ * Posix only, which is not a limitation here: every path a page sees came from
+ * a URL, and a URL's separator is `/` on every platform.
+ */
+export const path: {
+  readonly join: (...parts: $ReadOnlyArray<string>) => string,
+  readonly dirname: (of: string) => string,
+  readonly basename: (of: string, extension?: string) => string,
+  readonly extname: (of: string) => string,
+  readonly resolve: (...parts: $ReadOnlyArray<string>) => string,
+  readonly sep: string,
+} = {
+  sep: "/",
+  join: (...parts) => normalize(parts.filter((part) => part !== "").join("/")),
+  dirname: (of) => {
+    const at = of.lastIndexOf("/");
+    if (at === -1) return ".";
+    return at === 0 ? "/" : of.slice(0, at);
+  },
+  basename: (of, extension) => {
+    const name = of.slice(of.lastIndexOf("/") + 1);
+    return extension != null && name.endsWith(extension)
+      ? name.slice(0, name.length - extension.length)
+      : name;
+  },
+  extname: (of) => {
+    const name = of.slice(of.lastIndexOf("/") + 1);
+    const at = name.lastIndexOf(".");
+    return at <= 0 ? "" : name.slice(at);
+  },
+  resolve: (...parts) => {
+    let out = "";
+    for (const part of parts) {
+      if (part.startsWith("/")) out = part;
+      else if (out === "") out = part;
+      else out = `${out}/${part}`;
+    }
+    return normalize(out.startsWith("/") ? out : `/${out}`);
+  },
+};
+
+/** `a//b/./c/../d` as `a/b/d`, keeping a leading slash. */
+function normalize(input: string): string {
+  const absolute = input.startsWith("/");
+  const out: Array<string> = [];
+  for (const part of input.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === ".." && out.length > 0 && out[out.length - 1] !== "..") out.pop();
+    else out.push(part);
+  }
+  const joined = out.join("/");
+  return absolute ? `/${joined}` : joined === "" ? "." : joined;
+}
+
+export default path;

package/internal/expect.js

@@ -66,9 +66,11 @@
 // 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";
 
@@ -90,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,
@@ -177,6 +186,20 @@ export type Matchers<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>,
   ...
 };
@@ -318,7 +341,7 @@ function matchesThrown(thrown: mixed, expected: mixed): boolean {
  * ubugeeei-prod/uf#402.
  */
 function verdicts(received: mixed): {
-  readonly [string]: (...args: $ReadOnlyArray<mixed>) => Verdict,
+  readonly [string]: (...args: $ReadOnlyArray<mixed>) => Verdict | Promise<Verdict>,
 } {
   const shown = () => render(received);
   const simple = (pass: boolean, what: string, expected?: mixed): Verdict => ({
@@ -667,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",
+      };
+    },
   };
 
   /**
@@ -679,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;
   }
@@ -780,8 +829,7 @@ 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;
       }
@@ -793,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;
@@ -840,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) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/test",
-  "version": "0.0.0-alpha.15",
+  "version": "0.0.0-alpha.16",
   "description": "The test API and worker for `uf test`: describe/it, a full matcher set, and the process uf fans test files out to.",
   "type": "module",
   "license": "MIT",
@@ -12,15 +12,33 @@
   },
   "exports": {
     ".": "./index.js",
+    "./in-source": "./in-source.js",
     "./worker": "./worker.js",
     "./package.json": "./package.json"
   },
   "files": [
+    "in-source.js",
     "index.js",
-    "worker.js",
-    "internal"
+    "internal",
+    "worker.js"
   ],
   "dependencies": {
-    "@uniflowed/host": "0.0.0-alpha.15"
+    "@uniflowed/host": "0.0.0-alpha.16"
+  },
+  "peerDependencies": {
+    "axe-core": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "axe-core": {
+      "optional": true
+    }
+  },
+  "browser": {
+    "node:async_hooks": "./internal/browser/node.js",
+    "node:fs": "./internal/browser/node.js",
+    "node:module": "./internal/browser/node.js",
+    "node:path": "./internal/browser/node.js",
+    "node:url": "./internal/browser/node.js",
+    "node:util": "./internal/browser/node.js"
   }
 }

package/worker.js

@@ -53,6 +53,7 @@ import { writeChangedSnapshots } from "./internal/snapshot.js";
 import { createInterface } from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { installInSourceTests } from "./in-source.js";
 import { restoreSharedState } from "./internal/isolation.js";
 import { run } from "./internal/run.js";
 
@@ -155,8 +156,44 @@ async function runFile(request: Request, generation: number): Promise<void> {
   // file about to run, rather than something the previous file left behind.
   output.startFile();
 
+  // In-source blocks in *this* file get uf's test API; the same blocks in
+  // every module this file imports get `undefined` and do not register. See
+  // `./in-source.js` for why the marker is a call rather than a constant.
+  const url = pathToFileURL(request.file).href;
+  const uninstallInSourceTests = installInSourceTests(url);
   try {
-    await import(`${pathToFileURL(request.file).href}?uf-run=${generation}`);
+    await runImportedFile(request, generation, url, started);
+  } finally {
+    // For the whole file rather than only for its import. A block reads the
+    // marker at module scope, but a *case body* may read it too — `const
+    // { uft } = import.meta.uf.test` inside an `it` is an ordinary thing to
+    // write — and a marker that answered during the import and not during the
+    // run would be a value that changed under the file that read it.
+    //
+    // Taking it away earlier would not buy the isolation it looks like it
+    // buys: work a finished file left behind can register through a binding it
+    // captured just as easily as through this global, so the thing that keeps
+    // a straggler out of the next file is the registry reset at the top of
+    // this function and the generation stamped on every event, not the
+    // lifetime of one accessor.
+    uninstallInSourceTests();
+  }
+}
+
+/**
+ * The half of [`runFile`] that has a file to run.
+ *
+ * Split out so the caller's `finally` covers the import *and* the run without
+ * either of the two `return`s below escaping it.
+ */
+async function runImportedFile(
+  request: Request,
+  generation: number,
+  url: string,
+  started: number,
+): Promise<void> {
+  try {
+    await import(`${url}?uf-run=${generation}`);
   } catch (thrown) {
     const error = thrown instanceof Error ? thrown : new Error(String(thrown));
     write({