@reliverse/rempts-test 2.3.1

package/README.md

@@ -0,0 +1,264 @@
+# rempts-test
+
+Testing utilities for Rempts CLI applications.
+
+## Installation
+
+```bash
+bun add -d rempts-test
+```
+
+## Features
+
+- 🧪 Test individual commands or entire CLIs
+- 🎭 Mock user prompts and shell commands
+- ✅ Built-in test matchers for CLI output
+- 🔄 Support for validation and retry scenarios
+- 📝 TypeScript support with full type inference
+
+## Usage
+
+### Basic Command Testing
+
+```typescript
+import { test, expect } from 'bun:test'
+import { defineCommand } from '@reliverse/rempts-core'
+import { testCommand, expectCommand } from '@reliverse/rempts-test'
+
+const greetCommand = defineCommand({
+  name: 'greet',
+  description: 'Greet someone',
+  handler: async ({ colors }) => {
+    console.log(relico.green('Hello, world!'))
+  }
+})
+
+test('greet command', async () => {
+  const result = await testCommand(greetCommand)
+
+  expectCommand(result).toHaveSucceeded()
+  expectCommand(result).toContainInStdout('[green]Hello, world![/green]')
+})
+```
+
+### Testing with Flags
+
+```typescript
+const deployCommand = defineCommand({
+  name: 'deploy',
+  options: {
+    env: option(z.enum(['dev', 'prod'])),
+    force: option(z.boolean().default(false))
+  },
+  handler: async ({ flags }) => {
+    console.log(`Deploying to ${flags.env}${flags.force ? ' (forced)' : ''}`)
+  }
+})
+
+test('deploy with flags', async () => {
+  const result = await testCommand(deployCommand, {
+    flags: { env: 'prod', force: true }
+  })
+
+  expect(result.stdout).toContain('Deploying to prod (forced)')
+})
+```
+
+### Mocking User Prompts
+
+```typescript
+import { mockPromptResponses } from '@reliverse/rempts-test'
+
+const setupCommand = defineCommand({
+  name: 'setup',
+  handler: async ({ prompt }) => {
+    const name = await prompt('Project name:')
+    const useTs = await prompt.confirm('Use TypeScript?')
+    console.log(`Creating ${name} with${useTs ? '' : 'out'} TypeScript`)
+  }
+})
+
+test('interactive setup', async () => {
+  const result = await testCommand(setupCommand, mockPromptResponses({
+    'Project name:': 'my-app',
+    'Use TypeScript?': 'y'
+  }))
+
+  expect(result.stdout).toContain('Creating my-app with TypeScript')
+})
+```
+
+### Mocking Shell Commands
+
+```typescript
+import { mockShellCommands } from '@reliverse/rempts-test'
+
+const statusCommand = defineCommand({
+  name: 'status',
+  handler: async ({ shell }) => {
+    const branch = await shell`git branch --show-current`.text()
+    const status = await shell`git status --porcelain`.text()
+    console.log(`On branch: ${branch.trim()}`)
+    console.log(`Clean: ${status.trim() === ''}`)
+  }
+})
+
+test('git status', async () => {
+  const result = await testCommand(statusCommand, mockShellCommands({
+    'git branch --show-current': 'feature/awesome\n',
+    'git status --porcelain': ''
+  }))
+
+  expect(result.stdout).toContain('On branch: feature/awesome')
+  expect(result.stdout).toContain('Clean: true')
+})
+```
+
+### Testing Validation with Retries
+
+```typescript
+const emailCommand = defineCommand({
+  name: 'register',
+  handler: async ({ prompt }) => {
+    const email = await prompt('Enter email:', {
+      schema: z.string().email()
+    })
+    console.log(`Registered: ${email}`)
+  }
+})
+
+test('email validation', async () => {
+  const result = await testCommand(emailCommand, mockPromptResponses({
+    'Enter email:': ['invalid', 'still-bad', 'valid@email.com']
+  }))
+
+  // First two attempts fail validation
+  expect(result.stderr).toContain('Invalid email')
+  // Third attempt succeeds
+  expect(result.stdout).toContain('Registered: valid@email.com')
+})
+```
+
+### Testing Complete CLIs
+
+```typescript
+import { createCLI } from '@reliverse/rempts-core'
+import { testCLI } from '@reliverse/rempts-test'
+
+test('CLI help', async () => {
+  const result = await testCLI(
+    (cli) => {
+      cli.command('hello', {
+        description: 'Say hello',
+        handler: async () => console.log('Hello!')
+      })
+    },
+    ['--help']
+  )
+
+  expectCommand(result).toContainInStdout('Say hello')
+})
+```
+
+### Using Helper Functions
+
+```typescript
+import { mockInteractive, mergeTestOptions } from '@reliverse/rempts-test'
+
+test('complex interaction', async () => {
+  const result = await testCommand(myCommand, mockInteractive(
+    {
+      'Name:': 'Alice',
+      'Continue?': 'y'
+    },
+    {
+      'npm --version': '10.0.0\n'
+    }
+  ))
+
+  // Or merge multiple option sets
+  const result2 = await testCommand(myCommand, mergeTestOptions(
+    { flags: { verbose: true } },
+    mockPromptResponses({ 'Name:': 'Bob' }),
+    { env: { NODE_ENV: 'test' } }
+  ))
+})
+```
+
+## Test Matchers
+
+The `expectCommand` function provides CLI-specific test matchers:
+
+```typescript
+// Exit code assertions
+expectCommand(result).toHaveExitCode(0)
+expectCommand(result).toHaveSucceeded()    // exit code 0
+expectCommand(result).toHaveFailed()       // exit code !== 0
+
+// Output assertions
+expectCommand(result).toContainInStdout('success')
+expectCommand(result).toContainInStderr('error')
+expectCommand(result).toMatchStdout(/pattern/)
+expectCommand(result).toMatchStderr(/error.*occurred/)
+```
+
+## API Reference
+
+### `testCommand(command, options?)`
+
+Test a single command.
+
+**Parameters:**
+
+- `command`: Command to test
+- `options`: Test options
+  - `flags`: Command flags
+  - `args`: Positional arguments
+  - `env`: Environment variables
+  - `cwd`: Working directory
+  - `stdin`: Input lines (string or array)
+  - `mockPrompts`: Map of prompt messages to responses
+  - `mockShellCommands`: Map of shell commands to outputs
+  - `exitCode`: Expected exit code
+
+**Returns:** `TestResult` with stdout, stderr, exitCode, duration, and error
+
+### `testCLI(setupFn, argv, options?)`
+
+Test a complete CLI with multiple commands.
+
+**Parameters:**
+
+- `setupFn`: Function to configure the CLI
+- `argv`: Command line arguments
+- `options`: Test options (same as testCommand)
+
+### Helper Functions
+
+- `mockPromptResponses(responses)`: Create options with mock prompt responses
+- `mockShellCommands(commands)`: Create options with mock shell outputs
+- `mockInteractive(prompts, commands?)`: Combine prompt and shell mocks
+- `mockValidationAttempts(attempts)`: Create stdin for validation testing
+- `mergeTestOptions(...options)`: Merge multiple test option objects
+
+## Tips
+
+1. **Colors in Output**: The test utilities preserve color codes as tags (e.g., `[green]text[/green]`) for easier assertion
+
+2. **Multiple Attempts**: For validation scenarios, provide arrays of responses:
+
+   ```typescript
+   mockPromptResponses({
+     'Enter age:': ['abc', '-5', '25']  // Tries each until valid
+   })
+   ```
+
+3. **Default Mocks**: Common commands have default mock responses:
+   - `git branch --show-current`: Returns `main\n`
+   - `git status`: Returns `nothing to commit, working tree clean\n`
+
+4. **Schema Validation**: The mock prompt automatically handles Standard Schema validation and retry logic
+
+## License
+
+MIT

