@uniflowed/test 0.9.0 → 0.11.0

package/browser-worker.js

@@ -48,7 +48,7 @@ import path from "node:path";
 import { inSourceTests, sharedService } from "@uniflowed/host/transform";
 
 import { create } from "./internal/browser/server.js";
-import { connectPipe } from "./internal/browser/cdp.js";
+import { type PipeController, connectPipe } from "./internal/browser/cdp.js";
 
 /** What `uf` sends for one file. */
 type Request = {|
@@ -162,7 +162,7 @@ async function main(): Promise<void> {
   const browser = process.env.UF_BROWSER;
   const service = sharedService(root);
 
-  let controller = null;
+  let controller: PipeController | null = null;
   const server = await create({
     root,
     browserCommand: async (id, method, args) => {
@@ -170,7 +170,7 @@ async function main(): Promise<void> {
       return controller.command(id, method, args);
     },
     transform: async (id, code) => {
-      // The same three the Node loader passes (`packages/host/internal/
+      // The same three the Node loader passes (`npm/host/internal/
       // node-hooks.js`), so a module means the same thing on both hosts.
       // `inSourceTests` is the one that would be easy to forget and expensive
       // to: without it `import.meta.uf.test` compiles to `void 0`, every

package/index.js

@@ -52,8 +52,8 @@ export { fn, spyOn } from "./internal/spy.js";
  * 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: `@uniflowed/testing` re-exports both this
- * package and `@uniflowed/react-testing`, and both have a `waitFor`.
+ * are generic enough to collide with `@uniflowed/react-testing`, which
+ * also exports a `waitFor`.
  */
 export { UnsupportedError, uft } from "./internal/namespace.js";
 

package/internal/asymmetric.js

@@ -21,6 +21,7 @@
 // the time any matcher runs, both modules have finished evaluating — and the
 // alternative was wiring the comparison in at load, which is an import-time side
 // effect and the one thing every shipped module here is forbidden.
+import { callable } from "./callable.js";
 import { equals } from "./equality.js";
 
 /** The brand every matcher carries, so `equals` can recognise one. */
@@ -91,8 +92,10 @@ export function any(constructor: mixed): AsymmetricMatcher {
         // one means — not "has Object.prototype in its chain", which a
         // null-prototype object would fail and a test would find baffling.
         return received != null && (typeof received === "object" || typeof received === "function");
-      default:
-        return typeof constructor === "function" && received instanceof constructor;
+      default: {
+        const type = callable(constructor);
+        return type != null && received instanceof type;
+      }
     }
   });
 }

package/internal/browser/cdp.js

@@ -24,6 +24,15 @@ export type BrowserTransport = {|
   ) => Promise<WireValue>,
   readonly close: () => Promise<void>,
 |};
+/** The page commands `connectPipe` answers over one browser connection. */
+export type PipeController = {|
+  readonly command: (
+    id: string | null,
+    method: string,
+    args?: $ReadOnlyArray<WireValue>,
+  ) => Promise<WireValue>,
+  readonly closePages: () => Promise<void>,
+|};
 type Pending = {|
   timer: TimeoutID,
   resolve: (value: WireValue) => void,
@@ -31,7 +40,7 @@ type Pending = {|
 |};
 
 /** CDP over the private pipe: closing the test worker also closes Chromium. */
-export function connectPipe(child: $FlowFixMe, options: ControlOptions = {}) {
+export function connectPipe(child: $FlowFixMe, options: ControlOptions = {}): PipeController {
   let sequence = 0;
   let buffered = "";
   let closed = false;

package/internal/browser/page.js

@@ -123,6 +123,9 @@ async function runFile(request: PageRequest): Promise<void> {
   const uninstall = installInSourceTests(url);
   try {
     try {
+      // The test file the runner found, served by the dev server; Flow types
+      // only a literal specifier, and nothing is read from its namespace.
+      // $FlowFixMe[unsupported-syntax]
       await import(url);
     } catch (thrown) {
       const error = asError(thrown);

package/internal/browser/screenshots.js

@@ -10,12 +10,19 @@ export type ScreenshotOptions = {|
   readonly threshold?: number,
 |};
 
+/** A screenshot that matched its baseline, or was recorded as the new one. */
+export type ScreenshotResult = {|
+  readonly baseline: string,
+  readonly updated: boolean,
+  readonly differentPixels: number,
+|};
+
 /** Baselines stay under the project's configured directory, including through symlinks. */
 export async function compareScreenshot(
   data: string,
   name: string,
   options: ScreenshotOptions = {},
-) {
+): Promise<ScreenshotResult> {
   if (
     typeof name !== "string" ||
     !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}$/.test(name) ||
@@ -23,9 +30,9 @@ export async function compareScreenshot(
     /\.(actual|diff)$/.test(name)
   )
     throw new Error("screenshot name must be a simple file name without traversal");
-  const config = JSON.parse(process.env.UF_VRT_CONFIG ?? "{}");
+  const vrt = JSON.parse(process.env.UF_VRT_CONFIG ?? "{}");
   const root = await realpath(options.root ?? process.env.UF_PROJECT_ROOT ?? process.cwd());
-  const directory = path.resolve(root, options.baselines ?? config.baselines ?? "__uf_vrt__");
+  const directory = path.resolve(root, options.baselines ?? vrt.baselines ?? "__uf_vrt__");
   if (!directory.startsWith(root + path.sep))
     throw new Error("vrt.baselines must stay inside the test project");
   // Check each existing ancestor before creating anything through it.
@@ -49,7 +56,7 @@ export async function compareScreenshot(
   }
   const bytes = Buffer.from(data, "base64");
   const actual = PNG.sync.read(bytes);
-  const threshold = options.threshold ?? config.threshold ?? 0;
+  const threshold = options.threshold ?? vrt.threshold ?? 0;
   if (!Number.isInteger(threshold) || threshold < 0)
     throw new Error("vrt.threshold is the maximum number of different pixels");
   if (process.env.UF_UPDATE_SNAPSHOTS === "1") {

package/internal/browser/server.js

@@ -124,7 +124,7 @@ export type PageRequest = {|
 /** How `create` is configured. */
 export type ServerOptions = {|
   readonly browserCommand?: (
-    id: mixed,
+    id: string | null,
     method: string,
     args: $ReadOnlyArray<mixed>,
   ) => Promise<mixed>,
@@ -226,6 +226,7 @@ export async function create(options: ServerOptions): Promise<ModuleServer> {
           try {
             const { id, method, args } = JSON.parse(body);
             if (
+              (id !== null && typeof id !== "string") ||
               typeof method !== "string" ||
               !Array.isArray(args) ||
               options.browserCommand == null
@@ -279,7 +280,7 @@ export async function create(options: ServerOptions): Promise<ModuleServer> {
     server.listen(0, "127.0.0.1", resolve);
   });
   const address = server.address();
-  const port = address != null && typeof address === "object" ? address.port : 0;
+  const port: number = address != null && typeof address === "object" ? address.port : 0;
 
   return {
     url: `http://127.0.0.1:${String(port)}${PAGE_PATH}`,

package/internal/callable.js

@@ -0,0 +1,28 @@
+// @flow
+//
+// Internal to `@uniflowed/test`: a value that is a function, as one to call.
+//
+// A test hands this package values whose types it cannot know: the subject of
+// `expect(() => ...).toThrow()`, the implementation given to `fn(body)`, the
+// constructor in `expect.any(Date)`. Each is checked with `typeof` before it is
+// used, and that check is all JavaScript offers. Flow reads `typeof value ===
+// "function"` as a function whose parameters are unknown, which it will not
+// call, construct with or put on the right of `instanceof`.
+//
+// So this is the one place that turns such a value into something callable:
+// the run-time check and the single suppression that stands for it live
+// together, rather than an `any` at every call site.
+
+/** A function of unknown signature: it accepts any `this` and arguments. */
+export type Callable = (this: mixed, ...args: $ReadOnlyArray<mixed>) => mixed;
+
+/** `value` as a function to call, or `null` when it is not a function. */
+export function callable(value: mixed): Callable | null {
+  if (typeof value !== "function") {
+    return null;
+  }
+  // Checked just above, which is as far as JavaScript can check a function;
+  // Flow has no type for "a function with unknown parameters" that it calls.
+  // $FlowFixMe[incompatible-type]
+  return value;
+}

package/internal/equality.js

@@ -19,6 +19,7 @@
 //   which is the one place the two matchers differ besides prototypes.
 
 import { isAsymmetric, matchesAsymmetric } from "./asymmetric.js";
+import { callable } from "./callable.js";
 
 /** How strictly two values are compared. */
 export type Strictness = "loose" | "strict";
@@ -39,8 +40,16 @@ function isObject(value: mixed): value is interface {} {
   return typeof value === "object" && value !== null;
 }
 
+/**
+ * `Object.prototype.toString`, read through its descriptor: Flow refuses the
+ * method as a value, and `call` needs it as one to read any value's tag.
+ */
+const objectToString = callable(
+  Reflect.getOwnPropertyDescriptor(Object.prototype, "toString")?.value,
+);
+
 function tag(value: mixed): string {
-  return Object.prototype.toString.call(value);
+  return String(objectToString?.call(value));
 }
 
 /**

package/internal/expect.js

@@ -71,6 +71,7 @@ import type { SpyCall } from "./spy.js";
 import * as asymmetric from "./asymmetric.js";
 import * as snapshot from "./snapshot.js";
 import { auditElement, describeViolations, violationIds } from "./axe.js";
+import { callable } from "./callable.js";
 import { isSpy } from "./spy.js";
 import { equals, matchesObject, render } from "./equality.js";
 
@@ -486,11 +487,10 @@ function verdicts(received: mixed): {
         name,
       );
     },
-    toSatisfy: (predicate: mixed) =>
-      simple(
-        typeof predicate === "function" && predicate(received) === true,
-        "to satisfy the predicate",
-      ),
+    toSatisfy: (predicate: mixed) => {
+      const check = callable(predicate);
+      return simple(check != null && check(received) === true, "to satisfy the predicate");
+    },
     toMatchSnapshot: (hint?: mixed): Verdict => {
       const verdict = snapshot.matchSnapshot(
         received,
@@ -531,13 +531,14 @@ function verdicts(received: mixed): {
     },
     toThrow: (...rest: $ReadOnlyArray<mixed>) => {
       const expected = rest[0];
-      if (typeof received !== "function") {
+      const run = callable(received);
+      if (run == null) {
         return simple(false, "to be a function, so it could be called");
       }
       let thrown: mixed;
       let threw = false;
       try {
-        received();
+        run();
       } catch (error) {
         threw = true;
         thrown = error;
@@ -752,7 +753,7 @@ function verdicts(received: mixed): {
  *
  * # Why this is not the walk in `react-testing`
  *
- * `packages/react-testing/internal/queries.js` has one that looks like this
+ * `npm/react-testing/internal/queries.js` has one that looks like this
  * and answers a different question. `exposed` asks whether the accessibility
  * tree announces the element, so it ignores `opacity: 0` — a screen reader
  * reads text at zero opacity, which is exactly why hiding text that way is a

package/internal/frames.js

@@ -29,9 +29,9 @@ export type Site = {| readonly line: number, readonly column: number |};
  * report is concerned.
  */
 const INTERNAL_MARKERS = [
-  "/packages/test/internal/",
-  "/packages/test/worker.js",
-  "/packages/react-testing/",
+  "/npm/test/internal/",
+  "/npm/test/worker.js",
+  "/npm/react-testing/",
   "/@uniflowed/test/",
   "/@uniflowed/react-testing/",
   "node:internal/",
@@ -290,7 +290,7 @@ function sourceMapsForCallSites(): FindSourceMap | false {
  * 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
+ * have carried. `npm/test/registration-site.test.js` holds the two paths
  * to that.
  */
 export function callerSite(skip: (...args: $ReadOnlyArray<empty>) => mixed): Site | null | void {

package/internal/modules.js

@@ -287,6 +287,9 @@ function isPathSpecifier(specifier: string): boolean {
 
 /** `import()`, in one place, so the marker parameter is never spelled twice. */
 function importURL<Module>(url: string): Promise<Module> {
+  // The URL is a module the test asked to mock or load, known only at run
+  // time; Flow types only a literal specifier.
+  // $FlowFixMe[unsupported-syntax]
   return import(url) as $FlowFixMe;
 }
 
@@ -419,11 +422,17 @@ function copyProperties(
  * not — replacing their methods with spies would produce something that claims
  * to be a `Date` and cannot tell the time.
  */
-function isPlainish(value: mixed): boolean {
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === null || prototype === Object.prototype || isNamespace(value);
+function isPlainish(value: interface {}): boolean {
+  const prototype: mixed = Object.getPrototypeOf(value);
+  return prototype === null || prototype === OBJECT_PROTOTYPE || isNamespace(value);
 }
 
+/**
+ * `Object.prototype`, read off a literal: Flow's library declares no static
+ * `prototype` on `Object`, and a literal's prototype is exactly that object.
+ */
+const OBJECT_PROTOTYPE: mixed = Object.getPrototypeOf({});
+
 /** Whether `value` is a module namespace object. */
 function isNamespace(value: mixed): boolean {
   return (value as $FlowFixMe)[Symbol.toStringTag] === "Module";

package/internal/namespace.js

@@ -8,8 +8,8 @@
 // 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`.
+// are generic enough to collide in a test file: this package and
+// `@uniflowed/react-testing` 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

package/internal/spy.js

@@ -36,6 +36,8 @@
 // Every spy is registered, so `uft.clearAllMocks` and its siblings can reach the
 // ones a test never held a reference to.
 
+import { callable } from "./callable.js";
+
 /** One call's arguments, as Vitest's `mock.calls` holds them. */
 export type SpyCall = $ReadOnlyArray<mixed>;
 
@@ -118,7 +120,8 @@ function makeSpy(implementation: mixed, restore: Restore, name: string): $FlowFi
             ? Reflect.construct(body as $FlowFixMe, [...args], new.target)
             : this;
       } else {
-        returned = typeof body === "function" ? body.apply(this, args) : undefined;
+        const run = callable(body);
+        returned = run != null ? run.apply(this, args) : undefined;
       }
     } catch (thrown) {
       result.type = "throw";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/test",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "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",
@@ -8,7 +8,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ubugeeei-prod/uf.git",
-    "directory": "packages/test"
+    "directory": "npm/test"
   },
   "exports": {
     ".": {
@@ -38,7 +38,7 @@
     "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/host": "0.9.0",
+    "@uniflowed/host": "0.11.0",
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"
   },

package/worker.js

@@ -242,6 +242,9 @@ async function runImportedFile(
       const { loadNativeFile } = await import("./internal/native-host.js");
       closeNative = await loadNativeFile(request.file);
     } else {
+      // The test file the runner found; Flow types only a literal specifier,
+      // and nothing is read from its namespace.
+      // $FlowFixMe[unsupported-syntax]
       await import(`${url}?uf-run=${generation}`);
     }
   } catch (thrown) {