@inquirer/testing 3.0.4 → 3.1.0

package/README.md

@@ -27,13 +27,20 @@ yarn add @inquirer/testing --dev
 </tr>
 </table>
 
-# Example
+# Usage
+
+This package provides two ways to test Inquirer prompts:
+
+1. **Unit testing** with `render()` - Test individual prompts in isolation
+2. **E2E testing** with `screen` - Test full CLI applications that use Inquirer
+
+## Unit Testing with `render()`
 
-Here's an example of a test running with Jest (though `@inquirer/testing` will work with any runners).
+The `render()` function creates and instruments a command line interface for testing a single prompt.
 
 ```ts
 import { render } from '@inquirer/testing';
-import input from './src/index.mjs';
+import input from '@inquirer/input';
 
 describe('input prompt', () => {
   it('handle simple use case', async () => {
@@ -48,7 +55,6 @@ describe('input prompt', () => {
 
     events.type('ohn');
     events.keypress('enter');
-    // or events.keypress({ name: 'enter' })
 
     await expect(answer).resolves.toEqual('John');
     expect(getScreen()).toMatchInlineSnapshot(`"? What is your name John"`);
@@ -56,23 +62,132 @@ describe('input prompt', () => {
 });
 ```
 
-# Usage
-
-The core utility of `@inquirer/testing` is the `render()` function. This `render` function will create and instrument a command line like interface.
+### `render()` API
 
 `render` takes 2 arguments:
 
 1. The Inquirer prompt to test (the return value of `createPrompt()`)
 2. The prompt configuration (the first prompt argument)
 
-`render` then returns a promise that will resolve once the prompt is rendered and the test environment up and running. This promise returns the utilities we'll use to interact with our tests:
+`render` returns a promise that resolves once the prompt is rendered. This promise returns:
+
+- `answer` (`Promise`) - Resolves when an answer is provided and valid
+- `getScreen` (`({ raw?: boolean }) => string`) - Returns the current screen content. By default strips ANSI codes
+- `events` - Utilities to interact with the prompt:
+  - `keypress(key: string | KeyObject)` - Trigger a keypress event
+  - `type(text: string)` - Type text into the prompt
+- `getFullOutput` (`() => Promise<string>`) - Returns the full output interpreted through a virtual terminal, resolving ANSI escape sequences into the actual screen state
+
+### Unit Testing Example
+
+You can refer to the [`@inquirer/input` test suite](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/input/input.test.ts) for a comprehensive unit testing example using `render()`.
+
+## E2E Testing with `screen`
+
+For testing full CLI applications that use Inquirer prompts internally, use the framework-specific entry points:
+
+### Vitest
+
+```ts
+import { describe, it, expect } from 'vitest';
+import { screen } from '@inquirer/testing/vitest';
+
+// Import your CLI AFTER @inquirer/testing/vitest
+import { runMyCli } from './my-cli.js';
+
+describe('my CLI', () => {
+  it('asks for name and confirms', async () => {
+    const result = runMyCli();
+
+    // First prompt is immediately available
+    expect(screen.getScreen()).toContain('What is your name?');
+    screen.type('John');
+    screen.keypress('enter');
+
+    // Wait for next prompt
+    await screen.next();
+    expect(screen.getScreen()).toContain('Confirm?');
+    screen.keypress('enter');
+
+    await result;
+  });
+});
+```
+
+### Jest
+
+```ts
+import { screen } from '@inquirer/testing/jest';
+import { runMyCli } from './my-cli.js';
+
+describe('my CLI', () => {
+  it('asks for name and confirms', async () => {
+    const result = runMyCli();
+
+    // First prompt is immediately available
+    expect(screen.getScreen()).toContain('What is your name?');
+    screen.type('John');
+    screen.keypress('enter');
+
+    // Wait for next prompt
+    await screen.next();
+    expect(screen.getScreen()).toContain('Confirm?');
+    screen.keypress('enter');
+
+    await result;
+  });
+});
+```
+
+### `screen` API
+
+The `screen` object provides:
+
+- `next()` - Wait for the next screen update (prompt transitions, validation errors, async updates). The initial prompt render is available immediately via `getScreen()` — no `next()` needed
+- `getScreen({ raw?: boolean })` - Get the current prompt screen content. By default strips ANSI codes
+- `getFullOutput({ raw?: boolean })` - Get all accumulated output interpreted through a virtual terminal (returns a `Promise`). By default resolves ANSI escape sequences into actual screen state
+- `type(text)` - Type text (writes to stream AND emits keypresses)
+- `keypress(key)` - Send a keypress event
+- `clear()` - Reset screen state (called automatically before each test)
+
+### Mocking Third-Party Prompts
+
+All `@inquirer/*` prompts are mocked automatically. To mock a third-party or custom prompt package, use `wrapPrompt` in your own mock call:
+
+#### Vitest
+
+```ts
+import { screen, wrapPrompt } from '@inquirer/testing/vitest';
+
+vi.mock('@my-company/custom-prompt', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@my-company/custom-prompt')>();
+  return { ...actual, default: wrapPrompt(actual.default) };
+});
+```
+
+#### Jest
+
+In Jest, `jest.mock()` factories are hoisted before imports, so `wrapPrompt` must be accessed via `jest.requireActual()` inside the factory:
+
+```ts
+import { screen } from '@inquirer/testing/jest';
+
+jest.mock('@my-company/custom-prompt', () => {
+  const { wrapPrompt } = jest.requireActual('@inquirer/testing/jest');
+  const actual = jest.requireActual('@my-company/custom-prompt');
+  return { ...actual, default: wrapPrompt(actual.default) };
+});
+```
+
+### Important Notes
+
+1. **Import order matters**: Import `@inquirer/testing/vitest` or `@inquirer/testing/jest` BEFORE importing modules that use Inquirer prompts
+2. **Editor prompt**: The external editor is mocked — `screen.type()` buffers text, and `screen.keypress('enter')` submits it (same pattern as other prompts). Works with both `waitForUserInput: true` and `false`
+3. **Sequential prompts**: Multiple prompts are supported, but they must run sequentially (not concurrently)
 