package/dist/helpers.d.ts

@@ -0,0 +1,53 @@
+import type { TestOptions } from "./types.js";
+/**
+ * Helper to create test options with mock prompt responses
+ * @param responses - Map of prompt messages to responses
+ * @example
+ * mockPromptResponses({
+ *   'Enter name:': 'Alice',
+ *   'Enter age:': ['invalid', '25'], // Multiple attempts for validation
+ *   'Continue?': 'y'
+ * })
+ */
+export declare function mockPromptResponses(responses: Record<string, string | string[]>): Pick<TestOptions, "mockPrompts">;
+/**
+ * Helper to create test options with mock shell command outputs
+ * @param commands - Map of shell commands to their outputs
+ * @example
+ * mockShellCommands({
+ *   'git status': 'On branch main\nnothing to commit',
+ *   'npm --version': '10.2.0',
+ *   'node --version': 'v20.10.0'
+ * })
+ */
+export declare function mockShellCommands(commands: Record<string, string>): Pick<TestOptions, "mockShellCommands">;
+/**
+ * Helper to create test options for interactive commands
+ * @param prompts - Prompt responses
+ * @param commands - Shell command outputs
+ * @example
+ * mockInteractive(
+ *   { 'Name:': 'Alice', 'Continue?': 'y' },
+ *   { 'git status': 'clean' }
+ * )
+ */
+export declare function mockInteractive(prompts: Record<string, string | string[]>, commands?: Record<string, string>): TestOptions;
+/**
+ * Helper to create stdin input for validation testing
+ * Useful for testing retry behavior with invalid inputs
+ * @param attempts - Array of input attempts
+ * @example
+ * mockValidationAttempts(['invalid-email', 'still-bad', 'valid@email.com'])
+ */
+export declare function mockValidationAttempts(attempts: string[]): Pick<TestOptions, "stdin">;
+/**
+ * Helper to combine multiple test option objects
+ * @param options - Test option objects to merge
+ * @example
+ * mergeTestOptions(
+ *   { flags: { verbose: true } },
+ *   mockPromptResponses({ 'Name:': 'Alice' }),
+ *   { env: { NODE_ENV: 'test' } }
+ * )
+ */
+export declare function mergeTestOptions(...options: Partial<TestOptions>[]): TestOptions;

