@cueloop/client 0.1.0-alpha.11 → 0.1.0-alpha.111

package/src/testing/test-support.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createElement, type ReactElement } from "react";
+import type { KeyEvent, MouseEvent } from "@opentui/core";
+import type { TestRendererSetup } from "@opentui/core/testing";
+import { useKeyboard } from "@opentui/react";
+import { testRender } from "@opentui/react/test-utils";
+import { loadConfig } from "../settings/config";
+import {
+  clickText,
+  dragText,
+  frameRow,
+  isolateUserConfig,
+  locateText,
+  locateTextInFrame,
+  pressKey,
+  waitForText,
+  type FrameLocation,
+} from "./test-support";
+
+describe("isolateUserConfig", () => {
+  test("loadConfig sees defaults while isolated and the env is restored after", () => {
+    // Arrange
+    const home = mkdtempSync(join(tmpdir(), "cueloop-isolate-"));
+    const userConfigPath = join(home, "config.toml");
+
+    writeFileSync(userConfigPath, "[ui]\nauto_close = 5\n");
+    const priorEnv = process.env.CUELOOP_CONFIG;
+
+    process.env.CUELOOP_CONFIG = userConfigPath;
+
+    try {
+      // Act
+      const restoreUserConfig = isolateUserConfig(home);
+      const isolated = loadConfig({ repoRoot: home });
+
+      restoreUserConfig();
+      const restored = loadConfig({ repoRoot: home });
+
+      // Assert
+      expect(isolated.ui.autoClose).toBe("off");
+      expect(process.env.CUELOOP_CONFIG).toBe(userConfigPath);
+      expect(restored.ui.autoClose).toBe(5);
+    } finally {
+      if (priorEnv === undefined) delete process.env.CUELOOP_CONFIG;
+      else process.env.CUELOOP_CONFIG = priorEnv;
+
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test("restore removes the variable when nothing was set before", () => {
+    // Arrange
+    const home = mkdtempSync(join(tmpdir(), "cueloop-isolate-"));
+    const priorEnv = process.env.CUELOOP_CONFIG;
+
+    delete process.env.CUELOOP_CONFIG;
+
+    try {
+      // Act
+      const restoreUserConfig = isolateUserConfig(home);
+      const pointedAt = process.env.CUELOOP_CONFIG ?? "";
+
+      restoreUserConfig();
+
+      // Assert
+      expect(pointedAt).toBe(join(home, "no-config.toml"));
+      expect(process.env.CUELOOP_CONFIG).toBeUndefined();
+    } finally {
+      if (priorEnv !== undefined) process.env.CUELOOP_CONFIG = priorEnv;
+
+      rmSync(home, { recursive: true, force: true });
+    }
+  });
+});
+
+interface RecordedKey {
+  name: string;
+  ctrl: boolean;
+  shift: boolean;
+  meta: boolean;
+}
+
+interface RecordedMouseEvent {
+  type: "down" | "up";
+  x: number;
+  y: number;
+}
+
+interface FixtureLog {
+  keys: RecordedKey[];
+  mouseEvents: RecordedMouseEvent[];
+  pressZoneClicks: number[];
+}
+
+/**
+ * A minimal interaction surface: one keyboard recorder, a root box recording
+ * down/up coordinates, and stacked text rows at known positions.
+ */
+function InteractionFixture(properties: { log: FixtureLog }): ReactElement {
+  const { log } = properties;
+
+  useKeyboard((key: KeyEvent) => {
+    log.keys.push({ name: key.name, ctrl: key.ctrl, shift: key.shift, meta: key.meta });
+  });
+
+  return createElement(
+    "box",
+    {
+      width: "100%",
+      height: "100%",
+      flexDirection: "column",
+      onMouseDown: (event: MouseEvent) => {
+        log.mouseEvents.push({ type: "down", x: event.x, y: event.y });
+      },
+      onMouseUp: (event: MouseEvent) => {
+        log.mouseEvents.push({ type: "up", x: event.x, y: event.y });
+      },
+    },
+    createElement("text", { content: "header line" }),
+    createElement("text", { content: "   shifted needle" }),
+    createElement("text", { content: "  drag from here" }),
+    createElement("text", { content: "     drop to here" }),
+    createElement("text", {
+      content: "press zone",
+      onMouseDown: (event: MouseEvent) => {
+        log.pressZoneClicks.push(event.x);
+      },
+    }),
+  );
+}
+
+async function renderFixture(): Promise<{ setup: TestRendererSetup; log: FixtureLog }> {
+  const log: FixtureLog = { keys: [], mouseEvents: [], pressZoneClicks: [] };
+  const setup = await testRender(createElement(InteractionFixture, { log }), {
+    width: 40,
+    height: 8,
+  });
+
+  await waitForText(setup, "press zone");
+
+  return { setup, log };
+}
+
+describe("pressKey", () => {
+  test("a ctrl+letter chord reaches the keyboard handler with ctrl set", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await pressKey(setup, "o", { ctrl: true });
+
+    // Assert
+    expect(log.keys).toEqual([{ name: "o", ctrl: true, shift: false, meta: false }]);
+  });
+
+  test("a named key with a modifier arrives as the modified key", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await pressKey(setup, "ARROW_RIGHT", { shift: true });
+
+    // Assert
+    expect(log.keys).toEqual([{ name: "right", ctrl: false, shift: true, meta: false }]);
+  });
+});
+
+describe("locateText", () => {
+  test("returns the 0-based row and start column of the first occurrence", async () => {
+    // Arrange
+    const { setup } = await renderFixture();
+
+    // Act
+    const located = locateText(setup, "shifted needle");
+
+    // Assert
+    expect(located).toEqual({ row: 1, column: 3 });
+  });
+
+  test("a miss throws with the needle and the full frame in the message", async () => {
+    // Arrange
+    const { setup } = await renderFixture();
+
+    // Act
+    const locateMissing = (): FrameLocation => locateText(setup, "absent needle");
+
+    // Assert
+    expect(locateMissing).toThrow('"absent needle"');
+    expect(locateMissing).toThrow("header line");
+  });
+});
+
+describe("frameRow", () => {
+  test("returns rows that reflect the vertical layout", async () => {
+    // Arrange
+    const { setup } = await renderFixture();
+
+    // Act / Assert
+    expect(frameRow(setup, "header line")).toBe(0);
+    expect(frameRow(setup, "drop to here")).toBe(3);
+    expect(frameRow(setup, "press zone")).toBe(4);
+  });
+});
+
+describe("clickText", () => {
+  test("lands the click on the element rendering the needle", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await clickText(setup, "press zone");
+
+    // Assert
+    expect(log.pressZoneClicks).toEqual([0]);
+  });
+
+  test("charOffset shifts the click within the needle", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await clickText(setup, "press zone", 6);
+
+    // Assert
+    expect(log.pressZoneClicks).toEqual([6]);
+  });
+});
+
+describe("dragText", () => {
+  test("delivers the down at the from-text and the up at the to-text", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await dragText(setup, "drag from here", "drop to here");
+
+    // Assert
+    expect(log.mouseEvents).toContainEqual({ type: "down", x: 2, y: 2 });
+    expect(log.mouseEvents).toContainEqual({ type: "up", x: 5, y: 3 });
+  });
+
+  test("an end offset lands the up that many characters past the to-text", async () => {
+    // Arrange
+    const { setup, log } = await renderFixture();
+
+    // Act
+    await dragText(setup, "drag from here", "drop to here", 4);
+
+    // Assert
+    expect(log.mouseEvents).toContainEqual({ type: "up", x: 9, y: 3 });
+  });
+});
+
+describe("locateTextInFrame", () => {
+  test("finds the 0-based row and column of the first match, null when absent", () => {
+    // Arrange
+    const frame = "header\n  ● draft here\nfooter";
+
+    // Act + Assert
+    expect(locateTextInFrame(frame, "draft")).toEqual({ row: 1, column: 4 });
+    expect(locateTextInFrame(frame, "missing")).toBeNull();
+  });
+});

