@uniflowed/test 0.0.0-alpha.9 → 0.1.0

package/internal/isolation.js

@@ -0,0 +1,231 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: what a file is allowed to leave behind.
+//
+// A worker serves many files out of one process, one at a time (`../worker.js`
+// says why). Everything a file registers lives in this package and is cleared
+// with it; everything a file *reaches around* the package to change belongs to
+// the process, outlives the file, and is handed to whichever file the schedule
+// puts next in that worker.
+//
+// That second list is what this module is. It has been discovered four times,
+// and each time the same way — a suite that passed alone and failed beside
+// another, naming the file that read the value rather than the file that wrote
+// it:
+//
+//   * ubugeeei-prod/uf#417, `uft.stubEnv("NODE_ENV", …)` still set for the
+//     next file;
+//   * ubugeeei-prod/uf#581, a fake clock still installed, so the next file's
+//     `setTimeout` — including the one each case is raced against — never
+//     fired and the file hung with nothing on screen;
+//   * ubugeeei-prod/uf#607, `document.body` still holding the markup a
+//     hydration test wrote into it, so the next file's "there is one image on
+//     the page" found six;
+//   * ubugeeei-prod/uf#944, the window around that body: a `matchMedia` a file
+//     removed, and the document's `FormData` left in place of Node's. That one is not on the list below, because this package does not
+//     make the window — `@uniflowed/react-testing` does, and registers how to
+//     put it back (see `registeredElsewhere`).
+//
+// Which files share a worker is decided by `.uf/test-timings.json`, so a leak
+// makes the *result* of a suite depend on how the machine was loaded the last
+// time it ran. That is the failure this module exists to end, and the reason
+// it is a list in one place rather than three calls in `../worker.js`: the
+// question "what else does a file share with the next one" now has somewhere
+// to be answered, and a fourth answer is one entry rather than one more thing
+// to remember.
+//
+// # What belongs here
+//
+// State that (a) the process shares, (b) a test can change from inside a file,
+// and (c) nothing else puts back. Anything a file merely *reads* does not
+// belong here, and neither does anything the registry already clears — a spy
+// is not on this list because `reset()` is what a spy lives in.
+//
+// # When it runs
+//
+// Before the next file is imported, not after the previous one is run. A file
+// that throws while loading is still a file that has run code, and it still
+// hands the next one whatever that code changed; putting things back on the
+// way *in* covers the load failure and the crash as well as the ordinary end.
+// It also means the first file in a worker starts from the same state as the
+// tenth.
+
+import { reset } from "./registry.js";
+import { resetModuleState } from "./modules.js";
+import { unstubAllEnvs, unstubAllGlobals } from "./namespace.js";
+// Renamed at the door, for two reasons that agree. It reads as the resets
+// beside it do — `reset`, `unstubAllEnvs`, `resetModuleState` are all
+// verb-first, and so is what this does to the clock.
+import { restoreRealClock } from "./timers.js";
+
+/**
+ * One piece of process-wide state a file can change, and how to put it back.
+ *
+ * `what` is written for a person reading this list rather than for any code:
+ * nothing branches on it, and it is here because a list of five bare function
+ * references is a list nobody can check against the paragraph above it.
+ */
+type Shared = {|
+  readonly what: string,
+  readonly restore: () => void,
+|};
+
+/**
+ * Everything a file shares with the file after it, in the order it goes back.
+ *
+ * The order matters in one place and is harmless everywhere else: the clock
+ * goes back before the module stand-ins do, because a stand-in's factory runs
+ * on the next import and a factory that schedules anything under a leaked fake
+ * clock would schedule it into a clock nobody is going to advance.
+ */
+const SHARED: $ReadOnlyArray<Shared> = [
+  {
+    what: "the tests, hooks and spies this package registered",
+    restore: reset,
+  },
+  {
+    // `process.env` belongs to the process. `uft.stubEnv("NODE_ENV",
+    // "production")` in one file is still set when the next one imports, and
+    // the file that fails is the one that read it.
+    what: "environment variables `uft.stubEnv` replaced",
+    restore: unstubAllEnvs,
+  },
+  {
+    // `globalThis` likewise, and worse: a stubbed `fetch` makes the next file
+    // talk to a stand-in that does not know about it.
+    what: "globals `uft.stubGlobal` replaced",
+    restore: unstubAllGlobals,
+  },
+  {
+    // Worse than a leaked value, and worse in a way that hides it. A leaked
+    // stub makes the next file read something wrong, which arrives as an
+    // assertion naming the value. A leaked clock makes the next file's
+    // `setTimeout` never fire — including the one `withTimeout` races each
+    // case against — so the file hangs with nothing on screen until `uf`'s own
+    // deadline kills the worker, and the report names the file that waited
+    // rather than the file that stopped time.
+    what: "the clock, whatever `uft.useFakeTimers` did to it",
+    restore: restoreRealClock,
+  },
+  {
+    // A worker serves many files out of one module registry, so this is the
+    // difference between "one file at a time" and "one file's mocks at a
+    // time".
+    what: "modules `uft.mock` stood in for",
+    restore: resetModuleState,
+  },
+  {
+    what: "the document, if this process has one",
+    restore: restoreDocument,
+  },
+];
+
+/**
+ * Hand the next file a document nobody else has written to.
+ *
+ * The document is process-wide in a way that is easy to miss, because nothing
+ * in this package installs it: `@uniflowed/react-testing` puts one on the
+ * global object the first time a test renders and deliberately keeps it for
+ * the life of the process — replacing it would strand every React root already
+ * mounted in the old one. So one document serves every file a worker runs, and
+ * what a file leaves in it is what the next file queries.
+ *
+ * Its *contents* are put back rather than the document itself, and "back"
+ * means empty: a file is handed the body it would have had if it had installed
+ * the document itself. `cleanup()` already unmounts what `render` mounted, and
+ * that is not the leak — the leak is markup a test wrote into the body by
+ * hand, which a hydration test must do because hydration is React attaching to
+ * markup that is already there. `rsc-split.test.js` and `streaming.test.js`
+ * both `replaceChildren` into the body, and the file after them in that worker
+ * started with somebody else's page.
+ *
+ * Read through `globalThis` and guarded by `typeof`, because a worker running
+ * a suite that never renders has no `document` at all and must not pay for
+ * one — and because on a host that *is* a browser this is the page, whose body
+ * a run of `uf test` has no business emptying. It only ever clears a body that
+ * a test process is using as scratch space, which is every case this can
+ * reach: the shim's document, or a page the project chose to run its own tests
+ * in.
+ */
+function restoreDocument(): void {
+  if (typeof globalThis.document === "undefined") {
+    return;
+  }
+  const body = globalThis.document.body;
+  if (body == null) {
+    // A document a parser produced need not have one, and a document with no
+    // body is a document with nothing to put back.
+    return;
+  }
+  body.replaceChildren();
+  // The attributes too, and not for tidiness: `<body class="dark">` is how a
+  // theme test says what it is testing, and a file that leaves one behind
+  // makes the next file's "the page is in light mode" false for a reason it
+  // cannot see. Read into an array first — removing an attribute while
+  // iterating a live list is the loop that skips every other entry.
+  for (const name of [...body.getAttributeNames()]) {
+    body.removeAttribute(name);
+  }
+}
+
+/**
+ * Where other packages register process-wide state of their own.
+ *
+ * A package this one does not depend on can still install something a file
+ * changes and the next file reads: `@uniflowed/react-testing` installs a window
+ * on the first render and keeps it for the process. Only that package knows
+ * what the window looked like when it made it, so it registers how to put it
+ * back — a name for the message below, and a function — in a `Map` under this
+ * symbol, and every entry runs after the list above.
+ *
+ * A symbol from the global registry rather than an export, so the package that
+ * registers needs no import of this one: under another runner the entry is
+ * never read and costs nothing.
+ */
+const SHARED_STATE: symbol = Symbol.for("@uniflowed/test/shared-state");
+
+/** Every entry another package registered, as this module's own entries are shaped. */
+function registeredElsewhere(): $ReadOnlyArray<Shared> {
+  const registry: mixed = Reflect.get(globalThis, SHARED_STATE);
+  if (!(registry instanceof Map)) {
+    return [];
+  }
+  const entries: Array<Shared> = [];
+  for (const [what, restore] of registry) {
+    if (typeof what === "string" && typeof restore === "function") {
+      entries.push({ what, restore: () => void restore() });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Put back everything the file that just ran may have changed.
+ *
+ * Called by `../worker.js` before it imports the next file. Nothing here
+ * reports a file for having changed any of this: a file is *allowed* to — that
+ * is what the `uft` namespace is for — and the contract is that the change
+ * does not outlive the file, not that it never happened.
+ *
+ * Every entry is attempted even after one has thrown, and the first failure is
+ * raised afterwards under the name of what it could not put back. Stopping at
+ * the first would leave the four entries behind it un-restored, which is the
+ * defect this module exists to prevent arriving by a new route — and a bare
+ * throw from one of these used to say only that something in the runner failed
+ * between two files.
+ */
+export function restoreSharedState(): void {
+  let failure: { readonly what: string, readonly thrown: mixed } | null = null;
+  for (const shared of [...SHARED, ...registeredElsewhere()]) {
+    try {
+      shared.restore();
+    } catch (thrown) {
+      failure ??= { what: shared.what, thrown };
+    }
+  }
+  if (failure != null) {
+    const cause = failure.thrown;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(`@uniflowed/test could not put back ${failure.what}: ${message}`);
+  }
+}

package/internal/namespace.js

@@ -50,8 +50,11 @@ const stubbedGlobals: Map<string, { readonly owned: boolean, readonly value: mix
 /**
  * Read the process environment, whichever host this is.
  *
- * Node, Deno and Bun all expose `process.env`; Deno also has `Deno.env`, and
- * reaching for `process` first keeps one code path across the three.
+ * Node and Bun expose `process` as a global; **Deno does not**, and has the
+ * same object under `node:process`. `../worker.js` installs it on the global
+ * before anything here runs, which is what keeps this one code path across the
+ * three — and is why the `null` branch below is still reachable, for a host
+ * that is neither.
  */
 function environment(): { [string]: string } | null {
   const host = globalThis as $FlowFixMe;
@@ -59,10 +62,15 @@ function environment(): { [string]: string } | null {
 }
 
 /**
- * Replace an environment variable for the rest of the test.
+ * Replace an environment variable for the rest of the file.
  *
- * Undone by `unstubAllEnvs`, which the runner calls between files — a stub that
- * outlived its test would be a test that passes alone and fails in a suite.
+ * The file, and not the test: `process.env` belongs to the process, so a stub
+ * stands until something puts it back. `./worker.js` does that between files,
+ * beside the spy registry it clears for the same reason — a worker serves many
+ * files, and a stub that outlived its file would be a test that passes because
+ * of another one, in a suite where which files share a worker is decided by a
+ * timings file. A case that wants a narrower scope calls `unstubAllEnvs` in an
+ * `afterEach`, which is also what makes the scope visible to a reader.
  */
 export function stubEnv(name: string, value: string | void): void {
   const env = environment();
@@ -97,7 +105,11 @@ export function unstubAllEnvs(): void {
 }
 
 /**
- * Replace a global for the rest of the test.
+ * Replace a global for the rest of the file.
+ *
+ * Undone by `unstubAllGlobals`, which `./worker.js` calls between files, for
+ * the reason [`stubEnv`] above gives: `globalThis` outlives every file that
+ * writes to it.
  *
  * Whether the global was the object's own property is recorded, because putting
  * back an inherited one by assignment would leave a copy that shadows whatever
@@ -214,8 +226,8 @@ export type Uft = {
   readonly waitFor: typeof waitFor,
   readonly waitUntil: typeof waitUntil,
 
-  readonly useFakeTimers: typeof timers.useFakeTimers,
-  readonly useRealTimers: typeof timers.useRealTimers,
+  readonly useFakeTimers: typeof timers.installFakeClock,
+  readonly useRealTimers: typeof timers.restoreRealClock,
   readonly isFakeTimers: typeof timers.isFaked,
   readonly advanceTimersByTime: typeof timers.advanceTimersByTime,
   readonly advanceTimersByTimeAsync: typeof timers.advanceTimersByTimeAsync,
@@ -261,8 +273,8 @@ export const uft: Uft = Object.freeze({
 
   // The clock a test controls. A test about "after five minutes the session
   // expires" should not take five minutes.
-  useFakeTimers: timers.useFakeTimers,
-  useRealTimers: timers.useRealTimers,
+  useFakeTimers: timers.installFakeClock,
+  useRealTimers: timers.restoreRealClock,
   isFakeTimers: timers.isFaked,
   advanceTimersByTime: timers.advanceTimersByTime,
   advanceTimersByTimeAsync: timers.advanceTimersByTimeAsync,

package/internal/native-globals.js

@@ -0,0 +1,14 @@
+// @flow
+// The facade returns the outer uf worker's registry, not another test runner.
+const environment: $FlowFixMe = globalThis;
+const api = environment.__UF_NATIVE_TEST_API__;
+export const test = api.test;
+export const it = api.it;
+export const describe = api.describe;
+export const beforeAll = api.beforeAll;
+export const afterAll = api.afterAll;
+export const beforeEach = api.beforeEach;
+export const afterEach = api.afterEach;
+export const expect = api.expect;
+export const fn = api.fn;
+export const spyOn = api.spyOn;

package/internal/native-host.js

@@ -0,0 +1,97 @@
+// @flow
+// Jest's module environment executes RN's own mocks. uf still owns discovery,
+// scheduling, hooks, timeouts, isolation and the result protocol.
+
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as tests from "../index.js";
+
+// Optional, application-owned environment modules cross one dynamic boundary.
+type EnvironmentModule = $FlowFixMe;
+
+export async function loadNativeFile(file: string): Promise<() => Promise<void>> {
+  const rootDir = process.cwd();
+  const require = createRequire(path.join(rootDir, "package.json"));
+  const load = (name: string): EnvironmentModule => {
+    try {
+      return require(name);
+    } catch (cause) {
+      throw new Error(
+        `uf test (react-native): install ${name} in the application; the native environment could not load it`,
+        { cause },
+      );
+    }
+  };
+  const Runtime = load("jest-runtime").default;
+  const { readConfig } = load("jest-config");
+  const { createScriptTransformer } = load("@jest/transform");
+  const { jestExpect } = load("@jest/expect");
+  const { projectConfig: config, globalConfig } = await readConfig(
+    {
+      config: JSON.stringify({
+        rootDir,
+        preset: "@react-native/jest-preset",
+        cacheDirectory: path.join(rootDir, ".uf", "native-test-cache"),
+        moduleNameMapper: {
+          "^@uniflowed/test$": fileURLToPath(new URL("./native-globals.js", import.meta.url).href),
+        },
+        transform: {
+          "^.+\\.[jt]sx?$": require.resolve("@uniflowed/react-native/test-transformer.cjs"),
+        },
+        transformIgnorePatterns: [
+          "node_modules/(?!((jest-)?react-native|@react-native(-community)?|@react-navigation|@uniflowed|react-native-screens|react-native-safe-area-context)/)",
+        ],
+      }),
+    },
+    rootDir,
+  );
+  const context = await Runtime.createContext(config, {
+    console,
+    maxWorkers: 1,
+    watch: false,
+    watchman: false,
+  });
+  const Environment = load(config.testEnvironment);
+  const environment = new (Environment.TestEnvironment ?? Environment)(
+    { projectConfig: config, globalConfig },
+    { console, testPath: file, docblockPragmas: {} },
+  );
+  await environment.setup();
+  let runtime: EnvironmentModule = null;
+  let closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    try {
+      runtime?.leaveTestCode();
+      runtime?.teardown();
+    } finally {
+      await environment.teardown();
+    }
+  };
+  try {
+    const transformer = await createScriptTransformer(config, new Map());
+    runtime = new Runtime(
+      config,
+      environment,
+      context.resolver,
+      transformer,
+      new Map(),
+      { collectCoverage: false, collectCoverageFrom: [], coverageProvider: "v8" },
+      file,
+      globalConfig,
+    );
+    const api = { ...tests, expect: jestExpect };
+    for (const [key, value] of Object.entries(api)) environment.global[key] = value;
+    environment.global.__UF_NATIVE_TEST_API__ = api;
+    runtime.setGlobalsForRuntime(api);
+    runtime.enterTestCode();
+    for (const setup of config.setupFiles) runtime.requireModule(setup);
+    runtime.requireModule(file);
+    return close;
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}

package/internal/output.js

@@ -241,6 +241,19 @@ function writer(
  * Installed once, for the life of the worker: a worker runs many files, and
  * restoring the real methods between them would leave a window in which a
  * straggling `setTimeout` from the previous file writes into the protocol.
+ *
+ * # A page has no stream to take
+ *
+ * `uf test --browser` runs this same capture inside a page
+ * (`./browser/page.js`), and there the whole premise of the returned value is
+ * absent: there is no `process.stdout`, so there is nothing for a test to
+ * write into by accident, and the protocol's channel is a separate HTTP
+ * request rather than a stream anything else can reach. So the two `write`
+ * methods are only replaced when there are two `write` methods, and the
+ * "raw stream" handed back is a no-op nobody has a use for.
+ *
+ * Deliberately not a `typeof process` check at each use: the question is asked
+ * once, here, because the answer cannot change under a running host.
  */
 export function install(to: OutputSink): (chunk: string) => void {
   const global = host();
@@ -248,11 +261,14 @@ export function install(to: OutputSink): (chunk: string) => void {
   if (already != null) {
     return already;
   }
-  const stdout = global.process.stdout;
-  const real = stdout.write;
-  const protocol = (chunk: string) => {
-    real.call(stdout, chunk);
-  };
+  const stdout = global.process?.stdout;
+  const real = stdout?.write;
+  const protocol =
+    real == null
+      ? (_chunk: string) => {}
+      : (chunk: string) => {
+          real.call(stdout, chunk);
+        };
   raw = protocol;
   sink = to;
   for (const method of Object.keys(CONSOLE_STREAMS)) {
@@ -271,8 +287,10 @@ export function install(to: OutputSink): (chunk: string) => void {
     capture("stderr", `${userFrames(error.stack) ?? `Trace: ${error.message}`}\n`);
   };
 
-  global.process.stdout.write = writer("stdout");
-  global.process.stderr.write = writer("stderr");
+  if (global.process?.stdout != null) {
+    global.process.stdout.write = writer("stdout");
+    global.process.stderr.write = writer("stderr");
+  }
   return protocol;
 }
 

package/internal/registry.js

@@ -30,13 +30,29 @@ export type Body = () => mixed | Promise<mixed>;
 /** The suffix written on a registration call. */
 export type Modifier = "none" | "only" | "skip" | "todo";
 
-/** One registered test case. */
+/**
+ * How a benchmark runs under `uf test --bench`.
+ *
+ * `warmup` calls are made and their times thrown away, then `iterations` calls
+ * are each timed. `timeout` is the budget for one call, in milliseconds, and
+ * the benchmark as a whole is held to that budget once per call.
+ */
+export type BenchOptions = {|
+  readonly warmup?: number,
+  readonly iterations?: number,
+  readonly timeout?: number,
+|};
+
+/** One registered test case, or one benchmark. */
 export type Case = {|
-  readonly kind: "test",
+  readonly kind: "test" | "bench",
   readonly name: string,
   readonly body: Body | null,
   readonly modifier: Modifier,
+  readonly skipReason: string | null,
   readonly timeoutMs: number | null,
+  /** How to run it, for a benchmark; `null` for a test. */
+  readonly bench: BenchOptions | null,
   readonly line: number,
   readonly column: number,
 |};
@@ -123,14 +139,18 @@ function addCase(
   body: Body | null,
   modifier: Modifier,
   timeoutMs: number | null,
+  skipReason: string | null = null,
+  bench: BenchOptions | null = null,
 ): void {
   const position = callSite();
   current.children.push({
-    kind: "test",
+    kind: bench == null ? "test" : "bench",
     name,
     body,
     modifier,
+    skipReason,
     timeoutMs,
+    bench,
     line: position.line,
     column: position.column,
   });
@@ -179,6 +199,9 @@ function caseApi(): $FlowFixMe {
   api.skip = (name: string, body?: Body) => {
     addCase(name, body ?? null, "skip", null);
   };
+  api.skipBecause = (name: string, reason: string, body?: Body) => {
+    addCase(name, body ?? null, "skip", null, reason);
+  };
   api.todo = (name: string, body?: Body) => {
     addCase(name, body ?? null, "todo", null);
   };
@@ -211,6 +234,34 @@ export const it: $FlowFixMe = caseApi();
 /** `test` is `it`, for people who write it that way. */
 export const test: $FlowFixMe = it;
 
+/** The `bench` API, and its modifiers. See [`suiteApi`] for the shape. */
+function benchApi(): $FlowFixMe {
+  const api: $FlowFixMe = (name: string, body: Body, options?: BenchOptions) => {
+    addCase(name, body, "none", options?.timeout ?? null, null, options ?? {});
+  };
+  api.only = (name: string, body: Body, options?: BenchOptions) => {
+    addCase(name, body, "only", options?.timeout ?? null, null, options ?? {});
+  };
+  api.skip = (name: string, body?: Body) => {
+    addCase(name, body ?? null, "skip", null, null, {});
+  };
+  api.todo = (name: string) => {
+    addCase(name, null, "todo", null, null, {});
+  };
+  return api;
+}
+
+/**
+ * Register one benchmark.
+ *
+ * `uf test` reports a benchmark as skipped, so a suite does not pay for timing
+ * one, and `uf test --bench` runs the benchmarks in place of the tests and
+ * reports how long each call took. `bench.only`, `bench.skip` and `bench.todo`
+ * do what `it`'s do. See [`BenchOptions`] for `warmup`, `iterations` and
+ * `timeout`.
+ */
+export const bench: $FlowFixMe = benchApi();
+
 /**
  * Substitute a row into a name, the way every runner spells it: `%s` for the
  * value, `%j` for its JSON.