npm - @uniflowed/test - Versions diffs - 0.0.0-alpha.1 - Mend

@uniflowed/test 0.0.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/internal/registry.js ADDED Viewed

@@ -0,0 +1,243 @@
+// @flow
+//
+// Collecting `describe` / `it` into a tree, and running it.
+//
+// A test file registers by being imported: `describe` runs its body
+// immediately to collect children, `it` records a case. Nothing executes until
+// the runner walks the tree afterwards, which is what makes `.only` decidable
+// — a file's `.only` can appear after the tests it excludes.
+//
+// The rules, all of them the ones a person already expects:
+//
+// * `beforeEach` runs outermost-first and `afterEach` innermost-first, so a
+//   suite's set-up wraps its children's.
+// * `beforeAll` runs once before the first test in its suite that actually
+//   runs, and `afterAll` after the last one — a suite whose tests are all
+//   skipped never runs either, because there is nothing to set up for.
+// * An `afterEach` runs even when the test failed, and its own failure is
+//   reported rather than swallowed.
+// * `.only` anywhere in the file restricts the file to marked cases and their
+//   ancestors; everything else is reported skipped, never silently dropped.
+import { firstUserSite } from "./frames.js";
+/** The placeholders `it.each` substitutes a row into. */
+const ROW_TOKEN = /%[sjdi]/g;
+/** What a test or hook body may return. */
+export type Body = () => mixed | Promise<mixed>;
+/** The suffix written on a registration call. */
+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,
+|};
+/** 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,
+|};
+function suite(name: string, modifier: Modifier, line: number, column: number): Suite {
+  return {
+    kind: "suite",
+    name,
+    modifier,
+    children: [],
+    beforeAll: [],
+    afterAll: [],
+    beforeEach: [],
+    afterEach: [],
+    line,
+    column,
+  };
+}
+/** The root suite of the file currently being collected. */
+let root: Suite = suite("", "none", 0, 0);
+/** The suite `describe`/`it` calls attach to right now. */
+let current: Suite = root;
+/**
+ * Start collecting a new file, discarding anything from the last one.
+ *
+ * The worker calls this before each import, so one file's registrations can
+ * never leak into another's — which is the bug every "runner reuses a process"
+ * design has to avoid.
+ */
+export function reset(): void {
+  root = suite("", "none", 0, 0);
+  current = root;
+}
+/** The tree collected since the last [`reset`]. */
+export function collected(): Suite {
+  return root;
+}
+/**
+ * Where in the test file the call being registered was written.
+ *
+ * The stack is the only place this is available, and it is worth having: a
+ * failure that names a line is a line a person can jump to. When the stack is
+ * 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 |} {
+  return firstUserSite(new Error("position").stack) ?? { line: 0, column: 0 };
+}
+function addSuite(name: string, body: Body, modifier: Modifier): void {
+  const position = callSite();
+  const child = suite(name, modifier, position.line, position.column);
+  current.children.push(child);
+  const parent = current;
+  current = child;
+  try {
+    body();
+  } finally {
+    current = parent;
+  }
+}
+function addCase(name: string, body: Body | null, modifier: Modifier, timeoutMs: number | null): void {
+  const position = callSite();
+  current.children.push({
+    kind: "test",
+    name,
+    body,
+    modifier,
+    timeoutMs,
+    line: position.line,
+    column: position.column,
+  });
+}
+/** Options a single test may carry. */
+export type TestOptions = {| +timeout?: number |};
+/**
+ * The `describe` API, and its modifiers.
+ *
+ * The modifiers are properties on a callable, which is the shape every runner
+ * has used since Jasmine and the one a person types without thinking. They are
+ * attached inside this builder rather than assigned at the module's top level,
+ * so importing this module still only *declares* things.
+ */
+function suiteApi(): $FlowFixMe {
+  const api: $FlowFixMe = (name: string, body: Body) => {
+    addSuite(name, body, "none");
+  };
+  api.only = (name: string, body: Body) => {
+    addSuite(name, body, "only");
+  };
+  api.skip = (name: string, body: Body) => {
+    addSuite(name, body, "skip");
+  };
+  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");
+      }
+    };
+  return api;
+}
+/** The `it` API, and its modifiers. See [`suiteApi`] for the shape. */
+function caseApi(): $FlowFixMe {
+  const api: $FlowFixMe = (name: string, body: Body, options?: TestOptions) => {
+    addCase(name, body, "none", options?.timeout ?? null);
+  };
+  api.only = (name: string, body: Body, options?: TestOptions) => {
+    addCase(name, body, "only", options?.timeout ?? null);
+  };
+  api.skip = (name: string, body?: Body) => {
+    addCase(name, body ?? null, "skip", null);
+  };
+  api.todo = (name: string, body?: Body) => {
+    addCase(name, body ?? null, "todo", null);
+  };
+  api.each =
+    (table: $ReadOnlyArray<mixed>) =>
+    (name: string, body: (row: mixed) => mixed, options?: TestOptions) => {
+      for (const row of table) {
+        addCase(formatRow(name, row), () => body(row), "none", options?.timeout ?? null);
+      }
+    };
+  return api;
+}
+/**
+ * Group tests, and scope hooks to them.
+ *
+ * `describe.only`, `describe.skip` and `describe.todo` apply the modifier to
+ * everything inside; `describe.each(table)` declares one suite per row.
+ */
+export const describe: $FlowFixMe = suiteApi();
+/**
+ * Register one test.
+ *
+ * `it.only`, `it.skip` and `it.todo` do what they say; `it.each(table)` runs
+ * the body once per row, with `%s` and `%j` in the name replaced by the row.
+ */
+export const it: $FlowFixMe = caseApi();
+/** `test` is `it`, for people who write it that way. */
+export const test: $FlowFixMe = it;
+/**
+ * Substitute a row into a name, the way every runner spells it: `%s` for the
+ * value, `%j` for its JSON.
+ */
+function formatRow(name: string, row: mixed): string {
+  const values = Array.isArray(row) ? row : [row];
+  let index = 0;
+  return name.replace(ROW_TOKEN, (token) => {
+    const value = values[index];
+    index += 1;
+    return token === "%j" ? (JSON.stringify(value) ?? "undefined") : String(value);
+  });
+}
+/** Run once before the first test in this suite that runs. */
+export function beforeAll(body: Body): void {
+  current.beforeAll.push(body);
+}
+/** Run once after the last test in this suite that ran. */
+export function afterAll(body: Body): void {
+  current.afterAll.push(body);
+}
+/** Run before every test in this suite and its children. */
+export function beforeEach(body: Body): void {
+  current.beforeEach.push(body);
+}
+/** Run after every test in this suite and its children, including failures. */
+export function afterEach(body: Body): void {
+  current.afterEach.push(body);
+}

