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

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

@@ -12,7 +12,18 @@
 //
 // The whole surface is importable from here, so a test file has one import.
 
-export type { Body as TestBody, Case, Modifier, Suite, TestOptions } from "./internal/registry.js";
+export type { Expect, Expectation, Matchers } from "./internal/expect.js";
+export type { InSourceTests } from "./in-source.js";
+export type {
+  BenchOptions,
+  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";
 export type { Outcome, Result, RunOptions } from "./internal/run.js";
 export type { Site } from "./internal/frames.js";
 export type { SpyCall, SpyResult } from "./internal/spy.js";
@@ -23,6 +34,7 @@ export {
   afterEach,
   beforeAll,
   beforeEach,
+  bench,
   describe,
   it,
   test,

package/internal/axe.js

@@ -0,0 +1,362 @@
+// @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;
+}
+
+/**
+ * The audit this process started last, settled or not.
+ *
+ * axe-core runs one audit at a time per process and refuses a second outright
+ * ("Axe is already running") rather than queueing it. One file never starts two
+ * on purpose, but a worker serves many files: a case that timed out in the
+ * middle of an audit leaves that audit running, and the next file's first audit
+ * used to fail on it — reported under a file that had done nothing wrong.
+ */
+let running: Promise<mixed> = Promise.resolve();
+
+/**
+ * Run `audit` once the audit already running has settled, however it settles.
+ *
+ * Waiting rather than failing is safe because the audit being waited on always
+ * ends — axe-core walks a finite tree — and a case that waits too long is still
+ * bounded by its own timeout.
+ */
+function afterTheAuditRunning<T>(audit: () => Promise<T>): Promise<T> {
+  const turn = running.then(audit, audit);
+  running = turn.then(
+    () => undefined,
+    () => undefined,
+  );
+  return turn;
+}
+
+/** How long to wait between looks at an audit this module did not start. */
+const FOREIGN_AUDIT_POLL_MS = 10;
+
+/** How long an audit this module did not start may hold axe-core. */
+const FOREIGN_AUDIT_LIMIT_MS = 10000;
+
+// The timer and the clock as they were when this module loaded, so a file that
+// fakes timers cannot stall a wait for a real audit to end.
+const pause: typeof setTimeout = setTimeout;
+const now: () => number = Date.now.bind(Date);
+
+/**
+ * Whether axe-core refused to start because an audit is already running.
+ *
+ * `running` queues every audit this module starts, so a refusal means an audit
+ * started somewhere else. `uf dev`'s overlay runs axe-core itself, and stopping
+ * the overlay cannot recall an audit already walking the page: its own test can
+ * leave one finishing into the next file in the worker.
+ */
+function isAlreadyRunning(error: mixed): boolean {
+  return error instanceof Error && error.message.startsWith("Axe is already running");
+}
+
+/**
+ * Run the audit once axe-core is free of an audit this module did not start.
+ *
+ * Looks again every `FOREIGN_AUDIT_POLL_MS` until axe-core takes it, and after
+ * `FOREIGN_AUDIT_LIMIT_MS` says what held the engine rather than waiting on an
+ * audit that is not going to end.
+ */
+function runOnceAxeIsFree(
+  axe: $FlowFixMe,
+  node: mixed,
+  options: mixed,
+  since: number = now(),
+): Promise<mixed> {
+  return Promise.resolve()
+    .then(() => axe.run(node, options))
+    .catch((error: mixed) => {
+      if (!isAlreadyRunning(error)) {
+        throw error;
+      }
+      if (now() - since >= FOREIGN_AUDIT_LIMIT_MS) {
+        throw new Error(
+          "axe-core has been running an audit uf did not start for ten seconds, such as " +
+            "`uf dev`'s overlay or a direct `axe.run`; this assertion could not start its own.",
+        );
+      }
+      return new Promise((resolve) => {
+        pause(resolve, FOREIGN_AUDIT_POLL_MS);
+      }).then(() => runOnceAxeIsFree(axe, node, options, since));
+    });
+}
+
+/**
+ * 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 afterTheAuditRunning(() =>
+    runOnceAxeIsFree(axe, 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(", ");
+}