@visulima/tui 0.0.1 → 1.0.0-alpha.10

package/dist/testing/index.d.ts

@@ -0,0 +1,283 @@
+import { ReactElement } from 'react';
+import { R as RenderOptions } from "../packem_shared/render.d-BR3gA-N8.js";
+import 'yoga-layout';
+import '@visulima/colorize';
+import 'type-fest';
+import 'node:stream';
+declare const KEY: {
+  readonly backspace: "";
+  readonly ctrlC: "";
+  readonly delete: "\x1B[3~";
+  readonly down: "\x1B[B";
+  readonly end: "\x1B[F";
+  readonly escape: "\x1B";
+  readonly home: "\x1B[H";
+  readonly left: "\x1B[D";
+  readonly pageDown: "\x1B[6~";
+  readonly pageUp: "\x1B[5~";
+  readonly return: "\r";
+  readonly right: "\x1B[C";
+  readonly space: " ";
+  readonly tab: "	";
+  readonly up: "\x1B[A";
+};
+type KeyName = keyof typeof KEY;
+interface KeySender {
+  /**
+  * Simulate pressing the backspace key.
+  */
+  backspace: () => void;
+  /**
+  * Simulate pressing the delete key.
+  */
+  delete: () => void;
+  /**
+  * Simulate pressing the down arrow key.
+  */
+  down: () => void;
+  /**
+  * Simulate pressing the end key.
+  */
+  end: () => void;
+  /**
+  * Simulate pressing the enter/return key.
+  */
+  enter: () => void;
+  /**
+  * Simulate pressing the escape key.
+  */
+  escape: () => void;
+  /**
+  * Simulate pressing the home key.
+  */
+  home: () => void;
+  /**
+  * Simulate pressing the left arrow key.
+  */
+  left: () => void;
+  /**
+  * Simulate pressing the page down key.
+  */
+  pageDown: () => void;
+  /**
+  * Simulate pressing the page up key.
+  */
+  pageUp: () => void;
+  /**
+  * Send a single character as a key press.
+  */
+  press: (char: string) => void;
+  /**
+  * Send arbitrary raw data to stdin.
+  */
+  raw: (data: string) => void;
+  /**
+  * Simulate pressing the right arrow key.
+  */
+  right: () => void;
+  /**
+  * Simulate pressing the space key.
+  */
+  space: () => void;
+  /**
+  * Simulate pressing the tab key.
+  */
+  tab: () => void;
+  /**
+  * Type a string character by character.
+  */
+  type: (text: string) => void;
+  /**
+  * Simulate pressing the up arrow key.
+  */
+  up: () => void;
+}
+declare const createKeySender: (write: (data: string) => void) => KeySender;
+interface Screen {
+  /**
+  * Check if the current screen output contains the given text (ANSI-stripped).
+  */
+  contains: (text: string) => boolean;
+  /**
+  * Get all captured frames with ANSI codes stripped.
+  */
+  frames: () => string[];
+  /**
+  * Get a specific line by zero-based index from the current screen output.
+  */
+  line: (n: number) => string;
+  /**
+  * Get all non-empty lines from the current screen output.
+  */
+  lines: () => string[];
+  /**
+  * Check if the current screen output matches the given pattern (ANSI-stripped).
+  */
+  matches: (pattern: RegExp) => boolean;
+  /**
+  * Get all captured frames with ANSI codes preserved.
+  */
+  rawFrames: () => string[];
+  /**
+  * Get the last rendered frame with ANSI codes preserved.
+  */
+  rawText: () => string;
+  /**
+  * Get the last rendered frame with ANSI codes stripped.
+  */
+  text: () => string;
+}
+declare const createScreen: (lastFrame: () => string | undefined, allFrames: ReadonlyArray<string>) => Screen;
+interface WaitForOptions {
+  /**
+  * Polling interval in milliseconds.
+  * @default 50
+  */
+  interval?: number;
+  /**
+  * Maximum time to wait in milliseconds before throwing.
+  * @default 3000
+  */
+  timeout?: number;
+}
+/**
+* Wait for a condition to be met by polling at a regular interval.
+*
+* If `condition` is a string, waits until `screenText()` contains it.
+* If `condition` is a function, waits until it stops throwing.
+* @throws The last error encountered if the timeout is reached.
+*/
+declare const waitFor: (condition: (() => void) | string, screenText: () => string, options?: WaitForOptions) => Promise<void>;
+type TestInstanceStdout = {
+  /**
+  * All rendered frames captured from stdout.
+  */
+  readonly frames: ReadonlyArray<string>;
+  /**
+  * Returns the most recently rendered frame, or `undefined` if no frames have been written.
+  */
+  lastFrame: () => string | undefined;
+  /**
+  * Write data to the mock stdout stream (used internally by the renderer).
+  */
+  write: (frame: string) => boolean;
+};
+type TestInstanceStderr = {
+  /**
+  * All rendered frames captured from stderr.
+  */
+  readonly frames: ReadonlyArray<string>;
+  /**
+  * Returns the most recently rendered frame, or `undefined` if no frames have been written.
+  */
+  lastFrame: () => string | undefined;
+  /**
+  * Write data to the mock stderr stream (used internally by the renderer).
+  */
+  write: (frame: string) => boolean;
+};
+type TestInstanceStdin = {
+  /**
+  * Whether the stdin is a TTY.
+  */
+  readonly isTTY: boolean;
+  /**
+  * Simulate user input by writing data to stdin.
+  */
+  write: (data: string) => boolean;
+};
+type TestInstance = {
+  /**
+  * Unmount the app and clean up resources.
+  */
+  cleanup: () => void;
+  /**
+  * Wait for pending React renders to flush (two microtick delay).
+  */
+  flush: () => Promise<void>;
+  /**
+  * All rendered frames captured from stdout (shorthand for `stdout.frames`).
+  */
+  readonly frames: ReadonlyArray<string>;
+  /**
+  * Keyboard input helpers for simulating key presses.
+  */
+  keys: KeySender;
+  /**
+  * Returns the most recently rendered frame from stdout (shorthand for `stdout.lastFrame()`).
+  */
+  lastFrame: () => string | undefined;
+  /**
+  * Replace the previous root node with a new one or update props.
+  */
+  rerender: (node: ReactElement) => void;
+  /**
+  * Screen query helpers for inspecting rendered output with ANSI stripping.
+  */
+  screen: Screen;
+  /**
+  * Mock stderr stream with frame capture.
+  */
+  stderr: TestInstanceStderr;
+  /**
+  * Mock stdin stream for simulating user input.
+  */
+  stdin: TestInstanceStdin;
+  /**
+  * Mock stdout stream with frame capture.
+  */
+  stdout: TestInstanceStdout;
+  /**
+  * Manually unmount the whole app.
+  */
+  unmount: () => void;
+  /**
+  * Wait for a condition to be met by polling.
+  *
+  * If `condition` is a string, waits until the screen contains it.
+  * If `condition` is a function, waits until it stops throwing.
+  */
+  waitFor: (condition: (() => void) | string, options?: WaitForOptions) => Promise<void>;
+};
+type TestRenderOptions = {
+  /**
+  * Terminal column width for the mock stdout/stderr streams.
+  * @default 100
+  */
+  columns?: number;
+  /**
+  * Additional render options passed through to the underlying render function.
+  */
+  options?: Omit<RenderOptions, "debug" | "exitOnCtrlC" | "patchConsole" | "stderr" | "stdin" | "stdout">;
+};
+/**
+* Render a React element for testing, capturing output in mock streams.
+*
+* Returns an object with methods to inspect rendered output, simulate input,
+* and control the component lifecycle.
+* @example
+* ```tsx
+* import { render } from "@visulima/tui/test";
+* import { Text } from "@visulima/tui";
+*
+* const { lastFrame } = render(<Text>Hello</Text>);
+* console.log(lastFrame()); // "Hello"
+* ```
+*/
+declare const testRender: (node: ReactElement, testOptions?: TestRenderOptions) => TestInstance;
+/**
+* Unmount and clean up all rendered test instances.
+*
+* Call this in your test teardown (e.g., `afterEach`) to ensure
+* no test instances leak between tests.
+* @example
+* ```ts
+* import { cleanup } from "@visulima/tui/test";
+*
+* afterEach(() => {
+*     cleanup();
+* });
+* ```
+*/
+declare const cleanup: () => void;
+export { KEY, type KeyName, type KeySender, type Screen, TestInstance, TestInstanceStderr, TestInstanceStdin, TestInstanceStdout, TestRenderOptions, type WaitForOptions, cleanup, createKeySender, createScreen, testRender as render, waitFor };

