@mdxui/terminal 2.0.0

package/src/__tests__/utils/index.ts

@@ -0,0 +1,115 @@
+/**
+ * @mdxui/terminal Test Utilities
+ *
+ * Comprehensive test utilities for testing terminal components.
+ * This module provides:
+ *
+ * - **Mock Renderer**: Test components without a real terminal
+ * - **Assertions**: Terminal-aware assertion helpers
+ * - **Snapshot Utilities**: Prepare output for snapshot testing
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   createTestRenderer,
+ *   renderToLines,
+ *   expectTerminalContains,
+ *   expectBoxDrawing,
+ *   expectStyle,
+ *   toSnapshot,
+ * } from '../utils'
+ *
+ * describe('MyComponent', () => {
+ *   it('renders correctly', () => {
+ *     const output = renderToLines(<Box border="single"><Text>Hello</Text></Box>)
+ *
+ *     expectTerminalContains(output, 'Hello')
+ *     expectBoxDrawing(output, 'single')
+ *     expect(toSnapshot(output)).toMatchSnapshot()
+ *   })
+ *
+ *   it('applies styling', () => {
+ *     const output = renderToLines(<Text bold color="red">Error</Text>)
+ *
+ *     expectStyle(output, 'bold')
+ *     expectForegroundColor(output, 'red')
+ *   })
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Mock Renderer
+// ============================================================================
+
+export {
+  // Core renderer
+  createTestRenderer,
+  createTestRoot,
+  // Convenience functions
+  renderToLines,
+  renderToString,
+  prepareSnapshot,
+  // Mock factory functions (for vi.mock)
+  mockCreateCliRenderer,
+  mockCreateRoot,
+  // Types
+  type TestRenderer,
+  type TestRendererConfig,
+  type TestRoot,
+  type SnapshotOptions,
+  type RenderContext,
+} from './test-renderer'
+
+// ============================================================================
+// Assertions
+// ============================================================================
+
+export {
+  // ANSI utilities
+  stripAnsi,
+  hasAnsiCodes,
+  visibleLength,
+  extractAnsiCodes,
+  getPlainContent,
+  // Content assertions
+  expectTerminalContains,
+  expectTerminalNotContains,
+  expectTerminalMatches,
+  expectLineContains,
+  expectLineCount,
+  expectMinLines,
+  // ANSI style assertions
+  expectAnsiCode,
+  expectNoAnsiCode,
+  expectStyle,
+  expectForegroundColor,
+  expectBackgroundColor,
+  expectReset,
+  expectAnsi256Color,
+  expectTrueColor,
+  // Box drawing assertions
+  expectBoxDrawing,
+  expectHorizontalLine,
+  expectVerticalLine,
+  expectNoBoxDrawing,
+  // Dimension assertions
+  expectMaxWidth,
+  expectExactWidth,
+  expectFitsDimensions,
+  // Snapshot utilities
+  toSnapshot,
+  terminalOutputEquals,
+  expectTerminalEquals,
+  // Component-specific assertions
+  expectCursor,
+  expectFocused,
+  expectDisabled,
+  expectSelected,
+  // Types
+  type AnsiStyleName,
+  type AnsiColorName,
+  type AnsiBgColorName,
+} from './assertions'

package/src/__tests__/utils/test-renderer.ts

@@ -0,0 +1,381 @@
+/**
+ * @mdxui/terminal Test Renderer
+ *
+ * Mock terminal renderer for testing terminal components without requiring
+ * a real terminal or @opentui/core. Provides predictable output for assertions.
+ *
+ * @example
+ * ```tsx
+ * import { createTestRenderer, renderToLines } from './test-renderer'
+ * import { Box, Text } from '@mdxui/terminal'
+ *
+ * // Quick rendering
+ * const lines = await renderToLines(
+ *   <Box border="single"><Text>Hello</Text></Box>
+ * )
+ * expect(lines).toContain('Hello')
+ *
+ * // Full control
+ * const renderer = createTestRenderer({ width: 40, height: 10 })
+ * const output = renderer.render(<App />)
+ * expect(renderer.getBuffer()).toMatchSnapshot()
+ * ```
+ */
+
+import type { ReactElement, ReactNode } from 'react'
+import type { RenderContext } from '../../components/types'
+import { renderElement } from '../../components/render'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Configuration options for the test renderer
+ */
+export interface TestRendererConfig {
+  /** Terminal width in columns (default: 80) */
+  width?: number
+  /** Terminal height in rows (default: 24) */
+  height?: number
+  /** Enable color output (default: true) */
+  colors?: boolean
+  /** Color support level (default: 'truecolor') */
+  colorSupport?: 'none' | '16' | '256' | 'truecolor'
+}
+
+/**
+ * Mock renderer instance for testing
+ */
+export interface TestRenderer {
+  /** Terminal width in columns */
+  readonly width: number
+  /** Terminal height in rows */
+  readonly height: number
+  /** Render a React element and return output lines */
+  render(element: ReactElement): string[]
+  /** Get the current buffer as a 2D array (rows x columns) */
+  getBuffer(): string[][]
+  /** Get the current output as a single string with newlines */
+  toString(): string
+  /** Clear the buffer */
+  clear(): void
+  /** Get the last rendered output */
+  getLastOutput(): string[]
+  /** Configure the renderer */
+  configure(config: Partial<TestRendererConfig>): void
+  /** Mock lifecycle methods (for compatibility with CliRenderer interface) */
+  start(): void
+  stop(): void
+  destroy(): void
+  requestRender(): void
+}
+
+/**
+ * Mock root instance for React rendering
+ */
+export interface TestRoot {
+  /** Render a React element */
+  render(element: ReactNode): void
+  /** Unmount and clean up */
+  unmount(): void
+  /** Get the rendered output */
+  getOutput(): string[]
+}
+
+/**
+ * Snapshot options for terminal output
+ */
+export interface SnapshotOptions {
+  /** Strip ANSI codes before comparison (default: false) */
+  stripAnsi?: boolean
+  /** Trim trailing whitespace from lines (default: true) */
+  trimTrailingWhitespace?: boolean
+  /** Normalize line endings (default: true) */
+  normalizeLineEndings?: boolean
+}
+
+// ============================================================================
+// Mock Renderer Implementation
+// ============================================================================
+
+/**
+ * Create a mock terminal renderer for testing.
+ *
+ * This renderer simulates the @opentui/core renderer behavior
+ * but renders to an in-memory buffer instead of the terminal.
+ *
+ * @param config - Optional configuration
+ * @returns A mock renderer instance
+ *
+ * @example
+ * ```tsx
+ * const renderer = createTestRenderer({ width: 40, height: 10 })
+ * const lines = renderer.render(<Box>Test</Box>)
+ * expect(lines[0]).toContain('Test')
+ * ```
+ */
+export function createTestRenderer(config: TestRendererConfig = {}): TestRenderer {
+  let width = config.width ?? 80
+  let height = config.height ?? 24
+  let colors = config.colors ?? true
+  let colorSupport = config.colorSupport ?? 'truecolor'
+
+  // Internal buffer as 2D array
+  let buffer: string[][] = []
+  let lastOutput: string[] = []
+
+  // Initialize empty buffer
+  const initBuffer = () => {
+    buffer = Array.from({ length: height }, () =>
+      Array.from({ length: width }, () => ' ')
+    )
+  }
+
+  initBuffer()
+
+  return {
+    get width() {
+      return width
+    },
+    get height() {
+      return height
+    },
+
+    render(element: ReactElement): string[] {
+      const context: RenderContext = {
+        width,
+        colors,
+        colorSupport,
+      }
+
+      const lines = renderElement(element, context)
+      lastOutput = lines
+
+      // Update buffer with rendered content
+      initBuffer()
+      lines.forEach((line, row) => {
+        if (row < height) {
+          const chars = [...line]
+          chars.forEach((char, col) => {
+            if (col < width) {
+              buffer[row][col] = char
+            }
+          })
+        }
+      })
+
+      return lines
+    },
+
+    getBuffer(): string[][] {
+      return buffer.map(row => [...row])
+    },
+
+    toString(): string {
+      return lastOutput.join('\n')
+    },
+
+    clear(): void {
+      initBuffer()
+      lastOutput = []
+    },
+
+    getLastOutput(): string[] {
+      return [...lastOutput]
+    },
+
+    configure(newConfig: Partial<TestRendererConfig>): void {
+      if (newConfig.width !== undefined) width = newConfig.width
+      if (newConfig.height !== undefined) height = newConfig.height
+      if (newConfig.colors !== undefined) colors = newConfig.colors
+      if (newConfig.colorSupport !== undefined) colorSupport = newConfig.colorSupport
+      initBuffer()
+    },
+
+    // Mock lifecycle methods (no-op for testing)
+    start(): void {},
+    stop(): void {},
+    destroy(): void {},
+    requestRender(): void {},
+  }
+}
+
+/**
+ * Create a mock root for testing React trees.
+ *
+ * @param renderer - The test renderer to use
+ * @returns A mock root instance
+ *
+ * @example
+ * ```tsx
+ * const renderer = createTestRenderer()
+ * const root = createTestRoot(renderer)
+ * root.render(<App />)
+ * expect(root.getOutput()).toContain('Welcome')
+ * ```
+ */
+export function createTestRoot(renderer: TestRenderer): TestRoot {
+  let currentOutput: string[] = []
+
+  return {
+    render(element: ReactNode): void {
+      if (element === null || element === undefined) {
+        currentOutput = []
+        renderer.clear()
+        return
+      }
+
+      currentOutput = renderer.render(element as ReactElement)
+    },
+
+    unmount(): void {
+      currentOutput = []
+      renderer.clear()
+    },
+
+    getOutput(): string[] {
+      return [...currentOutput]
+    },
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Render a React element directly to lines without creating a renderer.
+ *
+ * This is a convenience function for quick tests that don't need
+ * full renderer control.
+ *
+ * @param element - The React element to render
+ * @param options - Optional configuration
+ * @returns Array of rendered output lines
+ *
+ * @example
+ * ```tsx
+ * const lines = await renderToLines(<Text color="red">Error</Text>)
+ * expect(lines[0]).toContain('Error')
+ * ```
+ */
+export function renderToLines(
+  element: ReactElement,
+  options: TestRendererConfig = {}
+): string[] {
+  const renderer = createTestRenderer(options)
+  return renderer.render(element)
+}
+
+/**
+ * Render a React element to a single string with newlines.
+ *
+ * @param element - The React element to render
+ * @param options - Optional configuration
+ * @returns The rendered output as a string
+ *
+ * @example
+ * ```tsx
+ * const output = renderToString(<Box>Hello</Box>)
+ * expect(output).toMatchSnapshot()
+ * ```
+ */
+export function renderToString(
+  element: ReactElement,
+  options: TestRendererConfig = {}
+): string {
+  const lines = renderToLines(element, options)
+  return lines.join('\n')
+}
+
+/**
+ * Prepare terminal output for snapshot comparison.
+ *
+ * Normalizes the output to ensure consistent snapshot matching
+ * across different environments.
+ *
+ * @param output - The raw output (string or array of lines)
+ * @param options - Normalization options
+ * @returns Normalized output string
+ *
+ * @example
+ * ```tsx
+ * const output = renderer.render(<Component />)
+ * expect(prepareSnapshot(output)).toMatchSnapshot()
+ * ```
+ */
+export function prepareSnapshot(
+  output: string | string[],
+  options: SnapshotOptions = {}
+): string {
+  const {
+    stripAnsi = false,
+    trimTrailingWhitespace = true,
+    normalizeLineEndings = true,
+  } = options
+
+  let text = Array.isArray(output) ? output.join('\n') : output
+
+  // Strip ANSI codes if requested
+  if (stripAnsi) {
+    text = text.replace(/\x1b\[[\d;]*m/g, '')
+  }
+
+  // Normalize line endings
+  if (normalizeLineEndings) {
+    text = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+  }
+
+  // Trim trailing whitespace from each line
+  if (trimTrailingWhitespace) {
+    text = text
+      .split('\n')
+      .map(line => line.trimEnd())
+      .join('\n')
+  }
+
+  return text
+}
+
+/**
+ * Create a mock @opentui/core createCliRenderer for testing.
+ *
+ * This returns a mock that can be used with vi.mock() or jest.mock()
+ * to replace the real OpenTUI renderer in tests.
+ *
+ * @param config - Optional configuration
+ * @returns A mock createCliRenderer function
+ *
+ * @example
+ * ```tsx
+ * vi.mock('@opentui/core', () => ({
+ *   createCliRenderer: mockCreateCliRenderer({ width: 40 }),
+ * }))
+ * ```
+ */
+export function mockCreateCliRenderer(config: TestRendererConfig = {}) {
+  return async () => createTestRenderer(config)
+}
+
+/**
+ * Create a mock @opentui/react createRoot for testing.
+ *
+ * @returns A mock createRoot function
+ *
+ * @example
+ * ```tsx
+ * vi.mock('@opentui/react', () => ({
+ *   createRoot: mockCreateRoot(),
+ * }))
+ * ```
+ */
+export function mockCreateRoot() {
+  return (renderer: TestRenderer) => createTestRoot(renderer)
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { type RenderContext }