@uniflowed/test 0.0.0-alpha.9 → 0.2.0

package/internal/frames.js

@@ -195,3 +195,181 @@ export function userFrames(stack: string | null | void): string | null {
   const frames = lines.slice(1).filter((frame) => !isInternalFrame(frame));
   return frames.length === 0 ? head : [head, ...frames].join("\n");
 }
+
+/**
+ * A V8 call site, as much of it as [`callerSite`] reads.
+ *
+ * Written out rather than imported: there is no library definition for V8's
+ * structured stack API, and these four methods are all it asks of one.
+ */
+type CallSite = interface {
+  getFileName(): ?string,
+  getLineNumber(): ?number,
+  getColumnNumber(): ?number,
+};
+
+/** The piece of `node:module`'s source-map API [`callerSite`] needs. */
+type SourceMapEntry = {|
+  readonly originalLine?: number,
+  readonly originalColumn?: number,
+  readonly originalSource?: string,
+|};
+type FindSourceMap = (
+  file: string,
+) => ?interface { findEntry(line: number, column: number): SourceMapEntry };
+
+/**
+ * `node:module`'s `findSourceMap` when the host is Node with source maps on;
+ * `false` when the structured path must not be taken; `undefined` until asked.
+ *
+ * Asked once per process: the host does not change under a running worker.
+ */
+let nodeSourceMaps: FindSourceMap | false | void;
+
+/**
+ * How to map a generated position the way Node's own stack traces do, or
+ * `false` when this host's stacks cannot be reproduced from call sites.
+ *
+ * Node only. Bun and Deno implement the call-site API too, but whether their
+ * call sites carry the generated position or the mapped one is theirs to
+ * decide and has changed between releases, so they keep the string path,
+ * whose answer is by construction the one their `.stack` prints. A browser
+ * has no `process` at all.
+ */
+function sourceMapsForCallSites(): FindSourceMap | false {
+  if (nodeSourceMaps !== undefined) {
+    return nodeSourceMaps;
+  }
+  const host: $FlowFixMe = globalThis;
+  const process = host.process;
+  const isNode =
+    typeof process?.versions?.node === "string" &&
+    process.versions.bun == null &&
+    host.Deno == null &&
+    typeof process.getBuiltinModule === "function" &&
+    typeof Error.captureStackTrace === "function";
+  if (!isNode) {
+    nodeSourceMaps = false;
+    return false;
+  }
+  const findSourceMap = process.getBuiltinModule("node:module")?.findSourceMap;
+  nodeSourceMaps =
+    typeof findSourceMap === "function"
+      ? // Only while Node applies source maps to its own stacks: with them off
+        // a `.stack` prints the generated position, and so must this.
+        (file) => (process.sourceMapsEnabled === true ? findSourceMap(file) : null)
+      : false;
+  return nodeSourceMaps;
+}
+
+/**
+ * The first position outside the runner on the stack of the call to `skip`,
+ * as `firstUserSite(new Error().stack)` would read it — or `undefined` when
+ * this host cannot answer that way, and the caller should build the string.
+ *
+ * # Why not simply read `.stack`
+ *
+ * Because it is the most expensive line in registering a test. `describe` and
+ * `it` ask where they were called from, once per case, and on Node with
+ * `--enable-source-maps` — which every `uf test` worker runs with — the string
+ * `.stack` is built by mapping *every* frame through its module's source map
+ * and printing each one, to read back one line and column from the first that
+ * is not the runner's. On a suite of 50 files and 1,000 cases that was about a
+ * sixth of a worker's CPU.
+ *
+ * V8 hands the same frames over unprinted to a `prepareStackTrace` installed
+ * for the one capture, and only the frame the answer comes from is mapped,
+ * with the lookup Node's printer itself uses — `findSourceMap(file)` then
+ * `findEntry(line - 1, column - 1)`, falling back to the generated position
+ * when there is no map or no entry — so the number is the one the string would
+ * have carried. `packages/test/registration-site.test.js` holds the two paths
+ * to that.
+ */
+export function callerSite(skip: (...args: $ReadOnlyArray<empty>) => mixed): Site | null | void {
+  const findSourceMap = sourceMapsForCallSites();
+  if (findSourceMap === false) {
+    return undefined;
+  }
+  const errors: $FlowFixMe = Error;
+  const limit: mixed = errors.stackTraceLimit;
+  const full = typeof limit === "number" ? limit : 0;
+  // A few frames first. The caller of a registration is two or three frames
+  // above it — `it`, the modifier or `each` wrapper, `addCase` — and V8's cost
+  // is per frame it materialises, so the whole default ten is walked only for
+  // the rare caller that is deeper than that.
+  const shallow = Math.min(full, SHALLOW_FRAMES);
+  const first = readCallSites(skip, shallow);
+  if (first === undefined) {
+    return undefined;
+  }
+  const found = firstUserCallSite(first, findSourceMap);
+  if (found != null || first.length < shallow || shallow === full) {
+    return found;
+  }
+  const again = readCallSites(skip, full);
+  return again === undefined ? undefined : firstUserCallSite(again, findSourceMap);
+}
+
+/** How many frames [`callerSite`] asks for before it asks for all of them. */
+const SHALLOW_FRAMES = 4;
+
+/** Hands V8's call sites back unprinted; one function, so none is made per capture. */
+function unprinted(_error: mixed, sites: $ReadOnlyArray<CallSite>): $ReadOnlyArray<CallSite> {
+  return sites;
+}
+
+/**
+ * Up to `limit` call sites above `skip`, or `undefined` when the host does not
+ * hand them over.
+ */
+function readCallSites(
+  skip: (...args: $ReadOnlyArray<empty>) => mixed,
+  limit: number,
+): $ReadOnlyArray<CallSite> | void {
+  const errors: $FlowFixMe = Error;
+  const prepare = errors.prepareStackTrace;
+  const before = errors.stackTraceLimit;
+  const holder: $FlowFixMe = {};
+  try {
+    errors.prepareStackTrace = unprinted;
+    errors.stackTraceLimit = limit;
+    errors.captureStackTrace(holder, skip);
+    // Read inside the `try`: V8 formats `stack` lazily, on first access, and
+    // with whatever `prepareStackTrace` is installed *then*. What comes back is
+    // what `unprinted` returned, which V8 does not type.
+    const sites: $FlowFixMe = holder.stack;
+    return Array.isArray(sites) ? sites : undefined;
+  } finally {
+    errors.prepareStackTrace = prepare;
+    errors.stackTraceLimit = before;
+  }
+}
+
+/** The first of `sites` outside the runner, mapped as Node maps a printed frame. */
+function firstUserCallSite(
+  sites: $ReadOnlyArray<CallSite>,
+  findSourceMap: FindSourceMap,
+): Site | null {
+  for (const site of sites) {
+    const file = site.getFileName();
+    if (file == null || isInternalFrame(file)) {
+      continue;
+    }
+    const line = site.getLineNumber();
+    const column = site.getColumnNumber();
+    if (line == null || column == null) {
+      continue;
+    }
+    const entry = findSourceMap(file)?.findEntry(line - 1, column - 1);
+    if (
+      entry?.originalSource != null &&
+      entry.originalSource !== "" &&
+      entry.originalLine != null &&
+      entry.originalColumn != null
+    ) {
+      return { line: entry.originalLine + 1, column: entry.originalColumn + 1 };
+    }
+    return { line, column };
+  }
+  return null;
+}

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;
 }