package/dist/testing/index.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var a=(t,e)=>w(t,"name",{value:e,configurable:!0});import{createRequire as F}from"node:module";import x from"../packem_shared/render-_r0K9K11.js";import{createKeySender as y}from"../packem_shared/KEY-Bk8B-3h_.js";import{KEY as $}from"../packem_shared/KEY-Bk8B-3h_.js";import{createScreen as T}from"../packem_shared/createScreen-CrLrxA6t.js";import{waitFor as j}from"../packem_shared/waitFor-Dj5zfL5s.js";const b=F(import.meta.url),o=typeof globalThis<"u"&&typeof globalThis.process<"u"?globalThis.process:process,v=a(t=>{if(typeof o<"u"&&o.versions&&o.versions.node){const[e,i]=o.versions.node.split(".").map(Number);if(e>22||e===22&&i>=3||e===20&&i>=16)return o.getBuiltinModule(t)}return b(t)},"__cjs_getBuiltinModule"),l=v("node:events");var R=Object.defineProperty,r=a((t,e)=>R(t,"name",{value:e,configurable:!0}),"t");class S extends l{static{a(this,"v")}static{r(this,"Stdout")}columns;_lastFrame;_frames=[];constructor(e=100){super(),this.columns=e}get frames(){return this._frames}lastFrame(){return this._lastFrame}write=r(e=>(this._frames.push(e),this._lastFrame=e,!0),"write")}class D extends l{static{a(this,"x")}static{r(this,"Stderr")}columns;_lastFrame;_frames=[];constructor(e=100){super(),this.columns=e}get frames(){return this._frames}lastFrame(){return this._lastFrame}write=r(e=>(this._frames.push(e),this._lastFrame=e,!0),"write")}class P extends l{static{a(this,"R")}static{r(this,"Stdin")}isTTY=!0;pendingData;write=r(e=>(this.pendingData=e,this.emit("readable"),this.emit("data",e),!0),"write");read(){const{pendingData:e}=this;return this.pendingData=void 0,e}setEncoding(){return this}setRawMode(){return this}resume(){return this}pause(){return this}ref(){return this}unref(){return this}}const c=[],O=r((t,e={})=>{const{columns:i,options:p}=e,n=new S(i),d=new D(i),m=new P,u=x(t,{debug:!0,exitOnCtrlC:!1,patchConsole:!1,stderr:d,stdin:m,stdout:n,...p});c.push(u);const f=T(()=>n.lastFrame(),n.frames),h=y(s=>m.write(s)),_=r(async()=>{await new Promise(s=>{setTimeout(s,0)}),await new Promise(s=>{setTimeout(s,0)})},"flush");return{cleanup:u.cleanup,flush:_,get frames(){return n.frames},keys:h,lastFrame:r(()=>n.lastFrame(),"lastFrame"),rerender:u.rerender,screen:f,stderr:d,stdin:m,stdout:n,unmount:u.unmount,async waitFor(s,g){await j(s,()=>f.text(),g)}}},"testRender"),Y=r(()=>{for(const t of c)t.cleanup();c.length=0},"cleanup");export{$ as KEY,Y as cleanup,y as createKeySender,T as createScreen,O as render,j as waitFor};