@alchemy.run/sigil 0.0.0-alpha.4 → 0.0.0-alpha.6

package/src/testing/explorer-app/style.css

@@ -0,0 +1,194 @@
+body {
+  margin: 0;
+  background: #101014;
+  color: #c0caf5;
+  font-family: monospace;
+  font-size: 13px;
+}
+a {
+  color: #7aa2f7;
+  text-decoration: none;
+}
+a:hover {
+  text-decoration: underline;
+}
+h1 {
+  font-size: 16px;
+  margin: 0 0 4px;
+}
+h2 {
+  font-size: 11px;
+  color: #888;
+  text-transform: uppercase;
+  letter-spacing: 1px;
+  margin: 20px 0 8px;
+}
+p {
+  color: #666;
+  font-size: 11px;
+  margin: 4px 0;
+}
+ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+li {
+  margin: 3px 0;
+}
+button {
+  background: #1f2335;
+  color: #7aa2f7;
+  border: 1px solid #2a2a33;
+  border-radius: 4px;
+  font: inherit;
+  font-size: 11px;
+  cursor: pointer;
+  padding: 1px 8px;
+}
+button:hover {
+  background: #24283b;
+}
+button:disabled {
+  color: #555;
+  cursor: default;
+}
+
+.layout {
+  display: grid;
+  grid-template-columns: 380px 1fr;
+  min-height: 100vh;
+}
+.sidebar {
+  padding: 20px;
+  border-right: 1px solid #2a2a33;
+  overflow-y: auto;
+  max-height: 100vh;
+  box-sizing: border-box;
+}
+.main {
+  padding: 20px;
+  overflow-y: auto;
+  max-height: 100vh;
+  box-sizing: border-box;
+}
+
+.task {
+  margin: 1px 0;
+}
+.task > .row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 1px 0;
+}
+.task .run {
+  visibility: hidden;
+  padding: 0 6px;
+}
+.task > .row:hover .run {
+  visibility: visible;
+}
+.task .dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #444;
+  flex: none;
+}
+.task .dot.pass {
+  background: #9ece6a;
+}
+.task .dot.fail {
+  background: #f7768e;
+}
+.task .dot.run {
+  background: #e0af68;
+  animation: pulse 1s infinite;
+}
+.task .name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.task .time {
+  color: #565f89;
+  font-size: 11px;
+  margin-left: auto;
+  flex: none;
+}
+.task .children {
+  margin-left: 14px;
+  border-left: 1px solid #1f2335;
+  padding-left: 8px;
+}
+.task .error {
+  color: #f7768e;
+  font-size: 11px;
+  margin: 2px 0 4px 14px;
+  white-space: pre-wrap;
+}
+#run-state {
+  color: #e0af68;
+  font-size: 11px;
+  margin-left: 8px;
+  text-transform: none;
+  letter-spacing: 0;
+}
+
+.session {
+  margin-bottom: 20px;
+  border: 1px solid #2a2a33;
+  border-radius: 6px;
+  overflow: hidden;
+  width: fit-content;
+}
+.session > .bar {
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 6px 10px;
+  background: #16161e;
+  font-size: 12px;
+}
+.session .status {
+  color: #9ece6a;
+}
+.session.done .status {
+  color: #888;
+}
+.session.failed .status {
+  color: #f7768e;
+}
+.session > .body {
+  padding: 8px;
+}
+#empty {
+  color: #565f89;
+}
+
+.terminal-view {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  box-sizing: border-box;
+  padding: 12px;
+  gap: 8px;
+}
+.terminal-view header {
+  color: #888;
+  font-size: 12px;
+  display: flex;
+  justify-content: space-between;
+  flex: none;
+}
+.terminal-view .terminal-host {
+  flex: 1;
+  min-height: 0;
+}
+
+@keyframes pulse {
+  50% {
+    opacity: 0.4;
+  }
+}

package/src/testing/explorer-app/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["."]
+}

package/src/testing/explorer-app/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/src/testing/index.ts

@@ -0,0 +1,26 @@
+// End-to-end testing for terminal apps: launch any command in a PTY attached
+// to a real terminal emulator engine — Ghostty's VT core (WebAssembly) or
+// xterm.js — and drive it with Playwright-style locators, key presses, and
+// Vitest matchers. The engines and the PTY are loaded on demand.
+//
+// Published as `@alchemy.run/sigil/testing`; emulator engines remain lazy.
+export type { Emulator, EmulatorCell, EmulatorName } from "#/testing/emulators.ts";
+export { createEmulator } from "#/testing/emulators.ts";
+export { keyToSequence } from "#/testing/keys.ts";
+export { terminalMatchers } from "#/testing/matchers.ts";
+export type {
+  LaunchOptions,
+  TerminalApp,
+  TerminalLocator,
+  WaitForOptions,
+} from "#/testing/terminal.ts";
+export { launchTerminal } from "#/testing/terminal.ts";
+export type {
+  ExplorerEntry,
+  ServeExplorerOptions,
+  ServeTerminalOptions,
+  TerminalServer,
+} from "#/testing/browser.ts";
+export { serveExplorer, serveTerminal } from "#/testing/browser.ts";
+export type { SerializedTask, TestEngine } from "#/testing/vitest.ts";
+export { createVitestEngine } from "#/testing/vitest.ts";