package/dist/helpers.js

@@ -0,0 +1,42 @@
+export function mockPromptResponses(responses) {
+  return { mockPrompts: responses };
+}
+export function mockShellCommands(commands) {
+  return { mockShellCommands: commands };
+}
+export function mockInteractive(prompts, commands) {
+  return {
+    ...mockPromptResponses(prompts),
+    ...commands ? mockShellCommands(commands) : {}
+  };
+}
+export function mockValidationAttempts(attempts) {
+  return { stdin: attempts };
+}
+export function mergeTestOptions(...options) {
+  const merged = {};
+  for (const opt of options) {
+    if (opt.stdin || opt.mockPrompts) {
+      const stdinArray = [];
+      if (merged.stdin) {
+        if (Array.isArray(merged.stdin)) {
+          stdinArray.push(...merged.stdin);
+        } else {
+          stdinArray.push(merged.stdin);
+        }
+      }
+      if (opt.stdin) {
+        if (Array.isArray(opt.stdin)) {
+          stdinArray.push(...opt.stdin);
+        } else {
+          stdinArray.push(opt.stdin);
+        }
+      }
+      if (stdinArray.length > 0) {
+        merged.stdin = stdinArray;
+      }
+    }
+    Object.assign(merged, opt);
+  }
+  return merged;
+}

package/dist/matchers.d.ts

@@ -0,0 +1,38 @@
+import type { TestResult } from "./types.js";
+export interface Matchers {
+    toHaveExitCode(code: number): void;
+    toHaveSucceeded(): void;
+    toHaveFailed(): void;
+    toContainInStdout(text: string): void;
+    toContainInStderr(text: string): void;
+    toMatchStdout(pattern: RegExp): void;
+    toMatchStderr(pattern: RegExp): void;
+}
+export declare function createMatchers(result: TestResult): Matchers;
+declare global {
+    namespace jest {
+        interface Matchers<R> {
+            toHaveExitCode(code: number): R;
+            toHaveSucceeded(): R;
+            toHaveFailed(): R;
+            toContainInStdout(text: string): R;
+            toContainInStderr(text: string): R;
+            toMatchStdout(pattern: RegExp): R;
+            toMatchStderr(pattern: RegExp): R;
+        }
+    }
+}
+export declare function expectCommand(result: TestResult): {
+    toHaveExitCode(code: number): void;
+    toHaveSucceeded(): void;
+    toHaveFailed(): void;
+    toContainInStdout(text: string): void;
+    toContainInStderr(text: string): void;
+    toMatchStdout(pattern: RegExp): void;
+    toMatchStderr(pattern: RegExp): void;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    duration: number;
+    error?: Error;
+};