-1. `answer` (`Promise`) This is the promise that'll be resolved once an answer is provided and valid.
-2. `getScreen` (`({ raw: boolean }) => string`) This function returns the state of what is printed on the command line screen at any given time. You can use its return value to validate your prompt is properly rendered. By default this function will strip the ANSI codes (used for colors.)
-3. `events` (`{ keypress: (name | Key) => void, type: (string) => void }`) Is the utilities allowing you to interact with the prompt. Use it to trigger keypress events, or typing any input.
-4. `getFullOutput` (`() => string`) Return a raw dump of everything that got sent on the output stream.
+### E2E Testing Example
 
-You can refer to [the `@inquirer/input` prompt test suite](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/input/input.test.ts) as a practical example.
+You can refer to the [`@inquirer/demo` test suite](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/demo/demo.test.ts) for a comprehensive E2E testing example using `screen`.
 
 # License
 

package/dist/buffered-stream.d.ts

@@ -0,0 +1,12 @@
+import { Stream } from 'node:stream';
+export declare class BufferedStream extends Stream.Writable {
+    #private;
+    columns: number;
+    get writeCount(): number;
+    _write(chunk: Buffer, _encoding: string, callback: () => void): void;
+    getLastChunk({ raw }?: {
+        raw?: boolean;
+    }): string;
+    getFullOutput(): string;
+    clear(): void;
+}

package/dist/buffered-stream.js

