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

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

@@ -21,25 +21,58 @@
 // # Why this is its own module
 //
 // Two callers need it and neither owns it: `worker.js` installs the capture at
-// start-up, and `run.js` says which case is running so a chunk can be named.
-// "Who printed this" is also state with a lifetime of its own — set around a
-// case's body and hooks, cleared between them — exactly like the snapshot key
-// in `snapshot.js`, and for the same reason it lives beside the thing it
-// describes rather than inside either caller.
+// start-up, and `run.js` runs each case inside the ownership kept here, so a
+// chunk can be named. "Who printed this" is also state with a lifetime of its
+// own — one case's hooks and body — exactly like the snapshot key in
+// `snapshot.js`, and for the same reason it lives beside the thing it describes
+// rather than inside either caller.
 //
 // # What "the test that printed it" means
 //
-// The name a chunk carries is the case the *worker* is running when the chunk
-// arrives, which is not the same as the case whose code produced it. A
-// `setTimeout` a test leaves behind prints while the next case is running and
-// is filed under that one; a chunk from no case at all is filed under the
-// file.
+// The case whose *asynchronous context* the write happened in, which is the
+// case whose code produced it.
 //
-// Getting this exactly right needs the printing to be tied to the asynchronous
-// context the case ran in — `AsyncLocalStorage` and everything under it — and
-// that is a bigger change than this module, because it has to reach the
-// scheduler that runs the cases. It is written down here rather than left to
-// be discovered from a confusing report. See ubugeeei-prod/uf#207.
+// The obvious answer was a module-level variable the runner set before a case
+// and cleared after it, and it was wrong in one shape that matters: the name a
+// chunk carried was whatever the worker happened to be running when the chunk
+// arrived. A `setTimeout` a test left behind fires while the *next* case is
+// running, so the line it printed was reported under that next case — a test
+// accused of printing something it never printed, which is worse than not
+// naming it at all, because a reader chasing the message finds it under code
+// that does not contain it. See ubugeeei-prod/uf#207.
+//
+// So the owner is an `AsyncLocalStorage`, and what `run.js` calls is
+// `runInTest` rather than an `enterTest` / `exitTest` pair: the store is only
+// carried by work started *inside* the case, so the case's setup, body and
+// teardown have to run within it. Everything they schedule inherits it,
+// whenever it eventually runs.
+//
+// # When there is no owner
+//
+// `getStore()` answers nothing outside a case, and a chunk with no owner is
+// filed under the file — which is right for an import, a `beforeAll`, or a
+// straggler from a case that is long gone.
+//
+// It is also the answer on a host whose storage does not reach the callback.
+// Deno 1.31 has `AsyncLocalStorage` and propagates it across `await`, but not
+// through `setTimeout`, so a detached callback there is filed under the file
+// rather than under the case that scheduled it. That degradation is the point:
+// of the two ways to be less than exact, naming the file says less, and naming
+// the next case says something false.
+//
+// `node:async_hooks` itself is not guarded for, because a guard could not run.
+// Node, Deno and Bun all provide it under the `node:` specifier, and a host
+// that had no `node:` builtins could not start this worker at all — `node:util`
+// is imported below, `node:readline` and `node:url` by `worker.js`. A `typeof`
+// check around the constructor would only ever execute on a host where this
+// module had already linked.
+//
+// The one thing this does not answer is a straggler that outlives its *file*:
+// the worker runs the next file in the same process, and a chunk still carrying
+// a name from the file before is a name the next file's report has no test for.
+// The host files it under the file it arrived in, which is honest but not
+// exact, and closing it properly needs the file's generation in the protocol.
+// That is ubugeeei-prod/uf#203, and it is not this module's to fix.
 
 // # Bounds
 //
@@ -49,6 +82,7 @@
 // nothing after it is kept. The budget starts over for each file, so a chatty
 // file does not silence the next one in the same worker.
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { format, inspect } from "node:util";
 
 import { userFrames } from "./frames.js";
@@ -95,9 +129,16 @@ const DECODER = new TextDecoder();
 /** What a stream's `write` calls when it has taken the chunk. */
 type WriteCallback = () => mixed;
 
+/**
+ * The case a write belongs to, kept in the asynchronous context it ran in.
+ *
+ * Full names rather than a record, because that is the whole of what a chunk
+ * needs to say and the protocol carries it as a string either way.
+ */
+const owner: AsyncLocalStorage<string> = new AsyncLocalStorage();
+
 let sink: OutputSink | null = null;
 let raw: ((chunk: string) => void) | null = null;
-let current: string | null = null;
 let captured = 0;
 let stopped = false;
 
@@ -159,7 +200,7 @@ function capture(stream: OutputStream, text: string): void {
     stopped = true;
   }
   captured += kept.length;
-  to({ stream, test: current, text: kept });
+  to({ stream, test: owner.getStore() ?? null, text: kept });
 }
 
 /** A stand-in for `process.stdout.write` / `process.stderr.write`. */
@@ -200,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();
@@ -207,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)) {
@@ -230,31 +287,41 @@ 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;
 }
 
 /**
- * Say which case is running, so what it prints can be named.
+ * Run `body` as `name`, so what it prints — and what it leaves behind to print
+ * later — is filed under that case.
+ *
+ * The runner wraps one case's `beforeEach`, body and `afterEach` in a single
+ * call, because those are the one case's work. Whatever `body` returns is
+ * returned unchanged, so an `await` on this is an `await` on the case.
  *
- * The runner calls this around a case's body and hooks and clears it between
- * them: output written while the module is being imported, from a `beforeAll`,
- * or after the last case finished belongs to the file, not to whichever case
- * happened to run last.
+ * Nothing here needs an "and now nothing is running" counterpart. Output from
+ * an import, a `beforeAll` or a case that has already been reported was never
+ * inside this call, so it has no owner and is the file's — which is the
+ * property the previous module-level variable had to be reset to keep, and
+ * kept only for as long as nothing straggled.
  */
-export function enterTest(name: string): void {
-  current = name;
+export function runInTest<T>(name: string, body: () => T): T {
+  return owner.run(name, body);
 }
 
-/** Say that no case is running. */
-export function exitTest(): void {
-  current = null;
-}
-
-/** Start one file's output budget over, with no case running. */
+/**
+ * Start one file's output budget over.
+ *
+ * Only the budget: there is no current case to clear, because a case's
+ * ownership lives in the callbacks it started rather than in this module. A
+ * straggler from the file before still carries the name it was written under,
+ * which the host cannot match to a test of the new file and files under that
+ * file instead. See ubugeeei-prod/uf#203.
+ */
 export function startFile(): void {
   captured = 0;
   stopped = false;
-  current = null;
 }

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.