package/dist/matchers.js

@@ -0,0 +1,62 @@
+export function createMatchers(result) {
+  return {
+    toHaveExitCode(code) {
+      if (result.exitCode !== code) {
+        throw new Error(
+          `Expected exit code ${code}, but got ${result.exitCode}
+stdout: ${result.stdout}
+stderr: ${result.stderr}`
+        );
+      }
+    },
+    toHaveSucceeded() {
+      if (result.exitCode !== 0) {
+        throw new Error(
+          `Expected command to succeed (exit code 0), but got ${result.exitCode}
+stdout: ${result.stdout}
+stderr: ${result.stderr}
+` + (result.error ? `error: ${result.error.message}` : "")
+        );
+      }
+    },
+    toHaveFailed() {
+      if (result.exitCode === 0) {
+        throw new Error(
+          `Expected command to fail (non-zero exit code), but it succeeded
+stdout: ${result.stdout}`
+        );
+      }
+    },
+    toContainInStdout(text) {
+      if (!result.stdout.includes(text)) {
+        throw new Error(`Expected stdout to contain "${text}"
+stdout: ${result.stdout}`);
+      }
+    },
+    toContainInStderr(text) {
+      if (!result.stderr.includes(text)) {
+        throw new Error(`Expected stderr to contain "${text}"
+stderr: ${result.stderr}`);
+      }
+    },
+    toMatchStdout(pattern) {
+      if (!pattern.test(result.stdout)) {
+        throw new Error(`Expected stdout to match ${pattern}
+stdout: ${result.stdout}`);
+      }
+    },
+    toMatchStderr(pattern) {
+      if (!pattern.test(result.stderr)) {
+        throw new Error(`Expected stderr to match ${pattern}
+stderr: ${result.stderr}`);
+      }
+    }
+  };
+}
+export function expectCommand(result) {
+  const matchers = createMatchers(result);
+  return {
+    ...result,
+    ...matchers
+  };
+}

package/dist/mod.d.ts

@@ -0,0 +1,4 @@
+export { mergeTestOptions, mockInteractive, mockPromptResponses, mockShellCommands, mockValidationAttempts, } from "./helpers.js";
+export { createMatchers, expectCommand } from "./matchers.js";
+export { testCLI, testCommand } from "./test-command.js";
+export type { Matchers, MockHandlerArgs, MockShell, ShellPromise, TestOptions, TestResult, } from "./types.js";

package/dist/mod.js

@@ -0,0 +1,9 @@
+export {
+  mergeTestOptions,
+  mockInteractive,
+  mockPromptResponses,
+  mockShellCommands,
+  mockValidationAttempts
+} from "./helpers.js";
+export { createMatchers, expectCommand } from "./matchers.js";
+export { testCLI, testCommand } from "./test-command.js";

package/dist/test-command.d.ts

@@ -0,0 +1,4 @@
+import type { CLI, Command } from "@reliverse/rempts-core";
+import type { TestOptions, TestResult } from "./types.js";
+export declare function testCommand(command: Command<any>, options?: TestOptions): Promise<TestResult>;
+export declare function testCLI(setupCLI: (cli: CLI) => void, argv: string[], _options?: Omit<TestOptions, "args">): Promise<TestResult>;

package/dist/test-command.js