@@ -0,0 +1,43 @@
+import { Stream } from 'node:stream';
+import { stripVTControlCharacters } from 'node:util';
+export class BufferedStream extends Stream.Writable {
+    // Expose a large column width so cli-width (used by @inquirer/core's breakLines)
+    // doesn't hard-wrap output at 80 columns. This prevents artificial line breaks
+    // that would break assertions like toContain() in tests.
+    columns = 10_000;
+    #fullOutput = '';
+    #chunks = [];
+    #rawChunks = [];
+    #writeCount = 0;
+    get writeCount() {
+        return this.#writeCount;
+    }
+    _write(chunk, _encoding, callback) {
+        const str = chunk.toString();
+        this.#fullOutput += str;
+        // Keep track of every chunk sent through.
+        this.#rawChunks.push(str);
+        // Stripping the ANSI codes here because Inquirer will push commands ANSI (like cursor move.)
+        // This is probably fine since we don't care about those for testing; but this could become
+        // an issue if we ever want to test for those.
+        if (stripVTControlCharacters(str).trim().length > 0) {
+            this.#chunks.push(str);
+            this.#writeCount++;
+            this.emit('render');
+        }
+        callback();
+    }
+    getLastChunk({ raw } = {}) {
+        const chunks = raw ? this.#rawChunks : this.#chunks;
+        const lastChunk = chunks.at(-1);
+        return lastChunk ?? '';
+    }
+    getFullOutput() {
+        return this.#fullOutput;
+    }
+    clear() {
+        this.#fullOutput = '';
+        this.#chunks = [];
+        this.#rawChunks = [];
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import MuteStream from 'mute-stream';
 import type { Prompt, Context } from '@inquirer/type';
-export declare function render<Value, const Config>(prompt: Prompt<Value, Config>, config: Config, options?: Context): Promise<{
+type RenderOptions = Omit<Context, 'input' | 'output'>;
+export declare function render<Value, const Config>(prompt: Prompt<Value, Config>, config: Config, options?: RenderOptions): Promise<{
     answer: Promise<Value>;
     input: MuteStream;
     events: {
@@ -15,5 +16,8 @@ export declare function render<Value, const Config>(prompt: Prompt<Value, Config
     getScreen: ({ raw }?: {
         raw?: boolean;
     }) => string;
-    getFullOutput: () => string;
+    getFullOutput: ({ raw }?: {
+        raw?: boolean;
+    }) => Promise<string>;
 }>;
+export {};

package/dist/index.js

@@ -1,40 +1,19 @@
-import { Stream } from 'node:stream';
 import { stripVTControlCharacters } from 'node:util';
 import MuteStream from 'mute-stream';
-class BufferedStream extends Stream.Writable {
-    #_fullOutput = '';
-    #_chunks = [];
-    #_rawChunks = [];
-    _write(chunk, _encoding, callback) {
-        const str = chunk.toString();
-        this.#_fullOutput += str;
-        // Keep track of every chunk send through.
-        this.#_rawChunks.push(str);
-        // Stripping the ANSI codes here because Inquirer will push commands ANSI (like cursor move.)
-        // This is probably fine since we don't care about those for testing; but this could become
-        // an issue if we ever want to test for those.
-        if (stripVTControlCharacters(str).trim().length > 0) {
-            this.#_chunks.push(str);
-        }
-        callback();
-    }
-    getLastChunk({ raw }) {
-        const chunks = raw ? this.#_rawChunks : this.#_chunks;
-        const lastChunk = chunks.at(-1);
-        return lastChunk ?? '';
-    }
-    getFullOutput() {
-        return this.#_fullOutput;
-    }
-}
+import { BufferedStream } from './buffered-stream.js';
+import { interpretTerminalOutput } from './terminal.js';
 export async function render(prompt, config, options) {
     const input = new MuteStream();
     input.unmute();
     const output = new BufferedStream();
-    const answer = prompt(config, { input, output, ...options });
-    // Wait for event listeners to be ready
-    await Promise.resolve();
-    await Promise.resolve();
+    const firstRender = new Promise((resolve) => output.once('render', resolve));
+    const answer = prompt(config, { ...options, input, output });
+    // The first render is synchronous. If our BufferedStream received a write, we're ready.
+    if (output.writeCount === 0) {
+        // Our BufferedStream didn't receive a write yet. This happens when the prompt
+        // errored before rendering. Race against the answer promise to handle that case.
+        await Promise.race([firstRender, answer.catch(() => { })]);
+    }
     const events = {
         keypress(key) {
             if (typeof key === 'string') {
@@ -59,8 +38,11 @@ export async function render(prompt, config, options) {
             const lastScreen = output.getLastChunk({ raw: Boolean(raw) });
             return raw ? lastScreen : stripVTControlCharacters(lastScreen).trim();
         },
-        getFullOutput: () => {
-            return output.getFullOutput();
+        getFullOutput: async ({ raw } = {}) => {
+            const fullOutput = output.getFullOutput();
+            if (raw)
+                return fullOutput;
+            return interpretTerminalOutput(fullOutput);
         },
     };
 }

package/dist/jest.d.ts

@@ -0,0 +1,19 @@
+import type { Prompt } from '@inquirer/type';
+import { Screen } from './screen.js';
+declare const screenInstance: Screen;
+export { screenInstance as screen };
+/**
+ * Wrap a prompt function to use the shared screen I/O.
+ * Use this in your own `jest.mock()` calls to mock third-party prompts.
+ *
+ * @example
+ * ```ts
+ * jest.mock('@my-company/custom-prompt', () => {
+ *   const { wrapPrompt } = jest.requireActual('@inquirer/testing/jest');
+ *   const actual = jest.requireActual('@my-company/custom-prompt');
+ *   return { ...actual, default: wrapPrompt(actual.default) };
+ * });
+ * ```
+ */
+export declare function wrapPrompt<Value, Config>(prompt: Prompt<Value, Config>): Prompt<Value, Config>;
+export { Screen, type KeypressEvent } from './screen.js';

package/dist/jest.js

@@ -0,0 +1,119 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access */
+// Note: Jest's requireActual returns `any` by design, unlike Vitest's typed importOriginal
+import { Screen } from './screen.js';
+// Global screen instance - exported for tests
+const screenInstance = new Screen();
+export { screenInstance as screen };
+// Reset before each test (Jest's beforeEach)
+beforeEach(() => {
+    screenInstance.clear();
+});
+/**
+ * Wrap a prompt function to use the shared screen I/O.
+ * Use this in your own `jest.mock()` calls to mock third-party prompts.
+ *
+ * @example
+ * ```ts
+ * jest.mock('@my-company/custom-prompt', () => {
+ *   const { wrapPrompt } = jest.requireActual('@inquirer/testing/jest');
+ *   const actual = jest.requireActual('@my-company/custom-prompt');
+ *   return { ...actual, default: wrapPrompt(actual.default) };
+ * });
+ * ```
+ */
+export function wrapPrompt(prompt) {
+    return (config, context) => {
+        const output = screenInstance.createOutput();
+        const promise = prompt(config, {
+            ...context,
+            input: screenInstance.input,
+            output,
+        });
+        screenInstance.setActivePromise(promise);
+        return promise;
+    };
+}
+// Mock individual prompt packages (covers `import input from '@inquirer/input'` style)
+jest.mock('@inquirer/input', () => {
+    const actual = jest.requireActual('@inquirer/input');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+jest.mock('@inquirer/select', () => {
+    const actual = jest.requireActual('@inquirer/select');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+jest.mock('@inquirer/confirm', () => {
+    const actual = jest.requireActual('@inquirer/confirm');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+jest.mock('@inquirer/checkbox', () => {
+    const actual = jest.requireActual('@inquirer/checkbox');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+jest.mock('@inquirer/password', () => {
+    const actual = jest.requireActual('@inquirer/password');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+jest.mock('@inquirer/expand', () => {
+    const actual = jest.requireActual('@inquirer/expand');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+jest.mock('@inquirer/rawlist', () => {
+    const actual = jest.requireActual('@inquirer/rawlist');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+jest.mock('@inquirer/number', () => {
+    const actual = jest.requireActual('@inquirer/number');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+jest.mock('@inquirer/search', () => {
+    const actual = jest.requireActual('@inquirer/search');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+jest.mock('@inquirer/editor', () => {
+    const actual = jest.requireActual('@inquirer/editor');
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+// Mock @inquirer/prompts barrel re-exports (covers `import { input } from '@inquirer/prompts'` style).
+// Jest's module mock for individual packages doesn't propagate through barrel re-exports.
+jest.mock('@inquirer/prompts', () => {
+    const actual = jest.requireActual('@inquirer/prompts');
+    return {
+        ...actual,
+        input: wrapPrompt(actual.input),
+        select: wrapPrompt(actual.select),
+        confirm: wrapPrompt(actual.confirm),
+        checkbox: wrapPrompt(actual.checkbox),
+        password: wrapPrompt(actual.password),
+        expand: wrapPrompt(actual.expand),
+        rawlist: wrapPrompt(actual.rawlist),
+        number: wrapPrompt(actual.number),
+        search: wrapPrompt(actual.search),
+        editor: wrapPrompt(actual.editor),
+    };
+});
+// Mock the external editor to capture typed input instead of spawning a real editor.
+// Buffers all screen.type() calls and submits on screen.keypress('enter'), matching
+// the interaction pattern of other prompts (type → enter).
+jest.mock('@inquirer/external-editor', () => ({
+    editAsync: (_text, callback) => {
+        let buffer = '';
+        const typeSpy = jest
+            .spyOn(screenInstance, 'type')
+            .mockImplementation((text) => {
+            buffer += text;
+        });
+        const keypressSpy = jest
+            .spyOn(screenInstance, 'keypress')
+            .mockImplementation((key) => {
+            const name = typeof key === 'string' ? key : key.name;
+            if (name === 'enter' || name === 'return') {
+                typeSpy.mockRestore();
+                keypressSpy.mockRestore();
+                process.nextTick(() => callback(undefined, buffer));
+            }
+        });
+    },
+}));
+// Re-export Screen class and KeypressEvent type for advanced use cases
+export { Screen } from './screen.js';

package/dist/screen.d.ts

@@ -0,0 +1,35 @@
+import MuteStream from 'mute-stream';
+import { BufferedStream } from './buffered-stream.js';
+export type KeypressEvent = {
+    name?: string;
+    ctrl?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+};
+export declare class Screen {
+    #private;
+    constructor();
+    get input(): MuteStream;
+    createOutput(): BufferedStream;
+    setActivePromise(promise: Promise<unknown>): void;
+    /**
+     * Wait for the next screen update.
+     *
+     * Handles re-renders within the same prompt (e.g., validation errors,
+     * async updates) and prompt transitions in multi-prompt flows
+     * (automatically waits for the next prompt).
+     *
+     * Note: The initial prompt render is available immediately via getScreen()
+     * — no next() call is needed before reading it.
+     */
+    next(): Promise<void>;
+    getScreen({ raw }?: {
+        raw?: boolean;
+    }): string;
+    getFullOutput({ raw }?: {
+        raw?: boolean;
+    }): Promise<string>;
+    keypress(key: string | KeypressEvent): void;
+    type(text: string): void;
+    clear(): void;
+}

package/dist/screen.js

@@ -0,0 +1,150 @@
+import { stripVTControlCharacters } from 'node:util';
+import MuteStream from 'mute-stream';
+import { BufferedStream } from './buffered-stream.js';
+import { interpretTerminalOutput } from './terminal.js';
+export class Screen {
+    #input;
+    #outputs = [];
+    #currentOutput = null;
+    #activePromise = null;
+    #rendersConsumed = 0;
+    #renderResolve = null;
+    constructor() {
+        this.#input = new MuteStream();
+        this.#input.unmute();
+    }
+    get input() {
+        return this.#input;
+    }
+    createOutput() {
+        const output = new BufferedStream();
+        this.#outputs.push(output);
+        this.#currentOutput = output;
+        this.#rendersConsumed = 0;
+        // Forward render events for cross-output listening
+        output.on('render', () => {
+            if (this.#renderResolve) {
+                this.#renderResolve();
+            }
+        });
+        return output;
+    }
+    setActivePromise(promise) {
+        this.#activePromise = promise;
+        // Auto-consume the initial render. Since createPrompt renders synchronously,
+        // getScreen() works immediately after starting a prompt — no next() needed.
+        this.#rendersConsumed = this.#currentOutput?.writeCount ?? 0;
+    }
+    /**
+     * Wait for the next screen update.
+     *
+     * Handles re-renders within the same prompt (e.g., validation errors,
+     * async updates) and prompt transitions in multi-prompt flows
+     * (automatically waits for the next prompt).
+     *
+     * Note: The initial prompt render is available immediately via getScreen()
+     * — no next() call is needed before reading it.
+     */
+    async next() {
+        if (this.#activePromise) {
+            const currentPromise = this.#activePromise;
+            // Consume any renders that happened synchronously (e.g., loading state).
+            // We want to wait for the next meaningful state change, not an intermediate render.
+            this.#rendersConsumed = this.#currentOutput?.writeCount ?? 0;
+            // Race: a future render (validation error, async update) vs the promise settling
+            // (prompt completed, possibly synchronously before any new render arrives).
+            const renderPromise = this.#waitForNextRender();
+            const settlePromise = currentPromise.then(() => 'settled', () => 'settled');
+            const result = await Promise.race([
+                renderPromise.then(() => 'render'),
+                settlePromise,
+            ]);
+            if (result === 'settled') {
+                if (this.#activePromise !== currentPromise) {
+                    // New prompt already started — its render was caught by the race's renderPromise.
+                    this.#rendersConsumed = this.#currentOutput?.writeCount ?? 0;
+                }
+                else {
+                    // Prompt settled but no new prompt yet. Wait for the next prompt's first render.
+                    await this.#waitForNextRender();
+                }
+            }
+            else {
+                // Got a render. Check if the prompt also completed (making this a "done" render).
+                // Microtasks (promise settlement) always drain before macrotasks (setImmediate),
+                // so if the prompt resolved, its .then wins the race.
+                const settled = await Promise.race([
+                    currentPromise.then(() => true, () => true),
+                    new Promise((resolve) => setImmediate(() => resolve(false))),
+                ]);
+                if (settled) {
+                    if (this.#activePromise !== currentPromise) {
+                        // New prompt already started — its render was caught by the race.
+                        this.#rendersConsumed = this.#currentOutput?.writeCount ?? 0;
+                    }
+                    else {
+                        // Prompt completed but no new prompt yet. Wait for it.
+                        await this.#waitForNextRender();
+                    }
+                }
+            }
+        }
+        else {
+            // No active promise — wait for a render (e.g., prompt hasn't started yet)
+            await this.#waitForNextRender();
+        }
+    }
+    async #waitForNextRender() {
+        const writeCount = this.#currentOutput?.writeCount ?? 0;
+        if (writeCount > this.#rendersConsumed) {
+            this.#rendersConsumed = writeCount;
+            return;
+        }
+        await new Promise((resolve) => {
+            const handler = () => {
+                this.#renderResolve = null;
+                resolve();
+            };
+            // Listen on current output (for re-renders within same prompt)
+            this.#currentOutput?.once('render', handler);
+            // Also set up cross-output listener (for prompt transitions and initial render)
+            this.#renderResolve = handler;
+        });
+        this.#rendersConsumed = this.#currentOutput?.writeCount ?? 0;
+    }
+    getScreen({ raw } = {}) {
+        const lastScreen = this.#currentOutput?.getLastChunk({ raw: Boolean(raw) }) ?? '';
+        return raw ? lastScreen : stripVTControlCharacters(lastScreen).trim();
+    }
+    async getFullOutput({ raw } = {}) {
+        const output = this.#outputs.map((o) => o.getFullOutput()).join('');
+        if (raw)
+            return output;
+        return interpretTerminalOutput(output);
+    }
+    keypress(key) {
+        if (typeof key === 'string') {
+            this.#input.emit('keypress', null, { name: key });
+        }
+        else {
+            this.#input.emit('keypress', null, key);
+        }
+    }
+    type(text) {
+        this.#input.write(text);
+        for (const char of text) {
+            this.#input.emit('keypress', null, { name: char });
+        }
+    }
+    clear() {
+        // Recreate input stream to ensure clean state
+        this.#input = new MuteStream();
+        this.#input.unmute();
+        // Reset output tracking
+        this.#outputs = [];
+        this.#currentOutput = null;
+        this.#activePromise = null;
+        this.#rendersConsumed = 0;
+        this.#renderResolve = null;
+    }
+}

package/dist/terminal.d.ts

@@ -0,0 +1 @@
+export declare function interpretTerminalOutput(rawOutput: string, cols?: number, rows?: number): Promise<string>;

package/dist/terminal.js

@@ -0,0 +1,15 @@
+import { Terminal } from '@xterm/headless';
+export async function interpretTerminalOutput(rawOutput, cols = 10_000, rows = 4000) {
+    const term = new Terminal({ cols, rows, allowProposedApi: true, convertEol: true });
+    await new Promise((resolve) => term.write(rawOutput, resolve));
+    const lines = [];
+    for (let i = 0; i < term.rows; i++) {
+        lines.push(term.buffer.active.getLine(i)?.translateToString(true) ?? '');
+    }
+    term.dispose();
+    // Trim trailing empty lines
+    while (lines.length > 0 && lines.at(-1) === '') {
+        lines.pop();
+    }
+    return lines.join('\n');
+}

package/dist/vitest.d.ts

@@ -0,0 +1,20 @@
+import type { Prompt } from '@inquirer/type';
+import { Screen } from './screen.js';
+declare const screenInstance: Screen;
+export { screenInstance as screen };
+/**
+ * Wrap a prompt function to use the shared screen I/O.
+ * Use this in your own `vi.mock()` calls to mock third-party prompts.
+ *
+ * @example
+ * ```ts
+ * import { wrapPrompt } from '@inquirer/testing/vitest';
+ *
+ * vi.mock('@my-company/custom-prompt', async (importOriginal) => {
+ *   const actual = await importOriginal<typeof import('@my-company/custom-prompt')>();
+ *   return { ...actual, default: wrapPrompt(actual.default) };
+ * });
+ * ```
+ */
+export declare function wrapPrompt<Value, Config>(prompt: Prompt<Value, Config>): Prompt<Value, Config>;
+export { Screen, type KeypressEvent } from './screen.js';

package/dist/vitest.js

@@ -0,0 +1,118 @@
+import { vi, beforeEach } from 'vitest';
+import { Screen } from './screen.js';
+// Global screen instance - exported for tests
+const screenInstance = new Screen();
+export { screenInstance as screen };
+// Reset before each test
+beforeEach(() => {
+    screenInstance.clear();
+});
+/**
+ * Wrap a prompt function to use the shared screen I/O.
+ * Use this in your own `vi.mock()` calls to mock third-party prompts.
+ *
+ * @example
+ * ```ts
+ * import { wrapPrompt } from '@inquirer/testing/vitest';
+ *
+ * vi.mock('@my-company/custom-prompt', async (importOriginal) => {
+ *   const actual = await importOriginal<typeof import('@my-company/custom-prompt')>();
+ *   return { ...actual, default: wrapPrompt(actual.default) };
+ * });
+ * ```
+ */
+export function wrapPrompt(prompt) {
+    return (config, context) => {
+        const output = screenInstance.createOutput();
+        const promise = prompt(config, {
+            ...context,
+            input: screenInstance.input,
+            output,
+        });
+        screenInstance.setActivePromise(promise);
+        return promise;
+    };
+}
+// Mock individual prompt packages (covers `import input from '@inquirer/input'` style)
+vi.mock('@inquirer/input', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+vi.mock('@inquirer/select', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+vi.mock('@inquirer/confirm', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+vi.mock('@inquirer/checkbox', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+vi.mock('@inquirer/password', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+vi.mock('@inquirer/expand', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+vi.mock('@inquirer/rawlist', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+vi.mock('@inquirer/number', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+vi.mock('@inquirer/search', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+vi.mock('@inquirer/editor', async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, default: wrapPrompt(actual.default) };
+});
+// Mock @inquirer/prompts barrel re-exports (covers `import { input } from '@inquirer/prompts'` style).
+// While Vitest's module interception often propagates through ESM re-exports, an explicit mock
+// ensures consistent behavior across all environments and bundler configurations.
+vi.mock('@inquirer/prompts', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        input: wrapPrompt(actual.input),
+        select: wrapPrompt(actual.select),
+        confirm: wrapPrompt(actual.confirm),
+        checkbox: wrapPrompt(actual.checkbox),
+        password: wrapPrompt(actual.password),
+        expand: wrapPrompt(actual.expand),
+        rawlist: wrapPrompt(actual.rawlist),
+        number: wrapPrompt(actual.number),
+        search: wrapPrompt(actual.search),
+        editor: wrapPrompt(actual.editor),
+    };
+});
+// Mock the external editor to capture typed input instead of spawning a real editor.
+// Buffers all screen.type() calls and submits on screen.keypress('enter'), matching
+// the interaction pattern of other prompts (type → enter).
+vi.mock('@inquirer/external-editor', () => ({
+    editAsync: (_text, callback) => {
+        let buffer = '';
+        const typeSpy = vi
+            .spyOn(screenInstance, 'type')
+            .mockImplementation((text) => {
+            buffer += text;
+        });
+        const keypressSpy = vi.spyOn(screenInstance, 'keypress').mockImplementation((key) => {
+            const name = typeof key === 'string' ? key : key.name;
+            if (name === 'enter' || name === 'return') {
+                typeSpy.mockRestore();
+                keypressSpy.mockRestore();
+                process.nextTick(() => callback(undefined, buffer));
+            }
+        });
+    },
+}));
+// Re-export Screen class and KeypressEvent type for advanced use cases
+export { Screen } from './screen.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inquirer/testing",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "Inquirer testing utilities",
   "keywords": [
     "answer",
@@ -55,12 +55,25 @@
     "dist"
   ],
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/vitest.ts",
+    "./src/jest.ts",
+    "./dist/vitest.js",
+    "./dist/jest.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./vitest": {
+      "types": "./dist/vitest.d.ts",
+      "default": "./dist/vitest.js"
+    },
+    "./jest": {
+      "types": "./dist/jest.d.ts",
+      "default": "./dist/jest.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -71,19 +84,34 @@
   },
   "dependencies": {
     "@inquirer/type": "^4.0.3",
+    "@xterm/headless": "^5.5.0",
     "mute-stream": "^3.0.0"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.0",
     "@types/mute-stream": "^0.0.4",
     "@types/node": "^25.0.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "@types/node": ">=18"
+    "@types/jest": ">=29.0.0",
+    "@types/node": ">=18",
+    "jest": ">=29.0.0",
+    "vitest": ">=1.0.0"
   },
   "peerDependenciesMeta": {
+    "@types/jest": {
+      "optional": true
+    },
     "@types/node": {
       "optional": true
+    },
+    "jest": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
   },
   "engines": {
@@ -91,5 +119,5 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "gitHead": "99d00a9adc53be8b7edf5926b2ec4ba0b792f68f"
+  "gitHead": "53dbf6c492883546f6f9f2d5b9a78cbc00bd434c"
 }