package/src/testing/keys.ts

@@ -0,0 +1,56 @@
+// Key names → escape sequences, Playwright-style: press("Enter"),
+// press("Ctrl+C"), press("Shift+Tab"), or any single character.
+import { CSI, ESC } from "#/ansi/escapes.ts";
+
+const keySequences: Record<string, string> = {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  Enter: "\r",
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  Tab: "\t",
+  "Shift+Tab": `${CSI}Z`,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  Escape: ESC,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  Backspace: "\u007F",
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  Delete: `${CSI}3~`,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  Space: " ",
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  ArrowUp: `${CSI}A`,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  ArrowDown: `${CSI}B`,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  ArrowRight: `${CSI}C`,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  ArrowLeft: `${CSI}D`,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  Home: `${CSI}H`,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  End: `${CSI}F`,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  PageUp: `${CSI}5~`,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  PageDown: `${CSI}6~`,
+};
+
+export const keyToSequence = (key: string): string => {
+  const sequence = keySequences[key];
+  if (sequence !== undefined) {
+    return sequence;
+  }
+
+  const ctrl = /^Ctrl\+([a-z])$/i.exec(key);
+  if (ctrl) {
+    return String.fromCharCode(ctrl[1]!.toLowerCase().charCodeAt(0) - 96);
+  }
+
+  if (Array.from(key).length === 1) {
+    return key;
+  }
+
+  throw new Error(
+    `Unknown key "${key}". Use a named key (${Object.keys(keySequences).join(", ")}), ` +
+      `"Ctrl+<letter>", or a single character.`,
+  );
+};

package/src/testing/live.ts

@@ -0,0 +1,85 @@
+// Mirrors a harness-launched terminal session to a live-view hub (the
+// explorer's /live page) over WebSocket, so e2e runs can be watched in the
+// browser while they execute — Playwright-UI style.
+//
+// Activated by the SIGIL_LIVE_URL environment variable (the explorer sets it
+// for the Vitest UI it spawns). Mirroring is fire-and-forget: a missing or
+// dead hub never affects the test.
+
+type LiveMessage =
+  | { type: "start"; id: string; title: string; columns: number; rows: number }
+  | { type: "title"; id: string; title: string }
+  | { type: "data"; id: string; data: string }
+  | { type: "end"; id: string; code: number | undefined };
+
+export type LiveClient = {
+  send: (message: LiveMessage) => void;
+  close: () => void;
+};
+
+/**
+Connects to the live hub named by `SIGIL_LIVE_URL`, or returns `undefined`
+when none is configured. Messages sent before the socket opens are queued.
+*/
+export const connectLiveClient = (): LiveClient | undefined => {
+  const base = process.env["SIGIL_LIVE_URL"];
+  if (!base) {
+    return undefined;
+  }
+
+  let socket: WebSocket | undefined;
+  let failed = false;
+  const queue: string[] = [];
+
+  try {
+    const url = new URL("/live/ingest", base);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    socket = new WebSocket(url);
+  } catch {
+    return undefined;
+  }
+
+  socket.addEventListener("open", () => {
+    for (const message of queue) {
+      socket?.send(message);
+    }
+
+    queue.length = 0;
+  });
+  socket.addEventListener("error", () => {
+    failed = true;
+    queue.length = 0;
+  });
+
+  return {
+    send: (message) => {
+      if (failed) {
+        return;
+      }
+
+      const encoded = JSON.stringify(message);
+      if (socket?.readyState === WebSocket.OPEN) {
+        socket.send(encoded);
+      } else if (socket?.readyState === WebSocket.CONNECTING) {
+        queue.push(encoded);
+      }
+    },
+    close: () => {
+      try {
+        socket?.close();
+      } catch {}
+    },
+  };
+};
+
+/**
+The current test name when running inside Vitest, for labeling the session.
+*/
+export const currentTestName = async (): Promise<string | undefined> => {
+  try {
+    const { expect } = await import("vitest");
+    return expect.getState().currentTestName ?? undefined;
+  } catch {
+    return undefined;
+  }
+};

package/src/testing/matchers.ts

