@mdxui/terminal 2.0.0

package/src/__tests__/utils/assertions.ts

@@ -0,0 +1,685 @@
+/**
+ * @mdxui/terminal Test Assertions
+ *
+ * Custom assertion helpers for testing terminal output. These helpers
+ * understand ANSI codes and terminal rendering conventions.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   expectTerminalContains,
+ *   expectTerminalMatches,
+ *   expectAnsiCode,
+ *   expectBoxDrawing,
+ * } from './assertions'
+ *
+ * const output = renderer.render(<Box border="single"><Text>Hello</Text></Box>)
+ *
+ * expectTerminalContains(output, 'Hello')
+ * expectBoxDrawing(output, 'single')
+ * ```
+ */
+
+import { expect } from 'vitest'
+import { ANSI } from '../../theme/ansi-codes'
+import { boxChars, type BoxStyle } from '../../theme/box-drawing'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** ANSI style names for assertion helpers */
+export type AnsiStyleName =
+  | 'bold'
+  | 'dim'
+  | 'italic'
+  | 'underline'
+  | 'inverse'
+  | 'strikethrough'
+  | 'reset'
+
+/** ANSI color names for assertion helpers */
+export type AnsiColorName =
+  | 'black'
+  | 'red'
+  | 'green'
+  | 'yellow'
+  | 'blue'
+  | 'magenta'
+  | 'cyan'
+  | 'white'
+  | 'brightBlack'
+  | 'brightRed'
+  | 'brightGreen'
+  | 'brightYellow'
+  | 'brightBlue'
+  | 'brightMagenta'
+  | 'brightCyan'
+  | 'brightWhite'
+
+/** Background color names */
+export type AnsiBgColorName =
+  | 'bgBlack'
+  | 'bgRed'
+  | 'bgGreen'
+  | 'bgYellow'
+  | 'bgBlue'
+  | 'bgMagenta'
+  | 'bgCyan'
+  | 'bgWhite'
+  | 'bgBrightBlack'
+  | 'bgBrightRed'
+  | 'bgBrightGreen'
+  | 'bgBrightYellow'
+  | 'bgBrightBlue'
+  | 'bgBrightMagenta'
+  | 'bgBrightCyan'
+  | 'bgBrightWhite'
+
+// ============================================================================
+// ANSI Code Utilities
+// ============================================================================
+
+/**
+ * Strip all ANSI escape codes from a string.
+ *
+ * @param str - The string containing ANSI codes
+ * @returns The string with ANSI codes removed
+ */
+export function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[\d;]*m/g, '')
+}
+
+/**
+ * Check if a string contains any ANSI escape codes.
+ *
+ * @param str - The string to check
+ * @returns True if the string contains ANSI codes
+ */
+export function hasAnsiCodes(str: string): boolean {
+  // eslint-disable-next-line no-control-regex
+  return /\x1b\[[\d;]*m/.test(str)
+}
+
+/**
+ * Get the visible length of a string (excluding ANSI codes).
+ *
+ * @param str - The string to measure
+ * @returns The visible character count
+ */
+export function visibleLength(str: string): number {
+  return stripAnsi(str).length
+}
+
+/**
+ * Extract all ANSI codes from a string.
+ *
+ * @param str - The string containing ANSI codes
+ * @returns Array of ANSI escape sequences found
+ */
+export function extractAnsiCodes(str: string): string[] {
+  // eslint-disable-next-line no-control-regex
+  const matches = str.match(/\x1b\[[\d;]*m/g)
+  return matches ?? []
+}
+
+/**
+ * Get the plain text content from terminal output.
+ *
+ * @param output - Array of output lines or single string
+ * @returns Plain text with ANSI codes stripped
+ */
+export function getPlainContent(output: string | string[]): string {
+  const text = Array.isArray(output) ? output.join('\n') : output
+  return stripAnsi(text)
+}
+
+// ============================================================================
+// Content Assertions
+// ============================================================================
+
+/**
+ * Assert that terminal output contains specific text (ignoring ANSI codes).
+ *
+ * @param output - Terminal output as string array or string
+ * @param text - The text to search for
+ * @throws AssertionError if text is not found
+ *
+ * @example
+ * ```tsx
+ * const output = renderer.render(<Text>Hello World</Text>)
+ * expectTerminalContains(output, 'Hello')
+ * expectTerminalContains(output, 'World')
+ * ```
+ */
+export function expectTerminalContains(
+  output: string | string[],
+  text: string
+): void {
+  const plainContent = getPlainContent(output)
+  expect(plainContent).toContain(text)
+}
+
+/**
+ * Assert that terminal output does NOT contain specific text.
+ *
+ * @param output - Terminal output as string array or string
+ * @param text - The text that should not be present
+ * @throws AssertionError if text is found
+ *
+ * @example
+ * ```tsx
+ * const output = renderer.render(<Input type="password" value="secret" />)
+ * expectTerminalNotContains(output, 'secret')
+ * ```
+ */
+export function expectTerminalNotContains(
+  output: string | string[],
+  text: string
+): void {
+  const plainContent = getPlainContent(output)
+  expect(plainContent).not.toContain(text)
+}
+
+/**
+ * Assert that terminal output matches a regular expression.
+ *
+ * @param output - Terminal output as string array or string
+ * @param pattern - The regex pattern to match
+ * @param options - Options for matching
+ * @throws AssertionError if pattern doesn't match
+ *
+ * @example
+ * ```tsx
+ * expectTerminalMatches(output, /Hello \w+/)
+ * expectTerminalMatches(output, /error/i, { stripAnsi: true })
+ * ```
+ */
+export function expectTerminalMatches(
+  output: string | string[],
+  pattern: RegExp,
+  options: { stripAnsi?: boolean } = {}
+): void {
+  let text = Array.isArray(output) ? output.join('\n') : output
+
+  if (options.stripAnsi !== false) {
+    text = stripAnsi(text)
+  }
+
+  expect(text).toMatch(pattern)
+}
+
+/**
+ * Assert that a specific line of output contains text.
+ *
+ * @param output - Array of output lines
+ * @param lineIndex - The line index to check (0-based)
+ * @param text - The text to search for
+ * @throws AssertionError if line doesn't contain text
+ *
+ * @example
+ * ```tsx
+ * expectLineContains(output, 0, 'Header')
+ * expectLineContains(output, 1, 'Content')
+ * ```
+ */
+export function expectLineContains(
+  output: string[],
+  lineIndex: number,
+  text: string
+): void {
+  expect(output.length).toBeGreaterThan(lineIndex)
+  expect(stripAnsi(output[lineIndex])).toContain(text)
+}
+
+/**
+ * Assert that output has a specific number of lines.
+ *
+ * @param output - Array of output lines
+ * @param count - Expected number of lines
+ * @throws AssertionError if line count doesn't match
+ */
+export function expectLineCount(output: string[], count: number): void {
+  expect(output).toHaveLength(count)
+}
+
+/**
+ * Assert that output has at least a minimum number of lines.
+ *
+ * @param output - Array of output lines
+ * @param minCount - Minimum expected lines
+ * @throws AssertionError if fewer lines than minimum
+ */
+export function expectMinLines(output: string[], minCount: number): void {
+  expect(output.length).toBeGreaterThanOrEqual(minCount)
+}
+
+// ============================================================================
+// ANSI Style Assertions
+// ============================================================================
+
+/**
+ * Assert that output contains a specific ANSI code.
+ *
+ * @param output - Terminal output as string array or string
+ * @param code - The ANSI code to check for (e.g., '\x1b[1m' for bold)
+ * @throws AssertionError if code is not found
+ *
+ * @example
+ * ```tsx
+ * expectAnsiCode(output, ANSI.bold)
+ * expectAnsiCode(output, '\x1b[31m') // red
+ * ```
+ */
+export function expectAnsiCode(
+  output: string | string[],
+  code: string
+): void {
+  const text = Array.isArray(output) ? output.join('') : output
+  expect(text).toContain(code)
+}
+
+/**
+ * Assert that output does NOT contain a specific ANSI code.
+ *
+ * @param output - Terminal output as string array or string
+ * @param code - The ANSI code that should not be present
+ * @throws AssertionError if code is found
+ */
+export function expectNoAnsiCode(
+  output: string | string[],
+  code: string
+): void {
+  const text = Array.isArray(output) ? output.join('') : output
+  expect(text).not.toContain(code)
+}
+
+/**
+ * Assert that output contains a specific ANSI style by name.
+ *
+ * @param output - Terminal output
+ * @param styleName - The style name (bold, dim, italic, underline, etc.)
+ * @throws AssertionError if style is not found
+ *
+ * @example
+ * ```tsx
+ * expectStyle(output, 'bold')
+ * expectStyle(output, 'underline')
+ * ```
+ */
+export function expectStyle(
+  output: string | string[],
+  styleName: AnsiStyleName
+): void {
+  const styleCode = ANSI[styleName]
+  expectAnsiCode(output, styleCode)
+}
+
+/**
+ * Assert that output contains a specific foreground color.
+ *
+ * @param output - Terminal output
+ * @param colorName - The color name
+ * @throws AssertionError if color is not found
+ *
+ * @example
+ * ```tsx
+ * expectForegroundColor(output, 'red')
+ * expectForegroundColor(output, 'cyan')
+ * ```
+ */
+export function expectForegroundColor(
+  output: string | string[],
+  colorName: AnsiColorName
+): void {
+  const colorCode = ANSI[colorName]
+  expectAnsiCode(output, colorCode)
+}
+
+/**
+ * Assert that output contains a specific background color.
+ *
+ * @param output - Terminal output
+ * @param colorName - The background color name
+ * @throws AssertionError if color is not found
+ *
+ * @example
+ * ```tsx
+ * expectBackgroundColor(output, 'bgBlue')
+ * expectBackgroundColor(output, 'bgRed')
+ * ```
+ */
+export function expectBackgroundColor(
+  output: string | string[],
+  colorName: AnsiBgColorName
+): void {
+  const colorCode = ANSI[colorName]
+  expectAnsiCode(output, colorCode)
+}
+
+/**
+ * Assert that output contains an ANSI reset code.
+ *
+ * This is important to verify that styles are properly cleaned up.
+ *
+ * @param output - Terminal output
+ * @throws AssertionError if reset is not found
+ */
+export function expectReset(output: string | string[]): void {
+  expectAnsiCode(output, ANSI.reset)
+}
+
+/**
+ * Assert that output contains 256-color ANSI code.
+ *
+ * @param output - Terminal output
+ * @param colorNumber - The 256-color code (0-255)
+ * @param isForeground - True for foreground, false for background
+ * @throws AssertionError if color code is not found
+ *
+ * @example
+ * ```tsx
+ * expectAnsi256Color(output, 33) // Blue in 256 palette
+ * expectAnsi256Color(output, 196, false) // Red background
+ * ```
+ */
+export function expectAnsi256Color(
+  output: string | string[],
+  colorNumber: number,
+  isForeground: boolean = true
+): void {
+  const prefix = isForeground ? '38' : '48'
+  const code = `\x1b[${prefix};5;${colorNumber}m`
+  expectAnsiCode(output, code)
+}
+
+/**
+ * Assert that output contains truecolor RGB ANSI code.
+ *
+ * @param output - Terminal output
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @param isForeground - True for foreground, false for background
+ * @throws AssertionError if RGB code is not found
+ *
+ * @example
+ * ```tsx
+ * expectTrueColor(output, 255, 0, 0) // Red foreground
+ * expectTrueColor(output, 59, 130, 246, false) // Blue-500 background
+ * ```
+ */
+export function expectTrueColor(
+  output: string | string[],
+  r: number,
+  g: number,
+  b: number,
+  isForeground: boolean = true
+): void {
+  const prefix = isForeground ? '38' : '48'
+  const code = `\x1b[${prefix};2;${r};${g};${b}m`
+  expectAnsiCode(output, code)
+}
+
+// ============================================================================
+// Box Drawing Assertions
+// ============================================================================
+
+/**
+ * Assert that output contains box drawing characters for a specific style.
+ *
+ * @param output - Terminal output
+ * @param style - The box style (single, double, rounded, etc.)
+ * @throws AssertionError if box characters are not found
+ *
+ * @example
+ * ```tsx
+ * expectBoxDrawing(output, 'single')
+ * expectBoxDrawing(output, 'double')
+ * expectBoxDrawing(output, 'rounded')
+ * ```
+ */
+export function expectBoxDrawing(
+  output: string | string[],
+  style: BoxStyle
+): void {
+  const text = Array.isArray(output) ? output.join('') : output
+  const chars = boxChars[style]
+
+  // Check for corner characters
+  expect(text).toContain(chars.topLeft)
+  expect(text).toContain(chars.topRight)
+  expect(text).toContain(chars.bottomLeft)
+  expect(text).toContain(chars.bottomRight)
+}
+
+/**
+ * Assert that output contains horizontal box lines.
+ *
+ * @param output - Terminal output
+ * @param style - The box style
+ * @throws AssertionError if horizontal lines are not found
+ */
+export function expectHorizontalLine(
+  output: string | string[],
+  style: BoxStyle
+): void {
+  const text = Array.isArray(output) ? output.join('') : output
+  expect(text).toContain(boxChars[style].horizontal)
+}
+
+/**
+ * Assert that output contains vertical box lines.
+ *
+ * @param output - Terminal output
+ * @param style - The box style
+ * @throws AssertionError if vertical lines are not found
+ */
+export function expectVerticalLine(
+  output: string | string[],
+  style: BoxStyle
+): void {
+  const text = Array.isArray(output) ? output.join('') : output
+  expect(text).toContain(boxChars[style].vertical)
+}
+
+/**
+ * Assert that output does NOT contain box drawing characters.
+ *
+ * @param output - Terminal output
+ * @throws AssertionError if any box characters are found
+ */
+export function expectNoBoxDrawing(output: string | string[]): void {
+  const text = stripAnsi(Array.isArray(output) ? output.join('') : output)
+
+  // Check all box styles
+  for (const style of ['single', 'double', 'rounded'] as const) {
+    const chars = boxChars[style]
+    expect(text).not.toContain(chars.topLeft)
+    expect(text).not.toContain(chars.topRight)
+    expect(text).not.toContain(chars.bottomLeft)
+    expect(text).not.toContain(chars.bottomRight)
+  }
+}
+
+// ============================================================================
+// Dimension Assertions
+// ============================================================================
+
+/**
+ * Assert that all lines have a maximum width.
+ *
+ * @param output - Array of output lines
+ * @param maxWidth - Maximum allowed visible width
+ * @throws AssertionError if any line exceeds maxWidth
+ *
+ * @example
+ * ```tsx
+ * expectMaxWidth(output, 80)
+ * ```
+ */
+export function expectMaxWidth(output: string[], maxWidth: number): void {
+  for (const line of output) {
+    expect(visibleLength(line)).toBeLessThanOrEqual(maxWidth)
+  }
+}
+
+/**
+ * Assert that all lines have an exact width.
+ *
+ * @param output - Array of output lines
+ * @param width - Expected visible width
+ * @throws AssertionError if any line doesn't match width
+ */
+export function expectExactWidth(output: string[], width: number): void {
+  for (const line of output) {
+    expect(visibleLength(line)).toBe(width)
+  }
+}
+
+/**
+ * Assert that output fits within specified dimensions.
+ *
+ * @param output - Array of output lines
+ * @param width - Maximum width
+ * @param height - Maximum height (line count)
+ * @throws AssertionError if output exceeds dimensions
+ */
+export function expectFitsDimensions(
+  output: string[],
+  width: number,
+  height: number
+): void {
+  expect(output.length).toBeLessThanOrEqual(height)
+  expectMaxWidth(output, width)
+}
+
+// ============================================================================
+// Snapshot Utilities
+// ============================================================================
+
+/**
+ * Create a snapshot-friendly representation of terminal output.
+ *
+ * This normalizes the output for consistent snapshot comparison:
+ * - Optionally strips ANSI codes
+ * - Trims trailing whitespace
+ * - Normalizes line endings
+ *
+ * @param output - Terminal output
+ * @param options - Snapshot options
+ * @returns Normalized string for snapshot comparison
+ *
+ * @example
+ * ```tsx
+ * expect(toSnapshot(output)).toMatchSnapshot()
+ * expect(toSnapshot(output, { stripAnsi: true })).toMatchSnapshot()
+ * ```
+ */
+export function toSnapshot(
+  output: string | string[],
+  options: {
+    stripAnsi?: boolean
+    trimLines?: boolean
+  } = {}
+): string {
+  const { stripAnsi: strip = false, trimLines = true } = options
+
+  let text = Array.isArray(output) ? output.join('\n') : output
+
+  if (strip) {
+    text = stripAnsi(text)
+  }
+
+  if (trimLines) {
+    text = text
+      .split('\n')
+      .map(line => line.trimEnd())
+      .join('\n')
+  }
+
+  return text
+}
+
+/**
+ * Compare two terminal outputs for equality (ignoring ANSI codes).
+ *
+ * @param actual - Actual output
+ * @param expected - Expected output
+ * @returns True if outputs are equal (after stripping ANSI)
+ */
+export function terminalOutputEquals(
+  actual: string | string[],
+  expected: string | string[]
+): boolean {
+  const actualText = getPlainContent(actual)
+  const expectedText = getPlainContent(expected)
+  return actualText === expectedText
+}
+
+/**
+ * Assert that two terminal outputs are equal (ignoring ANSI codes).
+ *
+ * @param actual - Actual output
+ * @param expected - Expected output
+ * @throws AssertionError if outputs don't match
+ */
+export function expectTerminalEquals(
+  actual: string | string[],
+  expected: string | string[]
+): void {
+  expect(getPlainContent(actual)).toBe(getPlainContent(expected))
+}
+
+// ============================================================================
+// Component-Specific Assertions
+// ============================================================================
+
+/**
+ * Assert that output shows a cursor indicator (inverse video or underline).
+ *
+ * Used for testing focused input fields.
+ *
+ * @param output - Terminal output
+ * @throws AssertionError if no cursor indicator found
+ */
+export function expectCursor(output: string | string[]): void {
+  const text = Array.isArray(output) ? output.join('') : output
+  // Cursor is typically shown as inverse video or underline
+  expect(text).toMatch(/\x1b\[7m|\x1b\[4m/)
+}
+
+/**
+ * Assert that output shows focus styling.
+ *
+ * @param output - Terminal output
+ * @throws AssertionError if no focus styling found
+ */
+export function expectFocused(output: string | string[]): void {
+  const text = Array.isArray(output) ? output.join('') : output
+  // Focus typically includes inverse, underline, or background color
+  expect(text).toMatch(/\x1b\[(7|4|4[0-7]|10[0-7])m/)
+}
+
+/**
+ * Assert that output shows disabled styling (typically dim).
+ *
+ * @param output - Terminal output
+ * @throws AssertionError if no disabled styling found
+ */
+export function expectDisabled(output: string | string[]): void {
+  expectAnsiCode(output, ANSI.dim)
+}
+
+/**
+ * Assert that output shows selection/highlight styling.
+ *
+ * @param output - Terminal output
+ * @throws AssertionError if no selection styling found
+ */
+export function expectSelected(output: string | string[]): void {
+  const text = Array.isArray(output) ? output.join('') : output
+  // Selection typically includes background color or inverse
+  expect(text).toMatch(/\x1b\[(7|4[0-7]|10[0-7])m/)
+}