@uniflowed/test 0.0.0-alpha.1 → 0.0.0-alpha.11

package/internal/namespace.js

@@ -0,0 +1,287 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: the `uft` namespace.
+//
+// The operations Vitest groups under `vi`, under uf's own name. The *shape* is
+// what a migration needs — `fn`, `spyOn`, `stubEnv`, `useFakeTimers` doing what
+// they do elsewhere — and borrowing another tool's brand for it would be
+// claiming something uf has not earned.
+//
+// A namespace rather than loose named exports, because several of these names
+// are generic enough to collide in a test file: `@uniflowed/testing` re-exports
+// both this package and `@uniflowed/react-testing`, and both have a `waitFor`.
+//
+// `uft` rather than `uf`, and rather than `uf.test`. A bare `uf` is the command
+// and the project, and a test file would be using the name for something much
+// smaller than everything else in the toolchain answers to. `uf.test` reads as
+// the `test` function this package also exports, which is `it` under another
+// name — two very different things one dot apart. `uft` is three characters,
+// belongs to nothing else, and is what a reader types a hundred times a file.
+//
+// `uft.mock` and the six names beside it intercept a module before it is
+// imported, which is the loader's job rather than the runner's: by the time the
+// runner sees an `import`, the module has been fetched, linked and evaluated.
+// So the mechanism is `@uniflowed/host`'s (`module-mocks.js`) and the API is
+// `./modules.js`'s, and this file only names them. A host that cannot provide
+// synchronous module hooks gets an `UnsupportedError` that says which host it
+// is and what to do instead — never a binding that silently does nothing.
+
+import {
+  importActual as importActualModule,
+  importMock as importMockModule,
+  mock as mockModule,
+  resetModules as resetModulesNow,
+  unmock as unmockModule,
+} from "./modules.js";
+import { clearAllMocks, fn, resetAllMocks, restoreAllMocks, spyOn } from "./spy.js";
+import * as timers from "./timers.js";
+import { UnsupportedError } from "./unsupported.js";
+
+// Declared in `./unsupported.js` rather than here, because `./modules.js` needs
+// it too and a class both halves of a pair reach for is a third module.
+export { UnsupportedError } from "./unsupported.js";
+
+/** Environment variables `stubEnv` replaced, and what they were. */
+const stubbedEnv: Map<string, string | void> = new Map();
+
+/** Globals `stubGlobal` replaced, and what they were. */
+const stubbedGlobals: Map<string, { readonly owned: boolean, readonly value: mixed }> = new Map();
+
+/**
+ * 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.
+ */
+function environment(): { [string]: string } | null {
+  const host = globalThis as $FlowFixMe;
+  return host.process?.env ?? null;
+}
+
+/**
+ * Replace an environment variable for the rest of the test.
+ *
+ * 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.
+ */
+export function stubEnv(name: string, value: string | void): void {
+  const env = environment();
+  if (env == null) {
+    throw new UnsupportedError("stubEnv", "this host exposes no process environment");
+  }
+  if (!stubbedEnv.has(name)) {
+    stubbedEnv.set(name, Object.hasOwn(env, name) ? env[name] : undefined);
+  }
+  if (value === undefined) {
+    delete env[name];
+  } else {
+    env[name] = value;
+  }
+}
+
+/** Put every environment variable `stubEnv` replaced back. */
+export function unstubAllEnvs(): void {
+  const env = environment();
+  if (env == null) {
+    stubbedEnv.clear();
+    return;
+  }
+  for (const [name, previous] of stubbedEnv) {
+    if (previous === undefined) {
+      delete env[name];
+    } else {
+      env[name] = previous;
+    }
+  }
+  stubbedEnv.clear();
+}
+
+/**
+ * Replace a global for the rest of the test.
+ *
+ * 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
+ * it was inherited from.
+ */
+export function stubGlobal(name: string, value: mixed): void {
+  const host = globalThis as $FlowFixMe;
+  if (!stubbedGlobals.has(name)) {
+    stubbedGlobals.set(name, {
+      owned: Object.hasOwn(host, name),
+      value: host[name],
+    });
+  }
+  host[name] = value;
+}
+
+/** Put every global `stubGlobal` replaced back. */
+export function unstubAllGlobals(): void {
+  const host = globalThis as $FlowFixMe;
+  for (const [name, previous] of stubbedGlobals) {
+    if (previous.owned) {
+      host[name] = previous.value;
+    } else {
+      delete host[name];
+    }
+  }
+  stubbedGlobals.clear();
+}
+
+/** How often `waitFor` re-runs its body while it is failing. */
+const WAIT_INTERVAL_MS = 20;
+
+/** How long `waitFor` keeps trying before giving up. */
+const WAIT_TIMEOUT_MS = 1_000;
+
+/**
+ * Run `body` until it stops throwing, or the timeout passes.
+ *
+ * The last failure is what is raised, not a timeout — "expected 2, got 1" says
+ * what went wrong, and "timed out" says only that something did.
+ */
+export async function waitFor<T>(
+  body: () => T | Promise<T>,
+  options?: { readonly timeout?: number, readonly interval?: number },
+): Promise<T> {
+  const timeout = options?.timeout ?? WAIT_TIMEOUT_MS;
+  const interval = options?.interval ?? WAIT_INTERVAL_MS;
+  const deadline = Date.now() + timeout;
+  let last: mixed = null;
+
+  for (;;) {
+    try {
+      return await body();
+    } catch (thrown) {
+      last = thrown;
+    }
+    if (Date.now() >= deadline) {
+      throw last ?? new Error(`uft.waitFor: gave up after ${timeout}ms`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+}
+
+/** Run `body` until it returns something truthy, or the timeout passes. */
+export async function waitUntil(
+  body: () => mixed | Promise<mixed>,
+  options?: { readonly timeout?: number, readonly interval?: number },
+): Promise<mixed> {
+  return waitFor(async () => {
+    const value = await body();
+    if (value == null || value === false) {
+      throw new Error("uft.waitUntil: the condition is not true yet");
+    }
+    return value;
+  }, options);
+}
+
+/**
+ * Hand a value back with its mock methods visible to the type checker.
+ *
+ * Purely a type-level convenience, exactly as in Vitest: at runtime it is the
+ * identity function, and its whole job is letting a test write
+ * `uft.mocked(client.send).mockReturnValue(…)` without a cast.
+ */
+export function mocked<T>(value: T): $FlowFixMe {
+  return value;
+}
+
+/**
+ * The `uft` namespace's type.
+ *
+ * Written out member by member rather than left as one `$FlowFixMe`, because
+ * the module-mocking half of it is the half a type can genuinely check: a
+ * factory that hands back the wrong shape for the module it is standing in for
+ * is an error at the call site, and that only works if `uft` has a type at all.
+ * The members that were already typed loosely keep the types they have —
+ * `typeof` reads them from their definitions, so this list cannot drift from
+ * them.
+ */
+export type Uft = {
+  readonly fn: typeof fn,
+  readonly spyOn: typeof spyOn,
+  readonly mocked: typeof mocked,
+
+  readonly clearAllMocks: typeof clearAllMocks,
+  readonly resetAllMocks: typeof resetAllMocks,
+  readonly restoreAllMocks: typeof restoreAllMocks,
+
+  readonly stubEnv: typeof stubEnv,
+  readonly unstubAllEnvs: typeof unstubAllEnvs,
+  readonly stubGlobal: typeof stubGlobal,
+  readonly unstubAllGlobals: typeof unstubAllGlobals,
+
+  readonly waitFor: typeof waitFor,
+  readonly waitUntil: typeof waitUntil,
+
+  readonly useFakeTimers: typeof timers.useFakeTimers,
+  readonly useRealTimers: typeof timers.useRealTimers,
+  readonly isFakeTimers: typeof timers.isFaked,
+  readonly advanceTimersByTime: typeof timers.advanceTimersByTime,
+  readonly advanceTimersByTimeAsync: typeof timers.advanceTimersByTimeAsync,
+  readonly advanceTimersToNextTimer: typeof timers.advanceTimersToNextTimer,
+  readonly runAllTimers: typeof timers.runAllTimers,
+  readonly runOnlyPendingTimers: typeof timers.runOnlyPendingTimers,
+  readonly getTimerCount: typeof timers.getTimerCount,
+  readonly setSystemTime: typeof timers.setSystemTime,
+  readonly getMockedSystemTime: typeof timers.getMockedSystemTime,
+
+  readonly mock: typeof mockModule,
+  readonly doMock: typeof mockModule,
+  readonly unmock: typeof unmockModule,
+  readonly doUnmock: typeof unmockModule,
+  readonly importActual: typeof importActualModule,
+  readonly importMock: typeof importMockModule,
+  readonly resetModules: typeof resetModulesNow,
+};
+
+/**
+ * The `uft` namespace.
+ *
+ * A frozen object rather than a class: it is a namespace, nothing about it is
+ * per-instance, and freezing it means a test cannot leave a monkey-patch behind
+ * for the next one.
+ */
+export const uft: Uft = Object.freeze({
+  fn,
+  spyOn,
+  mocked,
+
+  clearAllMocks,
+  resetAllMocks,
+  restoreAllMocks,
+
+  stubEnv,
+  unstubAllEnvs,
+  stubGlobal,
+  unstubAllGlobals,
+
+  waitFor,
+  waitUntil,
+
+  // 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,
+  isFakeTimers: timers.isFaked,
+  advanceTimersByTime: timers.advanceTimersByTime,
+  advanceTimersByTimeAsync: timers.advanceTimersByTimeAsync,
+  advanceTimersToNextTimer: timers.advanceTimersToNextTimer,
+  runAllTimers: timers.runAllTimers,
+  runOnlyPendingTimers: timers.runOnlyPendingTimers,
+  getTimerCount: timers.getTimerCount,
+  setSystemTime: timers.setSystemTime,
+  getMockedSystemTime: timers.getMockedSystemTime,
+
+  // Module interception. `doMock` is `mock` and `doUnmock` is `unmock`, under
+  // the names Vitest gives the un-hoisted forms: there is one form here,
+  // because uf hoists neither, and a `doMock` that was a different function
+  // would be claiming a difference that does not exist.
+  mock: mockModule,
+  doMock: mockModule,
+  unmock: unmockModule,
+  doUnmock: unmockModule,
+  importActual: importActualModule,
+  importMock: importMockModule,
+  resetModules: resetModulesNow,
+});

package/internal/output.js

@@ -0,0 +1,309 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: what a test printed, attributed to the test
+// that printed it.
+//
+// The worker and the tests it runs share one stdout, and the worker's protocol
+// is one JSON object per line on it. A `console.log` in a test therefore wrote
+// a line into the middle of that protocol, `uf` read it as an event it could
+// not parse, and the whole file died — a green suite killed by a debugging
+// statement somebody left in.
+//
+// So the stream stops being shared. This module takes over `console` and the
+// two `write` methods a test can reach directly, turns everything written
+// through them into an ordinary protocol event, and hands the caller the real
+// `process.stdout.write` it took — the protocol keeps the raw stream, and it
+// is the only thing that has it. A test that prints something shaped exactly
+// like a protocol line is then a string inside a JSON field, which is the
+// point: the escaping is what makes the channel robust, not a filter that
+// tries to recognise the imposter.
+//
+// # 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` 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 case whose *asynchronous context* the write happened in, which is the
+// case whose code produced it.
+//
+// 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
+//
+// A test that prints in a loop must not be able to fill the pipe, the worker's
+// memory or the report, so one file's captured output is bounded and the
+// bound is announced rather than hidden: the chunk that reaches it says so and
+// 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";
+
+/** Which of the process's two streams a chunk was written to. */
+export type OutputStream = "stdout" | "stderr";
+
+/** One thing a test — or the file around it — printed. */
+export type OutputChunk = {|
+  readonly stream: OutputStream,
+  /** Full name of the case that was running, or `null` when none was. */
+  readonly test: string | null,
+  /** The text as it would have reached the terminal, newline included. */
+  readonly text: string,
+|};
+
+/** Where captured output goes. */
+export type OutputSink = (chunk: OutputChunk) => void;
+
+/**
+ * Longest single write kept, in UTF-16 code units.
+ *
+ * A test that prints a megabyte-long serialised fixture meant to print
+ * something; the first few kilobytes of it are what says what happened, and
+ * the rest is not a report's to carry.
+ */
+export const MAX_CHUNK_LENGTH: number = 8 * 1024;
+
+/** Most output kept from one file, in UTF-16 code units. */
+export const MAX_FILE_LENGTH: number = 128 * 1024;
+
+/** Which stream each replaced `console` method writes to, as Node routes them. */
+const CONSOLE_STREAMS: { readonly [string]: OutputStream } = {
+  log: "stdout",
+  info: "stdout",
+  debug: "stdout",
+  warn: "stderr",
+  error: "stderr",
+};
+
+/** Decoder for a `write` that was handed bytes rather than a string. */
+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 captured = 0;
+let stopped = false;
+
+/**
+ * The globals to patch, in one place.
+ *
+ * The one untyped expression in this module, and it is the trust boundary
+ * itself: `console` and `process.stdout` are the host's, their libdef types
+ * are read-only, and replacing them is exactly what this module is for.
+ */
+function host(): $FlowFixMe {
+  return globalThis;
+}
+
+/**
+ * `args` rendered the way `console.log` renders them.
+ *
+ * Node's console hands its arguments to `util.format`, and this is that in two
+ * cases rather than one, because `format`'s first parameter is the template:
+ * with a leading string it substitutes `%s`, `%d`, `%o` and the rest and
+ * inspects whatever is left over, and with anything else there is no template
+ * to substitute into, so every argument is inspected and the results joined
+ * with a space. Both are what Node prints.
+ */
+function formatArguments(args: $ReadOnlyArray<mixed>): string {
+  const [first, ...rest] = args;
+  if (typeof first === "string") {
+    return format(first, ...rest);
+  }
+  return args.map((value) => (typeof value === "string" ? value : inspect(value))).join(" ");
+}
+
+/** The text of one `write` argument, whether it arrived as bytes or a string. */
+function textOf(chunk: mixed): string {
+  if (typeof chunk === "string") {
+    return chunk;
+  }
+  if (chunk instanceof Uint8Array) {
+    return DECODER.decode(chunk);
+  }
+  return String(chunk);
+}
+
+/**
+ * Record one piece of output, within the file's budget.
+ *
+ * Silently doing nothing when no sink is installed is deliberate: a test that
+ * prints must never fail because of how it was run.
+ */
+function capture(stream: OutputStream, text: string): void {
+  const to = sink;
+  if (to == null || stopped || text === "") {
+    return;
+  }
+  let kept = text.length > MAX_CHUNK_LENGTH ? `${text.slice(0, MAX_CHUNK_LENGTH)}…\n` : text;
+  const room = MAX_FILE_LENGTH - captured;
+  if (kept.length >= room) {
+    kept = `${kept.slice(0, Math.max(room, 0))}\n[uf] output stopped after ${MAX_FILE_LENGTH} characters\n`;
+    stopped = true;
+  }
+  captured += kept.length;
+  to({ stream, test: owner.getStore() ?? null, text: kept });
+}
+
+/** A stand-in for `process.stdout.write` / `process.stderr.write`. */
+function writer(
+  stream: OutputStream,
+): (chunk: mixed, encoding?: string | WriteCallback, callback?: WriteCallback) => boolean {
+  return (chunk, encoding, callback) => {
+    capture(stream, textOf(chunk));
+    // `write(chunk, callback)` and `write(chunk, encoding, callback)` are both
+    // real calls, and a caller that passed a callback is waiting for it.
+    //
+    // Deferred, because the real `Writable.write` never calls back before it
+    // returns: a caller that writes and then does something on the next line
+    // has that line run first, and one whose callback ran inline would see the
+    // two in the other order. `queueMicrotask` rather than `process.nextTick`
+    // so this holds on every host uf supports.
+    const done = typeof encoding === "function" ? encoding : callback;
+    if (done != null) {
+      queueMicrotask(done);
+    }
+    // The real method returns whether the stream has room for more. Nothing is
+    // buffered here, so it always has — and a caller told otherwise would wait
+    // for a `drain` that never comes.
+    return true;
+  };
+}
+
+/**
+ * Route everything a test prints to `to` instead of to the process's streams,
+ * and return the real `process.stdout.write` that was replaced.
+ *
+ * The caller gets the raw stream because the caller is the protocol, and a
+ * protocol sharing its stream with the code it reports on is the bug this
+ * module exists for. Handing it back from here rather than letting the caller
+ * read it first is what makes "taken before anything could have replaced it"
+ * true by construction.
+ *
+ * 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.
+ */
+export function install(to: OutputSink): (chunk: string) => void {
+  const global = host();
+  const already = raw;
+  if (already != null) {
+    return already;
+  }
+  const stdout = global.process.stdout;
+  const real = stdout.write;
+  const protocol = (chunk: string) => {
+    real.call(stdout, chunk);
+  };
+  raw = protocol;
+  sink = to;
+  for (const method of Object.keys(CONSOLE_STREAMS)) {
+    const stream = CONSOLE_STREAMS[method];
+    global.console[method] = (...args: $ReadOnlyArray<mixed>) => {
+      capture(stream, `${formatArguments(args)}\n`);
+    };
+  }
+  global.console.trace = (...args: $ReadOnlyArray<mixed>) => {
+    // `console.trace` is a message *and* the stack under it, which is the
+    // whole reason to call it rather than `console.error`. `Error.stack`
+    // opens with `Trace: <message>`, so the trace Node prints is that string
+    // with this module's own frames taken off it.
+    const error = new Error(formatArguments(args));
+    error.name = "Trace";
+    capture("stderr", `${userFrames(error.stack) ?? `Trace: ${error.message}`}\n`);
+  };
+
+  global.process.stdout.write = writer("stdout");
+  global.process.stderr.write = writer("stderr");
+  return protocol;
+}
+
+/**
+ * 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.
+ *
+ * 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 runInTest<T>(name: string, body: () => T): T {
+  return owner.run(name, body);
+}
+
+/**
+ * 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;
+}

package/internal/registry.js

@@ -32,27 +32,27 @@ export type Modifier = "none" | "only" | "skip" | "todo";
 
 /** One registered test case. */
 export type Case = {|
-  +kind: "test",
-  +name: string,
-  +body: Body | null,
-  +modifier: Modifier,
-  +timeoutMs: number | null,
-  +line: number,
-  +column: number,
+  readonly kind: "test",
+  readonly name: string,
+  readonly body: Body | null,
+  readonly modifier: Modifier,
+  readonly timeoutMs: number | null,
+  readonly line: number,
+  readonly column: number,
 |};
 
 /** One `describe` and everything inside it. */
 export type Suite = {|
-  +kind: "suite",
-  +name: string,
-  +modifier: Modifier,
-  +children: Array<Suite | Case>,
-  +beforeAll: Array<Body>,
-  +afterAll: Array<Body>,
-  +beforeEach: Array<Body>,
-  +afterEach: Array<Body>,
-  +line: number,
-  +column: number,
+  readonly kind: "suite",
+  readonly name: string,
+  readonly modifier: Modifier,
+  readonly children: Array<Suite | Case>,
+  readonly beforeAll: Array<Body>,
+  readonly afterAll: Array<Body>,
+  readonly beforeEach: Array<Body>,
+  readonly afterEach: Array<Body>,
+  readonly line: number,
+  readonly column: number,
 |};
 
 function suite(name: string, modifier: Modifier, line: number, column: number): Suite {
@@ -101,7 +101,7 @@ export function collected(): Suite {
  * not in a shape we understand, the position is `0`, which every consumer
  * treats as "unknown" rather than as line one.
  */
-function callSite(): {| +line: number, +column: number |} {
+function callSite(): {| readonly line: number, readonly column: number |} {
   return firstUserSite(new Error("position").stack) ?? { line: 0, column: 0 };
 }
 
@@ -118,7 +118,12 @@ function addSuite(name: string, body: Body, modifier: Modifier): void {
   }
 }
 
-function addCase(name: string, body: Body | null, modifier: Modifier, timeoutMs: number | null): void {
+function addCase(
+  name: string,
+  body: Body | null,
+  modifier: Modifier,
+  timeoutMs: number | null,
+): void {
   const position = callSite();
   current.children.push({
     kind: "test",
@@ -132,7 +137,7 @@ function addCase(name: string, body: Body | null, modifier: Modifier, timeoutMs:
 }
 
 /** Options a single test may carry. */
-export type TestOptions = {| +timeout?: number |};
+export type TestOptions = {| readonly timeout?: number |};
 
 /**
  * The `describe` API, and its modifiers.
@@ -155,13 +160,11 @@ function suiteApi(): $FlowFixMe {
   api.todo = (name: string, body?: Body) => {
     addSuite(name, body ?? (() => {}), "todo");
   };
-  api.each =
-    (table: $ReadOnlyArray<mixed>) =>
-    (name: string, body: (row: mixed) => mixed) => {
-      for (const row of table) {
-        addSuite(formatRow(name, row), () => body(row), "none");
-      }
-    };
+  api.each = (table: $ReadOnlyArray<mixed>) => (name: string, body: (row: mixed) => mixed) => {
+    for (const row of table) {
+      addSuite(formatRow(name, row), () => body(row), "none");
+    }
+  };
   return api;
 }