@@ -0,0 +1,70 @@
+// Playwright-style async matchers for Vitest. Register once per test file:
+//
+//   import { expect } from "vitest";
+//   import { terminalMatchers } from "#/testing/index.ts";
+//   expect.extend(terminalMatchers);
+//
+//   await expect(app.getByText("Home")).toBeVisible();
+//   await expect(app).toContainScreenText("Users");
+// Type-only: makes the module augmentation below attach to vitest's types.
+import type {} from "vitest";
+
+import { type TerminalApp, type TerminalLocator } from "#/testing/terminal.ts";
+
+type MatcherResult = {
+  pass: boolean;
+  message: () => string;
+};
+
+type MatcherContext = {
+  isNot: boolean;
+};
+
+declare module "vitest" {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- must match vitest's own type parameter exactly
+  interface Matchers<T = any> {
+    toBeVisible(options?: { timeout?: number }): Promise<T>;
+    toContainScreenText(text: string | RegExp, options?: { timeout?: number }): Promise<T>;
+  }
+}
+
+export const terminalMatchers = {
+  /**
+	Waits for the locator's text to appear on screen (or to disappear when
+	negated with `.not`).
+	*/
+  async toBeVisible(
+    this: MatcherContext,
+    locator: TerminalLocator,
+    options: { timeout?: number } = {},
+  ): Promise<MatcherResult> {
+    const state = this.isNot ? "hidden" : "visible";
+    try {
+      await locator.waitFor({ ...options, state });
+      return {
+        // `.not` inverts `pass`, so reaching the desired state must report
+        // the polarity that makes the assertion succeed either way.
+        pass: !this.isNot,
+        message: () => `expected ${locator.description} to be ${state} — and it is`,
+      };
+    } catch (error) {
+      return {
+        pass: this.isNot,
+        message: () => (error as Error).message,
+      };
+    }
+  },
+
+  /**
+	Waits for the given text to appear anywhere on the visible screen.
+	*/
+  async toContainScreenText(
+    this: MatcherContext,
+    app: TerminalApp,
+    text: string | RegExp,
+    options: { timeout?: number } = {},
+  ): Promise<MatcherResult> {
+    const locator = app.getByText(text);
+    return terminalMatchers.toBeVisible.call(this, locator, options);
+  },
+};

package/src/testing/public.ts

@@ -0,0 +1,94 @@
+import { EventEmitter } from "node:events";
+
+import type { ColorProfile } from "#/screen/color-profile.ts";
+import type { Screen } from "#/screen/screen.ts";
+import { serializeScreen } from "#/screen/serialize.ts";
+
+export class VirtualOutput extends EventEmitter {
+  columns: number;
+  rows: number;
+  isTTY: boolean;
+  writable = true;
+  writableEnded = false;
+  destroyed = false;
+  #chunks: string[] = [];
+
+  constructor(options: { columns?: number; rows?: number; isTTY?: boolean } = {}) {
+    super();
+    this.columns = options.columns ?? 80;
+    this.rows = options.rows ?? 24;
+    this.isTTY = options.isTTY ?? true;
+  }
+
+  write(
+    chunk: Uint8Array | string,
+    encodingOrCallback?: BufferEncoding | (() => void),
+    callback?: () => void,
+  ): boolean {
+    this.#chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString());
+    const done = typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+    queueMicrotask(() => done?.());
+    return true;
+  }
+
+  output(): string {
+    return this.#chunks.join("");
+  }
+  writes(): readonly string[] {
+    return this.#chunks;
+  }
+  reset(): void {
+    this.#chunks = [];
+  }
+  resize(columns: number, rows: number): void {
+    this.columns = columns;
+    this.rows = rows;
+    this.emit("resize");
+  }
+}
+
+export type RecordedFrame = {
+  readonly timestamp: number;
+  readonly screen: Screen;
+  readonly output: string;
+};
+
+export class FrameRecorder {
+  #frames: RecordedFrame[] = [];
+  readonly colorProfile: ColorProfile;
+  constructor(colorProfile: ColorProfile = "truecolor") {
+    this.colorProfile = colorProfile;
+  }
+  record(screen: Screen, timestamp = performance.now()): RecordedFrame {
+    const frame = {
+      timestamp,
+      screen,
+      output: serializeScreen(screen, { colorProfile: this.colorProfile }),
+    };
+    this.#frames.push(frame);
+    return frame;
+  }
+  frames(): readonly RecordedFrame[] {
+    return this.#frames;
+  }
+  clear(): void {
+    this.#frames = [];
+  }
+}
+
+export const screenText = (screen: Screen): string =>
+  screen
+    .toRows()
+    .map((row) =>
+      row
+        .filter((cell) => cell.width > 0)
+        .map((cell) => cell.grapheme)
+        .join("")
+        .trimEnd(),
+    )
+    .join("\n");
+
+export function assertScreenText(screen: Screen, expected: string): void {
+  const actual = screenText(screen);
+  if (actual !== expected) throw new Error(`Expected screen:\n${expected}\n\nReceived:\n${actual}`);
+}