package/internal/run.js ADDED Viewed

@@ -0,0 +1,314 @@
+// @flow
+//
+// Walking a collected suite tree and executing it.
+//
+// This is the half of the runner that knows what a test *is*; the half that
+// knows about processes, scheduling and terminals is `uf_test` in Rust. The
+// split is deliberate: everything here is pure with respect to the host — it
+// takes a tree and an `emit` callback and returns nothing — so it can be
+// driven by the worker, by a unit test, or by a future host that is not
+// Node.js, without any of them re-deciding what `.only` means.
+import { AssertionError } from "./expect.js";
+import { firstUserSite, userFrames } from "./frames.js";
+import { type Body, type Case, type Suite, collected } from "./registry.js";
+/** How one case ended. */
+export type Outcome =
+  | {| +status: "passed" |}
+  | {|
+      +status: "failed",
+      +message: string,
+      +stack: string | null,
+      +expected: string | null,
+      +received: string | null,
+      /** Where the failing assertion was written, when the stack says. */
+      +site: {| +line: number, +column: number |} | null,
+    |}
+  | {| +status: "skipped", +reason: "explicit" | "not-only" | "filtered" |}
+  | {| +status: "todo" |};
+/** One finished case, as the runner reports it. */
+export type Result = {|
+  +name: string,
+  +line: number,
+  +column: number,
+  +durationMicros: number,
+  +outcome: Outcome,
+|};
+/** How a run is configured. */
+export type RunOptions = {|
+  /** Keep only cases whose full name contains this, reporting the rest skipped. */
+  +filter?: string | null,
+  /** Wall-clock budget for one case, in milliseconds. */
+  +timeoutMs?: number,
+|};
+/** Default budget for one case, matching what most runners use. */
+export const DEFAULT_TIMEOUT_MS: number = 5000;
+/** The separator between a suite's name and its child's. */
+export const NAME_SEPARATOR: string = " > ";
+function fullName(path: $ReadOnlyArray<string>): string {
+  return path.filter((part) => part !== "").join(NAME_SEPARATOR);
+}
+/**
+ * Whether the tree contains a case marked `.only`, directly or through a
+ * suite marked `.only`.
+ *
+ * `.only` is per file, and this is the question that makes it so.
+ */
+function hasOnly(node: Suite | Case, inherited: boolean): boolean {
+  const marked = inherited || node.modifier === "only";
+  if (node.kind === "test") {
+    return marked;
+  }
+  return node.children.some((child) => hasOnly(child, marked));
+}
+/**
+ * Run `body` with a wall-clock budget.
+ *
+ * A body that never settles must not hang the whole run, and there is no way
+ * to interrupt JavaScript, so the budget is a race: the run continues and the
+ * case is reported as timed out. The abandoned work may still be running,
+ * which is why the worker is torn down between files.
+ */
+async function withTimeout(body: Body, timeoutMs: number): Promise<void> {
+  let timer: TimeoutID | null = null;
+  const timeout = new Promise<empty>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    await Promise.race([Promise.resolve().then(body), timeout]);
+  } finally {
+    if (timer != null) {
+      clearTimeout(timer);
+    }
+  }
+}
+function failure(thrown: mixed): Outcome {
+  if (thrown instanceof AssertionError) {
+    const stack = userFrames(thrown.stack);
+    return {
+      status: "failed",
+      message: thrown.message,
+      stack,
+      expected: thrown.expected,
+      received: thrown.received,
+      site: firstUserSite(stack, false),
+    };
+  }
+  if (thrown instanceof Error) {
+    const stack = userFrames(thrown.stack);
+    return {
+      status: "failed",
+      message: `${thrown.name}: ${thrown.message}`,
+      stack,
+      expected: null,
+      received: null,
+      site: firstUserSite(stack, false),
+    };
+  }
+  return {
+    status: "failed",
+    message: `the test threw ${String(thrown)}`,
+    stack: null,
+    expected: null,
+    received: null,
+    site: null,
+  };
+}
+/** Everything one case needs from the suites above it. */
+type Context = {|
+  +path: $ReadOnlyArray<string>,
+  +beforeEach: $ReadOnlyArray<Body>,
+  +afterEach: $ReadOnlyArray<Body>,
+  +skipped: boolean,
+  +onlyPath: boolean,
+|};
+/**
+ * Execute one case, hooks included.
+ *
+ * `afterEach` runs even when the body failed, and a hook's own failure is
+ * reported rather than replacing the body's — the first failure wins, because
+ * it is the one that explains the rest.
+ */
+async function runCase(
+  test: Case,
+  context: Context,
+  options: RunOptions,
+  emit: (result: Result) => void,
+): Promise<boolean> {
+  const name = fullName([...context.path, test.name]);
+  const started = performance.now();
+  const report = (outcome: Outcome) => {
+    emit({
+      name,
+      line: test.line,
+      column: test.column,
+      durationMicros: Math.round((performance.now() - started) * 1000),
+      outcome,
+    });
+  };
+  if (test.modifier === "todo" || test.body == null) {
+    report({ status: "todo" });
+    return true;
+  }
+  if (context.skipped || test.modifier === "skip") {
+    report({ status: "skipped", reason: "explicit" });
+    return true;
+  }
+  if (!context.onlyPath) {
+    report({ status: "skipped", reason: "not-only" });
+    return true;
+  }
+  const filter = options.filter;
+  if (filter != null && filter !== "" && !name.includes(filter)) {
+    report({ status: "skipped", reason: "filtered" });
+    return true;
+  }
+  const timeoutMs = test.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let outcome: Outcome = { status: "passed" };
+  try {
+    for (const hook of context.beforeEach) {
+      await withTimeout(hook, timeoutMs);
+    }
+    await withTimeout(test.body, timeoutMs);
+  } catch (thrown) {
+    outcome = failure(thrown);
+  }
+  // Teardown runs whatever happened above, and only reports its own failure
+  // when the body had not already failed.
+  for (const hook of context.afterEach) {
+    try {
+      await withTimeout(hook, timeoutMs);
+    } catch (thrown) {
+      if (outcome.status === "passed") {
+        outcome = failure(thrown);
+      }
+    }
+  }
+  report(outcome);
+  return outcome.status !== "failed";
+}
+/**
+ * Walk one suite, running what it contains.
+ *
+ * Returns whether everything under it passed, which is what `bail` reads.
+ */
+async function runSuite(
+  node: Suite,
+  context: Context,
+  options: RunOptions,
+  onlyMode: boolean,
+  emit: (result: Result) => void,
+  state: {| bail: boolean |},
+): Promise<boolean> {
+  const skipped = context.skipped || node.modifier === "skip" || node.modifier === "todo";
+  const onlyPath = !onlyMode || context.onlyPath || node.modifier === "only";
+  const path = node.name === "" ? context.path : [...context.path, node.name];
+  const inner: Context = {
+    path,
+    beforeEach: [...context.beforeEach, ...node.beforeEach],
+    afterEach: [...node.afterEach, ...context.afterEach],
+    skipped,
+    onlyPath,
+  };
+  // `beforeAll` is deferred until a case in this suite actually runs, so a
+  // fully skipped suite never sets anything up. `afterAll` mirrors it.
+  let setUp = false;
+  const setUpOnce = async () => {
+    if (setUp) {
+      return;
+    }
+    setUp = true;
+    for (const hook of node.beforeAll) {
+      await withTimeout(hook, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    }
+  };
+  let passed = true;
+  for (const child of node.children) {
+    if (state.bail) {
+      break;
+    }
+    if (child.kind === "test") {
+      const willRun =
+        !inner.skipped &&
+        child.modifier !== "skip" &&
+        child.modifier !== "todo" &&
+        child.body != null &&
+        (!onlyMode || inner.onlyPath || child.modifier === "only");
+      if (willRun) {
+        try {
+          await setUpOnce();
+        } catch (thrown) {
+          // A failed `beforeAll` fails the cases it was setting up for, named
+          // as such: reporting the hook alone would leave the tests silent.
+          emit({
+            name: fullName([...inner.path, child.name]),
+            line: child.line,
+            column: child.column,
+            durationMicros: 0,
+            outcome: failure(thrown),
+          });
+          passed = false;
+          continue;
+        }
+      }
+      const childContext: Context = {
+        ...inner,
+        onlyPath: !onlyMode || inner.onlyPath || child.modifier === "only",
+      };
+      const ok = await runCase(child, childContext, options, emit);
+      passed = passed && ok;
+    } else {
+      const ok = await runSuite(child, inner, options, onlyMode, emit, state);
+      passed = passed && ok;
+    }
+  }
+  if (setUp) {
+    for (const hook of node.afterAll) {
+      try {
+        await withTimeout(hook, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+      } catch {
+        // A teardown failure cannot fail a test that already reported, and
+        // there is nothing left to attach it to; the file's own status carries
+        // it instead, which the worker reports.
+        passed = false;
+      }
+    }
+  }
+  return passed;
+}
+/**
+ * Run the tree collected since the last `reset`, reporting each case through
+ * `emit` as it finishes.
+ */
+export async function run(options: RunOptions, emit: (result: Result) => void): Promise<void> {
+  const root = collected();
+  const onlyMode = hasOnly(root, false);
+  const context: Context = {
+    path: [],
+    beforeEach: [],
+    afterEach: [],
+    skipped: false,
+    onlyPath: !onlyMode,
+  };
+  await runSuite(root, context, options, onlyMode, emit, { bail: false });
+}

package/package.json ADDED Viewed

@@ -0,0 +1,23 @@
+{
+  "name": "@uniflowed/test",
+  "version": "0.0.0-alpha.1",
+  "description": "The test API and worker for `uf test`: describe/it, a full matcher set, and the process uf fans test files out to.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/test"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./worker": "./worker.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "worker.js",
+    "internal"
+  ]
+}

package/worker.js ADDED Viewed

@@ -0,0 +1,132 @@
+// @flow
+//
+// The process `uf test` fans work out to.
+//
+// One worker per core, each running whole files one at a time: `uf` writes a
+// request per line on stdin, the worker imports that file (through the host's
+// Flow loader, so the module is transformed by the same `uf transform` the
+// build uses), runs what it registered, and writes one event per line back.
+//
+//   → {"file": "src/math.test.js", "filter": "adds", "timeoutMs": 5000}
+//   ← {"event": "test", "name": "math > adds", "status": "passed", …}
+//   ← {"event": "file", "status": "completed", "durationMicros": 1234}
+//
+// Two decisions worth stating. Results are streamed as they happen rather than
+// batched at the end, so `uf test` can draw progress and `--bail` can stop a
+// long run early. And a file that throws while being *imported* is a file
+// result, not a test result: there were no tests to fail, and saying "0 tests"
+// for a module that could not load would be a lie.
+//
+// This module runs on import by design — it is a process entry point, the way
+// `@uniflowed/vite`'s loaders are.
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+import { reset } from "./internal/registry.js";
+import { run } from "./internal/run.js";
+/** What `uf` sends for one file. */
+type Request = {|
+  +file: string,
+  +filter?: string | null,
+  +timeoutMs?: number,
+|};
+function write(event: { +[string]: mixed }): void {
+  process.stdout.write(`${JSON.stringify(event)}\n`);
+}
+/**
+ * Import and run one file.
+ *
+ * The module is imported with a cache-busting query so a watch-mode rerun in
+ * the same worker sees the edited file rather than the one the module registry
+ * already holds.
+ */
+async function runFile(request: Request, generation: number): Promise<void> {
+  const started = performance.now();
+  reset();
+  try {
+    await import(`${pathToFileURL(request.file).href}?uf-run=${generation}`);
+  } catch (thrown) {
+    const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+    write({
+      event: "file",
+      status: "load-failed",
+      message: `${error.name}: ${error.message}`,
+      stack: error.stack ?? null,
+      durationMicros: Math.round((performance.now() - started) * 1000),
+    });
+    return;
+  }
+  try {
+    await run({ filter: request.filter ?? null, timeoutMs: request.timeoutMs }, (result) => {
+      write({ event: "test", ...result.outcome, name: result.name, line: result.line, column: result.column, durationMicros: result.durationMicros });
+    });
+    write({
+      event: "file",
+      status: "completed",
+      durationMicros: Math.round((performance.now() - started) * 1000),
+    });
+  } catch (thrown) {
+    const error = thrown instanceof Error ? thrown : new Error(String(thrown));
+    write({
+      event: "file",
+      status: "run-failed",
+      message: `${error.name}: ${error.message}`,
+      stack: error.stack ?? null,
+      durationMicros: Math.round((performance.now() - started) * 1000),
+    });
+  }
+}
+/**
+ * Serve requests until stdin closes.
+ *
+ * Requests are queued and served strictly in order: a worker runs one file at
+ * a time, because two files sharing a process would share globals and module
+ * state, and a test suite that passes alone but fails beside another is the
+ * worst failure a runner can produce.
+ */
+function serve(): void {
+  let queue: Promise<void> = Promise.resolve();
+  let generation = 0;
+  createInterface({ input: process.stdin }).on("line", (line) => {
+    if (line.trim() === "") {
+      return;
+    }
+    let request: Request;
+    try {
+      request = JSON.parse(line);
+    } catch (error) {
+      write({ event: "file", status: "run-failed", message: `malformed request: ${String(error)}` });
+      return;
+    }
+    generation += 1;
+    const at = generation;
+    queue = queue.then(() => runFile(request, at));
+  });
+  process.stdin.on("close", () => {
+    queue.then(() => process.exit(0));
+  });
+}
+// Unhandled rejections would otherwise take the worker down mid-file with no
+// explanation; reporting one as a file failure keeps the run honest.
+process.on("unhandledRejection", (reason: mixed) => {
+  const error = reason instanceof Error ? reason : new Error(String(reason));
+  write({
+    event: "file",
+    status: "run-failed",
+    message: `unhandled rejection: ${error.message}`,
+    stack: error.stack ?? null,
+  });
+  process.exit(1);
+});
+serve();