@@ -0,0 +1,360 @@
+import { createCLI } from "@reliverse/rempts-core";
+export async function testCommand(command, options = {}) {
+  const startTime = performance.now();
+  const stdout = [];
+  const stderr = [];
+  let exitCode = 0;
+  let error;
+  const stdinLines = Array.isArray(options.stdin) ? [...options.stdin] : options.stdin ? [options.stdin] : [];
+  const mockPromptsMap = options.mockPrompts || {};
+  const promptResponsesUsed = /* @__PURE__ */ new Map();
+  const mockPrompt = Object.assign(
+    async (message, options2) => {
+      stdout.push(message);
+      let response;
+      if (mockPromptsMap[message]) {
+        const responses = mockPromptsMap[message];
+        const usedCount = promptResponsesUsed.get(message) || 0;
+        if (Array.isArray(responses)) {
+          response = responses[usedCount] ?? responses.at(-1) ?? "";
+          promptResponsesUsed.set(message, usedCount + 1);
+        } else {
+          response = responses ?? "";
+        }
+      } else {
+        response = stdinLines.shift() || "";
+      }
+      stdout.push(response);
+      if (options2?.schema) {
+        const result = await options2.schema["~standard"].validate(response);
+        if (result.issues) {
+          stderr.push("[red]Invalid input:[/red]");
+          for (const issue of result.issues) {
+            stderr.push(`[dim]  \u2022 ${issue.message}[/dim]`);
+          }
+          const hasMoreMockResponses = mockPromptsMap[message] && Array.isArray(mockPromptsMap[message]) && (promptResponsesUsed.get(message) || 0) < mockPromptsMap[message].length;
+          const hasMoreStdin = stdinLines.length > 0;
+          if (hasMoreMockResponses || hasMoreStdin) {
+            return mockPrompt(message, options2);
+          }
+          return void 0;
+        }
+        return result.value;
+      }
+      if (options2?.validate) {
+        const validationResult = options2.validate(response);
+        if (validationResult !== true) {
+          const errorMsg = typeof validationResult === "string" ? validationResult : "Invalid input";
+          stderr.push(`\u2717 ${errorMsg}`);
+          if (stdinLines.length > 0) {
+            return mockPrompt(message, options2);
+          }
+        }
+      }
+      return response;
+    },
+    {
+      confirm: async (message, opts) => {
+        stdout.push(message);
+        let response;
+        if (mockPromptsMap[message]) {
+          const responses = mockPromptsMap[message];
+          const usedCount = promptResponsesUsed.get(message) || 0;
+          if (Array.isArray(responses)) {
+            response = responses[usedCount] ?? responses.at(-1) ?? "";
+            promptResponsesUsed.set(message, usedCount + 1);
+          } else {
+            response = responses ?? "";
+          }
+        } else {
+          response = stdinLines.shift() || "";
+        }
+        stdout.push(response);
+        const normalized = response.toLowerCase().trim();
+        return normalized === "y" || normalized === "yes" || opts?.default && normalized === "";
+      },
+      select: async (message, selectOptions) => {
+        stdout.push(message);
+        selectOptions.options.forEach((choice2, i) => {
+          const label = typeof choice2 === "object" ? choice2.label : choice2;
+          stdout.push(`  ${i + 1}. ${label}`);
+        });
+        let response;
+        if (mockPromptsMap[message]) {
+          const responses = mockPromptsMap[message];
+          const usedCount = promptResponsesUsed.get(message) || 0;
+          if (Array.isArray(responses)) {
+            response = responses[usedCount] ?? responses.at(-1) ?? "";
+            promptResponsesUsed.set(message, usedCount + 1);
+          } else {
+            response = responses ?? "";
+          }
+        } else {
+          response = stdinLines.shift() || "1";
+        }
+        stdout.push(`> ${response}`);
+        const index = Number.parseInt(response, 10) - 1;
+        const choice = selectOptions.options[index] || selectOptions.options[0];
+        return typeof choice === "object" ? choice.value : choice;
+      },
+      password: async (message, options2) => {
+        stdout.push(message);
+        let response;
+        if (mockPromptsMap[message]) {
+          const responses = mockPromptsMap[message];
+          const usedCount = promptResponsesUsed.get(message) || 0;
+          if (Array.isArray(responses)) {
+            response = responses[usedCount] ?? responses.at(-1) ?? "";
+            promptResponsesUsed.set(message, usedCount + 1);
+          } else {
+            response = responses ?? "";
+          }
+        } else {
+          response = stdinLines.shift() || "";
+        }
+        stdout.push("*".repeat(response.length));
+        if (options2?.schema) {
+          const result = await options2.schema["~standard"].validate(response);
+          if (result.issues) {
+            stderr.push("[red]Invalid input:[/red]");
+            for (const issue of result.issues) {
+              stderr.push(`[dim]  \u2022 ${issue.message}[/dim]`);
+            }
+            const hasMoreMockResponses = mockPromptsMap[message] && Array.isArray(mockPromptsMap[message]) && (promptResponsesUsed.get(message) || 0) < mockPromptsMap[message].length;
+            const hasMoreStdin = stdinLines.length > 0;
+            if (hasMoreMockResponses || hasMoreStdin) {
+              return mockPrompt.password(message, options2);
+            }
+            return void 0;
+          }
+          return result.value;
+        }
+        return response;
+      },
+      multiselect: async (message, selectOptions) => {
+        stdout.push(message);
+        selectOptions.options.forEach((choice, i) => {
+          const label = typeof choice === "object" ? choice.label : choice;
+          stdout.push(`  [ ] ${i + 1}. ${label}`);
+        });
+        let response;
+        if (mockPromptsMap[message]) {
+          const responses = mockPromptsMap[message];
+          const usedCount = promptResponsesUsed.get(message) || 0;
+          if (Array.isArray(responses)) {
+            response = responses[usedCount] ?? responses.at(-1) ?? "";
+            promptResponsesUsed.set(message, usedCount + 1);
+          } else {
+            response = responses ?? "";
+          }
+        } else {
+          response = stdinLines.shift() || "";
+        }
+        stdout.push(`> ${response}`);
+        const indices = response.split(",").map((s) => Number.parseInt(s.trim(), 10) - 1);
+        return indices.filter((i) => i >= 0 && i < selectOptions.options.length).map((i) => {
+          const choice = selectOptions.options[i];
+          return typeof choice === "object" ? choice.value : choice;
+        });
+      }
+    }
+  );
+  const mockSpinner = (text) => {
+    if (text) {
+      stdout.push(`\u280B ${text}`);
+    }
+    return {
+      start: (text2) => {
+        if (text2) {
+          stdout.push(`\u280B ${text2}`);
+        }
+      },
+      stop: (text2) => {
+        if (text2) {
+          stdout.push(text2);
+        }
+      },
+      succeed: (text2) => {
+        stdout.push(`\u2705 ${text2 || "Done"}`);
+      },
+      fail: (text2) => {
+        stdout.push(`\u274C ${text2 || "Failed"}`);
+      },
+      warn: (text2) => {
+        stdout.push(`\u26A0\uFE0F  ${text2 || "Warning"}`);
+      },
+      info: (text2) => {
+        stdout.push(`\u2139\uFE0F  ${text2 || "Info"}`);
+      },
+      update: (text2) => {
+        stdout.push(`\u280B ${text2}`);
+      }
+    };
+  };
+  const mockShellCommands = options.mockShellCommands || {};
+  const mockShell = (strings, ...values) => {
+    const command2 = strings.reduce((acc, str, i) => {
+      return acc + str + (values[i] || "");
+    }, "").trim();
+    stdout.push(`$ ${command2}`);
+    const promise = Promise.resolve();
+    promise.text = async () => {
+      if (mockShellCommands[command2]) {
+        return mockShellCommands[command2];
+      }
+      if (command2.includes("git branch --show-current")) {
+        return "main\n";
+      }
+      if (command2.includes("git status")) {
+        return "nothing to commit, working tree clean\n";
+      }
+      return "";
+    };
+    promise.json = async () => {
+      if (mockShellCommands[command2]) {
+        try {
+          return JSON.parse(mockShellCommands[command2]);
+        } catch {
+          return {};
+        }
+      }
+      return {};
+    };
+    promise.quiet = () => promise;
+    return promise;
+  };
+  const mockColors = {
+    red: (text) => `[red]${text}[/red]`,
+    green: (text) => `[green]${text}[/green]`,
+    blue: (text) => `[blue]${text}[/blue]`,
+    yellow: (text) => `[yellow]${text}[/yellow]`,
+    cyan: (text) => `[cyan]${text}[/cyan]`,
+    magenta: (text) => `[magenta]${text}[/magenta]`,
+    gray: (text) => `[gray]${text}[/gray]`,
+    dim: (text) => `[dim]${text}[/dim]`,
+    bold: (text) => `[bold]${text}[/bold]`,
+    italic: (text) => `[italic]${text}[/italic]`,
+    underline: (text) => `[underline]${text}[/underline]`,
+    strikethrough: (text) => `[strikethrough]${text}[/strikethrough]`,
+    bgRed: (text) => `[bgRed]${text}[/bgRed]`,
+    bgGreen: (text) => `[bgGreen]${text}[/bgGreen]`,
+    bgBlue: (text) => `[bgBlue]${text}[/bgBlue]`,
+    bgYellow: (text) => `[bgYellow]${text}[/bgYellow]`,
+    bgCyan: (text) => `[bgCyan]${text}[/bgCyan]`,
+    bgMagenta: (text) => `[bgMagenta]${text}[/bgMagenta]`,
+    bgGray: (text) => `[bgGray]${text}[/bgGray]`,
+    black: (text) => `[black]${text}[/black]`,
+    white: (text) => `[white]${text}[/white]`,
+    bgBlack: (text) => `[bgBlack]${text}[/bgBlack]`,
+    bgWhite: (text) => `[bgWhite]${text}[/bgWhite]`,
+    // Add missing bright colors
+    brightRed: (text) => `[brightRed]${text}[/brightRed]`,
+    brightGreen: (text) => `[brightGreen]${text}[/brightGreen]`,
+    brightYellow: (text) => `[brightYellow]${text}[/brightYellow]`,
+    brightBlue: (text) => `[brightBlue]${text}[/brightBlue]`,
+    brightCyan: (text) => `[brightCyan]${text}[/brightCyan]`,
+    brightMagenta: (text) => `[brightMagenta]${text}[/brightMagenta]`,
+    brightWhite: (text) => `[brightWhite]${text}[/brightWhite]`,
+    reset: (text) => `[reset]${text}[/reset]`,
+    strip: (text) => text.replace(/\[[^\]]+\]/g, "")
+  };
+  const originalLog = console.log;
+  const originalError = console.error;
+  console.log = (...args) => {
+    stdout.push(args.join(" "));
+  };
+  console.error = (...args) => {
+    stderr.push(args.join(" "));
+  };
+  try {
+    const handlerArgs = {
+      flags: options.flags || {},
+      positional: options.args || [],
+      env: { ...process.env, ...options.env },
+      cwd: options.cwd || process.cwd(),
+      prompt: mockPrompt,
+      spinner: mockSpinner,
+      shell: mockShell,
+      colors: mockColors,
+      terminal: {
+        width: 80,
+        height: 24,
+        isInteractive: false,
+        isCI: true,
+        supportsColor: false,
+        supportsMouse: false
+      },
+      runtime: {
+        startTime: Date.now(),
+        args: options.args || [],
+        command: command.description
+      }
+    };
+    if (command.handler) {
+      await command.handler(handlerArgs);
+    }
+    exitCode = options.exitCode || 0;
+  } catch (err) {
+    error = err;
+    exitCode = 1;
+    stderr.push(error.message);
+  } finally {
+    console.log = originalLog;
+    console.error = originalError;
+  }
+  const duration = performance.now() - startTime;
+  return {
+    stdout: stdout.join("\n"),
+    stderr: stderr.join("\n"),
+    exitCode,
+    duration,
+    error
+  };
+}
+export async function testCLI(setupCLI, argv, _options = {}) {
+  const startTime = performance.now();
+  const stdout = [];
+  const stderr = [];
+  let exitCode = 0;
+  let error;
+  const originalLog = console.log;
+  const originalError = console.error;
+  const originalExit = process.exit;
+  console.log = (...args) => {
+    stdout.push(args.join(" "));
+  };
+  console.error = (...args) => {
+    stderr.push(args.join(" "));
+  };
+  process.exit = (code) => {
+    exitCode = code || 0;
+    throw new Error(`Process exited with code ${exitCode}`);
+  };
+  try {
+    const cli = await createCLI({
+      name: "test-cli",
+      version: "1.0.0",
+      description: "Test CLI"
+    });
+    setupCLI(cli);
+    await cli.run(argv);
+  } catch (err) {
+    if (!err.message.startsWith("Process exited with code")) {
+      error = err;
+      exitCode = 1;
+      stderr.push(error?.message || "Unknown error");
+    }
+  } finally {
+    console.log = originalLog;
+    console.error = originalError;
+    process.exit = originalExit;
+  }
+  const duration = performance.now() - startTime;
+  return {
+    stdout: stdout.join("\n"),
+    stderr: stderr.join("\n"),
+    exitCode,
+    duration,
+    error
+  };
+}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+import type { HandlerArgs } from "@reliverse/rempts-core";
+export interface TestOptions {
+    /** Command flags to pass */
+    flags?: Record<string, unknown>;
+    /** Positional arguments */
+    args?: string[];
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Current working directory */
+    cwd?: string;
+    /** Input for prompts (line by line) */
+    stdin?: string | string[];
+    /** Mock prompt responses mapped by prompt message */
+    mockPrompts?: Record<string, string | string[]>;
+    /** Mock shell command outputs */
+    mockShellCommands?: Record<string, string>;
+    /** Exit code to expect */
+    exitCode?: number;
+}
+export interface TestResult {
+    /** Captured stdout */
+    stdout: string;
+    /** Captured stderr */
+    stderr: string;
+    /** Exit code */
+    exitCode: number;
+    /** Execution time in ms */
+    duration: number;
+    /** Any error thrown */
+    error?: Error;
+}
+export interface MockHandlerArgs extends Omit<HandlerArgs, "prompt" | "spinner" | "shell"> {
+    prompt: {
+        (message: string, options?: any): Promise<string>;
+        confirm: (message: string, options?: any) => Promise<boolean>;
+        select: <T = string>(message: string, options: any) => Promise<T>;
+        password: (message: string, options?: any) => Promise<string>;
+        multiselect: <T = string>(message: string, options: any) => Promise<T[]>;
+    };
+    spinner: (text?: string) => {
+        start: (text?: string) => void;
+        stop: (text?: string) => void;
+        succeed: (text?: string) => void;
+        fail: (text?: string) => void;
+        warn: (text?: string) => void;
+        info: (text?: string) => void;
+        update: (text: string) => void;
+    };
+    shell: MockShell;
+}
+export interface Matchers {
+    toHaveExitCode(code: number): void;
+    toHaveSucceeded(): void;
+    toHaveFailed(): void;
+    toContainInStdout(text: string): void;
+    toContainInStderr(text: string): void;
+    toMatchStdout(pattern: RegExp): void;
+    toMatchStderr(pattern: RegExp): void;
+}
+export type MockShell = (strings: TemplateStringsArray, ...values: any[]) => ShellPromise;
+export interface ShellPromise extends Promise<void> {
+    text(): Promise<string>;
+    json<T = any>(): Promise<T>;
+    quiet(): ShellPromise;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@reliverse/rempts-test",
+  "version": "2.3.1",
+  "description": "Testing utilities for Rempts CLI applications",
+  "keywords": [
+    "assertions",
+    "bun",
+    "cli",
+    "matchers",
+    "rempts",
+    "test",
+    "testing",
+    "typescript"
+  ],
+  "homepage": "https://github.com/reliverse/dler#readme",
+  "bugs": {
+    "url": "https://github.com/reliverse/dler/issues"
+  },
+  "license": "MIT",
+  "author": "blefnk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reliverse/dler.git",
+    "directory": "packages/test"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "module": "./src/mod.ts",
+  "types": "./src/mod.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/mod.d.ts",
+      "import": "./dist/mod.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@reliverse/relico": "2.3.1",
+    "@reliverse/rempts-core": "2.3.1",
+    "arktype": "^2.1.29",
+    "arkregex": "^0.0.5"
+  }
+}