react-x11 2.45.1 → 2.45.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.45.1",
+  "version": "2.45.2",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [

package/src/testing/events.js

@@ -15,6 +15,7 @@
 // async and `fireEvent` is not.
 
 import { act } from './harness.js';
+import { describeNode } from './queries.js';
 import { keysymOf, MOD, XK_RETURN } from '../keysyms.js';
 
 /** The window node that owns a drawn node (a node, or a window itself). */
@@ -22,15 +23,23 @@ function rootWindow(node) {
   return node?.isWindow ? node : (node?.root ?? null);
 }
 
+const NOT_IN_A_WINDOW =
+  'react-x11/test: the target is not inside a realized window — did you ' +
+  'await renderX11(), or has it unmounted?';
+
 /** A node's centre in **screen** coordinates, which is what injection takes. */
 export function screenPointOf(node, { dx = 0, dy = 0 } = {}) {
   const win = rootWindow(node);
-  if (!win?.window) {
-    throw new Error(
-      'react-x11/test: the target is not inside a realized window — did you ' +
-        'await renderX11(), or has it unmounted?',
-    );
+  // Asked before the rect, which neither kind of node gives up: one that
+  // has unmounted, or that something hides, keeps the rect it was last laid
+  // out at, and what is at that spot now is whatever was behind it. The hit
+  // test passes over a hidden node, and an unmounted one is in no tree, so
+  // a pointer aimed there could only reach something else, and nothing
+  // would say so.
+  if (node?.destroyed || hiddenBy(node)) {
+    throw new Error(noRectMessage(node, win));
   }
+  if (!win?.window) throw new Error(NOT_IN_A_WINDOW);
   const origin = win.window._screenOrigin ?? {
     x: win.window.x ?? 0,
     y: win.window.y ?? 0,
@@ -44,10 +53,7 @@ export function screenPointOf(node, { dx = 0, dy = 0 } = {}) {
   }
   const abs = node.abs;
   if (!abs || (abs.width === 0 && abs.height === 0)) {
-    throw new Error(
-      `react-x11/test: <${node.kind}> has no laid-out rect yet. Layout runs ` +
-        'on the frame clock, so `await act()` before pointing at it.',
-    );
+    throw new Error(noRectMessage(node, win));
   }
   return {
     x: Math.round(origin.x + abs.x + abs.width / 2 + dx),
@@ -56,8 +62,101 @@ export function screenPointOf(node, { dx = 0, dy = 0 } = {}) {
   };
 }
 
+/**
+ * Why a node has no rect to aim at, worded as what to do about it. Only one
+ * answer is a matter of waiting, and its advice, `await act()`, is wrong for
+ * every other: no frame gives a size to a node that layout has already
+ * placed at 0×0. Asked in this order:
+ *
+ * - it has unmounted;
+ * - it is hidden: by its own `display: 'none'` or an ancestor's, by React,
+ *   or in a window kept unmapped by `hidden` or by React. That comes before
+ *   asking whether layout reached it, because a `<box>` with
+ *   `display: 'none'` never places its children at all.
+ *
+ *   These first two are asked whatever the node's rect: `screenPointOf`
+ *   comes here for them before it looks, since the rect such a node keeps
+ *   is where it was, not where anything is;
+ * - it has no box of its own: a span, an SVG shape;
+ * - layout has not placed it yet (`_placed`), or the window owes a pass
+ *   (`needsLayout`) that may still give it a size. A pending frame is no
+ *   witness: a paced window holds one with nothing scheduled;
+ * - layout placed it, at 0×0.
+ */
+function noRectMessage(node, win) {
+  const name = describeNode(node);
+  if (node.destroyed) {
+    return (
+      `react-x11/test: ${name} has unmounted, so it is nowhere on screen to ` +
+      'point at. If something replaced it, query for that instead.'
+    );
+  }
+  const hider = hiddenBy(node);
+  if (hider) {
+    const self = hider === node;
+    const has = self ? 'has' : 'which has';
+    const how =
+      hider.isWindow && hider.props.hidden
+        ? `${has} \`hidden\``
+        : hider.style?.display === 'none'
+          ? `${has} \`display: 'none'\``
+          : `${self ? 'is hidden by React' : 'which React has hidden'}, in ` +
+            'an `<Activity mode="hidden">` or a `<Suspense>` showing its ' +
+            'fallback';
+    return (
+      `react-x11/test: ${name} ` +
+      (self ? how : `is inside ${describeNode(hider)}, ${how}`) +
+      ', so there is nothing on screen to point at, and `await act()` will ' +
+      'not change that. ' +
+      (self
+        ? 'Show it before pointing at it.'
+        : 'Show that before pointing at anything inside it.')
+    );
+  }
+  if (!node.yoga) {
+    let owner = node.parent;
+    while (owner && !owner.yoga) owner = owner.parent;
+    return (
+      `react-x11/test: ${name} has no box of its own: it is laid out as part ` +
+      `of ${owner ? describeNode(owner) : 'its parent'}, so there is no ` +
+      'rect to point at. Point at that instead, with `{ dx, dy }` to reach ' +
+      'a spot inside it.'
+    );
+  }
+  if (!node._placed || win.needsLayout) {
+    return (
+      `react-x11/test: <${node.kind}> has no laid-out rect yet. Layout runs ` +
+      'on the frame clock, so `await act()` before pointing at it.'
+    );
+  }
+  return (
+    `react-x11/test: ${name} was laid out at 0×0, so there is nothing on ` +
+    'screen to point at. Layout has run since it last changed, so ' +
+    '`await act()` will not give it a size: give it one, with `width` and ' +
+    '`height`, `flexGrow` or content to size it, or point at an ancestor ' +
+    'or a child that has one. If its size comes from content still on its ' +
+    'way, such as an image that is loading, wait for that with `waitFor`.'
+  );
+}
+
+/** The node that takes `node` off the screen — itself or the nearest
+ * ancestor with `display: 'none'` or hidden by React, up to and including
+ * its window, which a `hidden` prop or React keeps unmapped — or null when
+ * nothing does. The same walk as the renderer's `_hiddenInTree`. */
+function hiddenBy(node) {
+  for (let n = node; n; n = n.parent) {
+    if (n.hidden || n.style?.display === 'none') return n;
+    if (n.isWindow) break;
+  }
+  return null;
+}
+
 function serverOf(node) {
-  const server = rootWindow(node)?.app?._reactX11TestServer;
+  // what a target that is no node at all — a `queryBy*` that found nothing —
+  // is told by `screenPointOf`, for the calls that never ask it
+  const win = rootWindow(node);
+  if (!win) throw new Error(NOT_IN_A_WINDOW);
+  const server = win.app?._reactX11TestServer;
   if (!server) {
     throw new Error(
       'react-x11/test: fireEvent needs the in-process X server, so it needs a ' +
@@ -142,10 +241,13 @@ export const fireEvent = {
     fireEvent.mouseMove(node, options);
   },
 
-  /** Move the pointer off the node, which is what produces a leave. */
-  mouseLeave(node, options = {}) {
-    const { server } = screenPointOf(node, options);
-    server.injectPointerMove(0, 0);
+  /**
+   * Move the pointer off the node, to the screen's origin, which is what
+   * produces a leave. Nothing is aimed at, so the node may since have been
+   * hidden or unmounted: it only names the connection.
+   */
+  mouseLeave(node) {
+    serverOf(node).injectPointerMove(0, 0);
   },
 
   mouseDown(node, options = {}) {
@@ -157,9 +259,13 @@ export const fireEvent = {
     for (const kc of modifiers.reverse()) server.injectKey(kc, false);
   },
 
+  /**
+   * Release the button wherever the pointer is — a `mouseMove` first puts
+   * it somewhere else. The node only names the connection, so it may be one
+   * the press hid or unmounted: the gesture can still end.
+   */
   mouseUp(node, options = {}) {
-    const { server } = screenPointOf(node, options);
-    server.injectButton(options.button ?? 1, false);
+    serverOf(node).injectButton(options.button ?? 1, false);
   },
 
   /** Press and release — the renderer synthesises the click from the pair. */

package/src/testing/harness.js

@@ -56,23 +56,84 @@ const DEFAULT_SCREEN = { width: 1280, height: 800 };
  * cheapest request with a reply, and its reply cannot arrive before every
  * request queued ahead of it has been processed — which is what makes it a
  * barrier rather than a sleep.
+ *
+ * **On a connection that is going, it resolves at once.** Nothing there will
+ * be answered, and a test that ends its connection still has `act()`,
+ * `waitFor` and `cleanup()` to get through — the last from an `afterEach`.
+ * node-x11 reports the two ways a connection goes very differently:
+ *
+ * - **The app closed it.** From the moment `close()` begins, every request
+ *   throws `client is in closing state` — synchronously, which inside the
+ *   promise below is a rejection.
+ * - **The server ended it** — it exited, or killed the client. All node-x11
+ *   says is an `end` event: it goes on taking requests and never answers
+ *   them, or anything that was in flight, so the round trip waits forever.
+ *   That is the route a test of `onDisconnect` has to take: over the
+ *   in-process stream pair, a client that closed its own connection never
+ *   hears it end.
  */
 export function settle(app, roundTrips = 2) {
   const X = app?.X;
   if (typeof X?.GetInputFocus !== 'function') return Promise.resolve();
+  // renderX11 settles as it mounts, so its connection is watched before a
+  // test can end it
+  const watch = watchEnd(X);
   let chain = Promise.resolve();
   for (let i = 0; i < roundTrips; i++) {
     chain = chain.then(
       () =>
         new Promise((resolve) => {
-          // resolve either way: a closing connection must not hang a test
-          X.GetInputFocus(() => resolve());
+          if (connectionGone(X)) return resolve();
+          const done = () => {
+            watch.waiting.delete(done);
+            resolve();
+          };
+          watch.waiting.add(done);
+          try {
+            X.GetInputFocus(done);
+          } catch {
+            // refused by a rule the check above does not know: whatever the
+            // reason, a request that never went out has nothing to drain
+            done();
+          }
         }),
     );
   }
   return chain;
 }
 
+// Each connection settle() has met: whether the server has ended it, and the
+// round trips waiting on it, which the end has to answer since no reply will.
+const watched = new WeakMap();
+
+function watchEnd(X) {
+  let watch = watched.get(X);
+  if (!watch) {
+    watch = { ended: false, waiting: new Set() };
+    watched.set(X, watch);
+    X.once?.('end', () => {
+      watch.ended = true;
+      for (const done of watch.waiting) done();
+    });
+  }
+  return watch;
+}
+
+/**
+ * Whether a request on this connection would go unanswered: the app began
+ * closing it, or its stream has ended — the test ntk makes before releasing
+ * anything (`connectionGone`, ntk's lib/cleanup.js) — or the server ended
+ * it, which only the `end` event says.
+ */
+function connectionGone(X) {
+  return Boolean(
+    X?._closing ||
+    X?.stream?.destroyed ||
+    X?.stream?.writableEnded ||
+    watched.get(X)?.ended,
+  );
+}
+
 async function createXServerApp({ screen, fonts }) {
   const [{ default: xserver }, ntk] = await Promise.all([
     optional('x11/lib/xserver/index.js', 'is the in-process X server'),
@@ -340,7 +401,15 @@ export async function act(fn, only = null) {
   for (const entry of entries) await settle(entry.app);
 }
 
-/** Run the frame the scheduler would have run, for every window in a root. */
+/**
+ * Run the frame the scheduler would have run, for every window in a root.
+ *
+ * Not skipped on a connection that has gone. The harm a frame can do there
+ * is to throw, which it would only once the app is closing, and the frame
+ * declines on such a connection before it sends a thing (`_flushFrame`); on
+ * one the server ended, its requests are taken and go nowhere. A check here
+ * would be a second copy of the frame's own.
+ */
 function flushFrames(entry) {
   for (const node of windowNodesOf(entry.windowNode)) {
     if (!node.window) continue;
@@ -359,12 +428,17 @@ async function unmountEntry(entry) {
   // before the unmount, so the teardown's own hook traffic is not recorded
   entry.at?.uninstall();
   try {
-    entry.root.unmount?.();
+    // awaited, or the catch is never reached: unmount is async
+    await entry.root.unmount?.();
   } catch {
     // a root whose connection already died: nothing left to unmount
   }
   await settle(entry.app);
-  if (entry.ownsApp) {
+  // A connection that is already going is not closed again. close() begins
+  // with a round trip, which one the test closed refuses by throwing, and
+  // which one whose stream has ended — the server's doing, or a dispose —
+  // never answers, hanging the teardown
+  if (entry.ownsApp && !connectionGone(entry.app.X)) {
     try {
       await entry.app.close?.();
     } catch {

package/src/testing/index.d.ts

@@ -343,7 +343,11 @@ export function cleanup(): Promise<void>;
  */
 export function setAppearance(values: PinnedAppearance): Promise<void>;
 
-/** Drain in-flight requests on a connection. */
+/**
+ * Drain in-flight requests on a connection. On one that has gone — closed by
+ * the app, or ended by the server — it resolves at once, since nothing there
+ * will be answered.
+ */
 export function settle(app: NtkApp, roundTrips?: number): Promise<void>;
 
 /**
@@ -461,8 +465,14 @@ export interface KeyOptions {
 export const fireEvent: {
   mouseMove(node: DrawnNode, options?: PointerOptions): void;
   mouseEnter(node: DrawnNode, options?: PointerOptions): void;
+  /** Move the pointer to the screen's origin, which is a leave. Aims at
+   *  nothing: `node` only names the connection, and may since have been
+   *  hidden or unmounted. */
   mouseLeave(node: DrawnNode, options?: PointerOptions): void;
   mouseDown(node: DrawnNode, options?: PointerOptions): void;
+  /** Release `button` wherever the pointer is — move it first to release
+   *  somewhere else. Aims at nothing: `node` only names the connection, and
+   *  may be one the press hid or unmounted. */
   mouseUp(node: DrawnNode, options?: PointerOptions): void;
   click(node: DrawnNode, options?: PointerOptions): void;
   doubleClick(node: DrawnNode, options?: PointerOptions): void;
@@ -491,6 +501,7 @@ export const userEvent: {
   click(node: DrawnNode, options?: PointerOptions): Promise<void>;
   doubleClick(node: DrawnNode, options?: PointerOptions): Promise<void>;
   hover(node: DrawnNode, options?: PointerOptions): Promise<void>;
+  /** `fireEvent.mouseLeave`, flushed: aims at nothing. */
   unhover(node: DrawnNode, options?: PointerOptions): Promise<void>;
   /** A scroll in notches; `smooth` takes fractions of one, as a touchpad
    *  measures them. */
@@ -517,7 +528,12 @@ export const userEvent: {
   }): Promise<void>;
 };
 
-/** A node's centre in screen coordinates. */
+/**
+ * A node's centre in screen coordinates. Throws, saying why, for a node
+ * with no rect: not laid out yet, laid out at 0×0, or laid out as part of
+ * another node — and for one that is hidden or has unmounted, whatever rect
+ * it kept, which is where it was and not where anything is.
+ */
 export function screenPointOf(
   node: DrawnNode,
   options?: { dx?: number; dy?: number },

package/src/testing/queries.js

@@ -66,11 +66,24 @@ export function roleOf(node) {
   return roleNameOf(node) ?? node.kind;
 }
 
-function describe(node) {
-  const text = textOf(node).trim();
+/** A node the way an error names it: its kind, its `data-testname` and the
+ * start of its text — what a test author can find it by. A `<popup>` is a
+ * window to the renderer, and is named as the element it was written as.
+ * The text is read whether or not the node is still mounted, unlike
+ * `textOf`'s: one that has unmounted presents nothing now, and is named by
+ * what it said. A mounted node holds no unmounted child, so for one of those
+ * the two read the same. */
+export function describeNode(node) {
+  let text = '';
+  (function read(n) {
+    if (typeof n.text === 'string') text += n.text;
+    for (const child of n.children ?? []) read(child);
+  })(node);
+  text = text.trim();
   const name = node.props?.['data-testname'];
+  const tag = node.isPopup ? 'popup' : node.kind;
   return (
-    `<${node.kind}${name ? ` data-testname="${name}"` : ''}>` +
+    `<${tag}${name ? ` data-testname="${name}"` : ''}>` +
     (text ? ` ${JSON.stringify(text.slice(0, 40))}` : '')
   );
 }
@@ -79,7 +92,7 @@ function inventory(root, limit = 12) {
   const lines = [];
   walk(root, (n) => {
     if (n.kind === 'textchunk' || n.kind === 'textspan') return;
-    if (lines.length < limit) lines.push(`  ${describe(n)}`);
+    if (lines.length < limit) lines.push(`  ${describeNode(n)}`);
   });
   return lines.join('\n');
 }
@@ -93,7 +106,7 @@ function one(root, found, what, printTree = inventory) {
   }
   throw new Error(
     `react-x11/test: found ${found.length} elements for ${what}, expected one:\n` +
-      found.map((n) => `  ${describe(n)}`).join('\n'),
+      found.map((n) => `  ${describeNode(n)}`).join('\n'),
   );
 }