package/src/testing/test-support.ts

@@ -0,0 +1,449 @@
+/**
+ * Shared driving helpers for the virtual-terminal App suites: an input settles
+ * when its painted frame stops changing across consecutive event-loop turns
+ * (macrotask yield, render pass, visual-idle wait per turn) - no fixed-duration
+ * sleeps. Waits on daemon round-trips go through waitForFrame/waitFor with
+ * generous pass budgets.
+ */
+
+import { join } from "node:path";
+import { cloneElement, isValidElement, type ReactNode } from "react";
+import type { TestRendererOptions, TestRendererSetup } from "@opentui/core/testing";
+import { testRender } from "@opentui/react/test-utils";
+import type { AppProps } from "../app/App";
+
+/**
+ * A probe for the App's ready signal in an in-process suite: pass `onReady`
+ * to the App and await `ready` before the first interaction, instead of
+ * waiting for a piece of text and hoping the keyboard is bound by then.
+ */
+export interface AppReadyProbe {
+  onReady: () => void;
+  ready: Promise<void>;
+}
+
+export function appReadyProbe(): AppReadyProbe {
+  let resolve: () => void = () => {};
+  const ready = new Promise<void>((done) => {
+    resolve = done;
+  });
+
+  return { onReady: () => resolve(), ready };
+}
+
+/**
+ * Boot an App element and resolve once it has fired its ready signal: the
+ * first usable screen is painted and its keyboard handlers are subscribed.
+ * Every App suite starts here so no boot waits on a piece of text and hopes.
+ */
+export async function renderReadyApp(
+  element: ReactNode,
+  options: TestRendererOptions,
+): Promise<TestRendererSetup> {
+  if (!isValidElement<AppProps>(element)) throw new Error("renderReadyApp needs an App element");
+
+  const probe = appReadyProbe();
+  const setup = await testRender(cloneElement(element, { onReady: probe.onReady }), options);
+
+  allowEventLoopUpdates();
+  await probe.ready;
+
+  return setup;
+}
+
+/**
+ * The CUELOOP_CONFIG path that isolates a test from the developer's real user
+ * config: a file inside the test home that does not exist unless the test
+ * writes it. Subprocess harnesses set this in the child env; in-process suites
+ * use `isolateUserConfig`.
+ */
+export function isolatedUserConfigPath(home: string, fileName = "no-config.toml"): string {
+  return join(home, fileName);
+}
+
+/**
+ * Isolate the user config: point CUELOOP_CONFIG into the test home so
+ * loadConfig never reads the developer's real ~/.config/cueloop (a persisted
+ * review_state would change what char frames render locally while CI stays
+ * clean). The default file name does not exist, so loadConfig returns
+ * defaults; pass a file name for suites that write and assert a config of
+ * their own. Call in beforeEach; invoke the returned restore in afterEach.
+ */
+export function isolateUserConfig(home: string, fileName?: string): () => void {
+  const priorUserConfig = process.env.CUELOOP_CONFIG;
+
+  process.env.CUELOOP_CONFIG = isolatedUserConfigPath(home, fileName);
+
+  return () => {
+    if (priorUserConfig === undefined) delete process.env.CUELOOP_CONFIG;
+    else process.env.CUELOOP_CONFIG = priorUserConfig;
+  };
+}
+
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+
+/** The harness drives the real event loop by design; keep React's act warning off. */
+export function allowEventLoopUpdates(): void {
+  globalThis.IS_REACT_ACT_ENVIRONMENT = false;
+}
+
+/** Turns of the event loop a frame must survive unchanged before an input counts as settled. */
+const SETTLE_QUIET_TURNS = 2;
+
+/** Upper bound on settle turns, so a surface that keeps changing never stalls a test. */
+const SETTLE_MAX_TURNS = 40;
+
+/** The painted frame with its colors, so a caret cell (background only) counts as a change. */
+function paintedFrame(setup: TestRendererSetup): string {
+  return JSON.stringify(
+    setup
+      .captureSpans()
+      .lines.map((line) =>
+        line.spans.map((span) => [span.text, span.fg?.toInts(), span.bg?.toInts()]),
+      ),
+  );
+}
+
+/**
+ * Wait for an input to land: React commits its state on its own scheduler, which the renderer's
+ * idle check cannot see, so on a slow machine a single idle wait returns between the key and its
+ * paint. Instead, run turns of the loop until the painted frame is unchanged across
+ * `SETTLE_QUIET_TURNS` consecutive turns.
+ */
+export async function settle(setup: TestRendererSetup): Promise<void> {
+  allowEventLoopUpdates();
+  let previous = "";
+  let quietTurns = 0;
+
+  for (let turn = 0; turn < SETTLE_MAX_TURNS; turn++) {
+    if (setup.renderer.isDestroyed) return;
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    if (setup.renderer.isDestroyed) return;
+
+    await setup.renderOnce();
+    await setup.waitForVisualIdle();
+
+    if (setup.renderer.isDestroyed) return;
+
+    if (setup.renderer.getSchedulerState().isRendering) {
+      await setup.renderOnce();
+    }
+
+    const frame = paintedFrame(setup);
+
+    quietTurns = frame === previous ? quietTurns + 1 : 0;
+
+    if (quietTurns >= SETTLE_QUIET_TURNS) return;
+
+    previous = frame;
+  }
+}
+
+/** Drive one key press: letters type as text; named keys use KeyCodes ids. */
+export async function press(setup: TestRendererSetup, key: string): Promise<void> {
+  if (key === "enter") setup.mockInput.pressKey("RETURN");
+  else if (key === "escape") setup.mockInput.pressKey("ESCAPE");
+  else if (key === "backspace") setup.mockInput.pressKey("BACKSPACE");
+  else if (key === "left") setup.mockInput.pressKey("ARROW_LEFT");
+  else if (key === "right") setup.mockInput.pressKey("ARROW_RIGHT");
+  else if (key === "up") setup.mockInput.pressKey("ARROW_UP");
+  else if (key === "down") setup.mockInput.pressKey("ARROW_DOWN");
+  else return typeText(setup, key);
+
+  await settle(setup);
+}
+
+export async function typeText(setup: TestRendererSetup, text: string): Promise<void> {
+  await setup.mockInput.typeText(text);
+  await settle(setup);
+}
+
+/** Drive one key press with modifiers: KeyCodes names ("ARROW_RIGHT") or single letters (ctrl+o). */
+export async function pressKey(
+  setup: TestRendererSetup,
+  key: string,
+  modifiers?: { shift?: boolean; ctrl?: boolean; meta?: boolean },
+): Promise<void> {
+  setup.mockInput.pressKey(key, modifiers);
+  await settle(setup);
+}
+
+/**
+ * Run a thread nav-mode command: esc drops the surface into nav mode, then a bare
+ * key acts (a letter, or a named key like "enter"/"backspace"). The caret and any
+ * held selection carry into nav, so the command lands where the caret is.
+ */
+export async function navCommand(setup: TestRendererSetup, key: string): Promise<void> {
+  await press(setup, "escape");
+  await new Promise((resolve) => setTimeout(resolve, 40));
+  await settle(setup);
+
+  // a single letter is a discrete keypress (nav command); named keys route through press
+  if (key.length === 1) await pressKey(setup, key);
+  else await press(setup, key);
+}
+
+/** A 0-based cell position within a captured char frame. */
+export interface FrameLocation {
+  row: number;
+  column: number;
+}
+
+/** Locate the first line of a text frame containing the needle; null when absent. */
+export function locateTextInFrame(frame: string, needle: string): FrameLocation | null {
+  for (const [row, line] of frame.split("\n").entries()) {
+    const column = line.indexOf(needle);
+
+    if (column !== -1) return { row, column };
+  }
+
+  return null;
+}
+
+/** Locate the first visual line containing the needle: 0-based row and start column. */
+export function locateText(setup: TestRendererSetup, needle: string): FrameLocation {
+  const frame = setup.captureCharFrame();
+  const location = locateTextInFrame(frame, needle);
+
+  if (location === null) {
+    throw new Error(`locateText ${JSON.stringify(needle)} not found.\nframe:\n${frame}`);
+  }
+
+  return location;
+}
+
+/** The 0-based visual row of the needle - for relative vertical-layout assertions. */
+export function frameRow(setup: TestRendererSetup, needle: string): number {
+  return locateText(setup, needle).row;
+}
+
+/** Click the first on-screen occurrence of the needle, offset in characters from its start. */
+export async function clickText(
+  setup: TestRendererSetup,
+  needle: string,
+  charOffset = 0,
+): Promise<void> {
+  const { row, column } = locateText(setup, needle);
+
+  await setup.mockMouse.click(column + charOffset, row);
+  await settle(setup);
+}
+
+/**
+ * Drag from the first occurrence of one needle to the first occurrence of
+ * another, `toCharOffset` characters past the second needle's start - so a
+ * character-precise selection can end inside or right after a word.
+ */
+export async function dragText(
+  setup: TestRendererSetup,
+  fromNeedle: string,
+  toNeedle: string,
+  toCharOffset = 0,
+): Promise<void> {
+  const from = locateText(setup, fromNeedle);
+  const to = locateText(setup, toNeedle);
+
+  await setup.mockMouse.drag(from.column, from.row, to.column + toCharOffset, to.row);
+  await settle(setup);
+}
+
+// Below the 60s per-test budget so a genuinely stuck wait throws its frame
+// error (useful) before bun's bare "timed out" fires. Generous because a
+// contended CI runner starves the render loop and daemon round-trips.
+const WAIT_DEADLINE_MS = 45_000;
+
+/** One macrotask turn: hands the event loop back so the in-process daemon can
+ *  read its socket and apply the write before the next poll. Tight render-pass
+ *  bursts starve that read on a contended CI runner - the round-trip then never
+ *  lands and the wait hangs the whole budget. */
+function yieldEventLoop(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 2));
+}
+
+/** Log a still-waiting line at most this often, so only genuinely slow (i.e.
+ *  flaking) waits are noisy; fast waits stay silent. */
+const PROGRESS_LOG_MS = 4000;
+
+/** The last render frame's tail, so a progress line shows what is on screen. */
+function frameTail(frame: string, rows = 6): string {
+  return frame.split("\n").slice(-rows).join("\n");
+}
+
+/**
+ * Poll gently: one render pass, one frame check, one macrotask yield. No
+ * multi-pass bursts, so the daemon (same event loop) always gets a turn to
+ * process IO between checks. The deadline bounds the whole wait. Slow waits log
+ * progress (poll count + frame-change count) so a CI stall shows whether the
+ * render froze or the content simply never arrived.
+ */
+async function waitForFramePredicate(
+  setup: TestRendererSetup,
+  predicate: (frame: string) => boolean,
+  label: string,
+): Promise<string> {
+  allowEventLoopUpdates();
+  const start = Date.now();
+  const deadline = start + WAIT_DEADLINE_MS;
+  let polls = 0;
+  let frameChanges = 0;
+  let lastFrame = "";
+  let lastLog = start;
+
+  for (;;) {
+    if (setup.renderer.isDestroyed) {
+      throw new Error(
+        `waitFor ${label} failed: renderer was destroyed before frame matched.\nlast frame:\n${lastFrame}`,
+      );
+    }
+
+    await setup.renderOnce();
+
+    if (setup.renderer.isDestroyed) {
+      throw new Error(
+        `waitFor ${label} failed: renderer was destroyed before frame matched.\nlast frame:\n${lastFrame}`,
+      );
+    }
+
+    // Retry while a render still holds the buffer lease.
+    // eslint-disable-next-line no-await-in-loop
+    const frame = await captureSettledFrame(setup);
+
+    polls++;
+
+    if (frame !== lastFrame) {
+      frameChanges++;
+      lastFrame = frame;
+    }
+
+    if (predicate(frame)) return frame;
+
+    const now = Date.now();
+
+    if (now > deadline) {
+      const frozen = frameChanges <= 1 ? " - render never advanced (frozen)" : "";
+
+      throw new Error(
+        `waitFor ${label} timed out after ${now - start}ms (${polls} polls, ${frameChanges} frame changes${frozen}).\nlast frame:\n${frame}`,
+      );
+    }
+
+    if (now - lastLog >= PROGRESS_LOG_MS) {
+      lastLog = now;
+      console.error(
+        `[waitFor] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes\n${frameTail(frame)}`,
+      );
+    }
+
+    await yieldEventLoop();
+  }
+}
+
+/**
+ * Capture a frame, retrying while OpenTUI still holds the buffer lease.
+ * A render in progress answers the capture with OutputBusy.
+ */
+export async function captureSettledFrame(
+  setup: { captureCharFrame(): string },
+  deadline = Date.now() + 1_000,
+): Promise<string> {
+  try {
+    return setup.captureCharFrame();
+  } catch (error) {
+    const busy = error instanceof Error && error.message.includes("OutputBusy");
+
+    if (!busy || Date.now() >= deadline) throw error;
+
+    await new Promise((resolve) => setTimeout(resolve, 15));
+
+    return captureSettledFrame(setup, deadline);
+  }
+}
+
+/** Wait until a state predicate holds (daemon round-trips included). */
+export async function waitForState(
+  setup: TestRendererSetup,
+  predicate: () => boolean,
+  label = "state",
+): Promise<void> {
+  allowEventLoopUpdates();
+  const start = Date.now();
+  const deadline = start + WAIT_DEADLINE_MS;
+  let polls = 0;
+  let frameChanges = 0;
+  let lastFrame = "";
+  let lastLog = start;
+
+  for (;;) {
+    if (setup.renderer.isDestroyed) {
+      if (predicate()) return;
+
+      throw new Error(
+        `waitForState ${label} failed: renderer was destroyed before condition matched.\nlast frame:\n${lastFrame}`,
+      );
+    }
+
+    await setup.renderOnce();
+
+    if (setup.renderer.isDestroyed) {
+      if (predicate()) return;
+
+      throw new Error(
+        `waitForState ${label} failed: renderer was destroyed before condition matched.\nlast frame:\n${lastFrame}`,
+      );
+    }
+
+    // Retry while a render still holds the buffer lease.
+    // eslint-disable-next-line no-await-in-loop
+    const frame = await captureSettledFrame(setup);
+
+    polls++;
+
+    if (frame !== lastFrame) {
+      frameChanges++;
+      lastFrame = frame;
+    }
+
+    if (predicate()) return;
+
+    const now = Date.now();
+
+    if (now > deadline) {
+      const frozen = frameChanges <= 1 ? " - render never advanced (frozen)" : "";
+
+      throw new Error(
+        `waitForState ${label} timed out after ${now - start}ms (${polls} polls, ${frameChanges} frame changes${frozen}).\nlast frame:\n${frame}`,
+      );
+    }
+
+    if (now - lastLog >= PROGRESS_LOG_MS) {
+      lastLog = now;
+      console.error(
+        `[waitForState] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes`,
+      );
+    }
+
+    await yieldEventLoop();
+  }
+}
+
+/** Wait until the frame contains the needle (daemon round-trips included). */
+export async function waitForText(setup: TestRendererSetup, needle: string): Promise<string> {
+  return waitForFramePredicate(
+    setup,
+    (frame) => frame.includes(needle),
+    `text ${JSON.stringify(needle)}`,
+  );
+}
+
+/** Wait until the frame no longer contains the needle. */
+export async function waitForTextGone(setup: TestRendererSetup, needle: string): Promise<string> {
+  return waitForFramePredicate(
+    setup,
+    (frame) => !frame.includes(needle),
+    `text-gone ${JSON.stringify(needle)}`,
+  );
+}