@mdxui/terminal 2.0.0

package/src/__tests__/renderer.test.ts

@@ -0,0 +1,489 @@
+/**
+ * @mdxui/terminal OpenTUI Renderer Integration Tests
+ *
+ * TDD RED Phase: Tests for the OpenTUI renderer integration.
+ * These tests verify the core renderer APIs work correctly:
+ * - createCliRenderer(): Creates the underlying OpenTUI terminal renderer
+ * - createRoot(): Creates a React root for terminal rendering
+ * - CLI(): High-level API combining renderer + root
+ *
+ * Tests mock @opentui/core and @opentui/react for CI environments
+ * where a real terminal is not available.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import React from 'react'
+
+// ============================================================================
+// Mock Setup
+// ============================================================================
+
+/**
+ * Mock renderer instance with all required methods
+ */
+function createMockRenderer() {
+  return {
+    width: 80,
+    height: 24,
+    start: vi.fn(),
+    stop: vi.fn(),
+    destroy: vi.fn(),
+    requestRender: vi.fn(),
+  }
+}
+
+/**
+ * Mock root instance with render/unmount
+ */
+function createMockRoot() {
+  return {
+    render: vi.fn(),
+    unmount: vi.fn(),
+  }
+}
+
+// Mock the OpenTUI modules
+vi.mock('@opentui/core', () => ({
+  createCliRenderer: vi.fn(async () => createMockRenderer()),
+}))
+
+vi.mock('@opentui/react', () => ({
+  createRoot: vi.fn(() => createMockRoot()),
+}))
+
+// ============================================================================
+// createCliRenderer Tests
+// ============================================================================
+
+describe('OpenTUI Renderer Integration', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('createCliRenderer', () => {
+    it('returns renderer with width/height properties', async () => {
+      const { createCliRenderer } = await import('..')
+
+      const renderer = await createCliRenderer()
+
+      expect(renderer).toBeDefined()
+      expect(typeof renderer.width).toBe('number')
+      expect(typeof renderer.height).toBe('number')
+      expect(renderer.width).toBeGreaterThan(0)
+      expect(renderer.height).toBeGreaterThan(0)
+    })
+
+    it('renderer has start/stop/destroy methods', async () => {
+      const { createCliRenderer } = await import('..')
+
+      const renderer = await createCliRenderer()
+
+      expect(typeof renderer.start).toBe('function')
+      expect(typeof renderer.stop).toBe('function')
+      expect(typeof renderer.destroy).toBe('function')
+    })
+
+    it('renderer has requestRender method', async () => {
+      const { createCliRenderer } = await import('..')
+
+      const renderer = await createCliRenderer()
+
+      expect(typeof renderer.requestRender).toBe('function')
+    })
+
+    it('start/stop/destroy methods are callable', async () => {
+      const { createCliRenderer } = await import('..')
+
+      const renderer = await createCliRenderer()
+
+      // These should not throw
+      expect(() => renderer.start()).not.toThrow()
+      expect(() => renderer.stop()).not.toThrow()
+      expect(() => renderer.requestRender()).not.toThrow()
+      expect(() => renderer.destroy()).not.toThrow()
+    })
+
+    it('accepts configuration options', async () => {
+      const { createCliRenderer } = await import('..')
+      const { createCliRenderer: mockCreate } = await import('@opentui/core')
+
+      await createCliRenderer({
+        targetFps: 30,
+        useAlternateScreen: true,
+        useMouse: false,
+        exitOnCtrlC: true,
+      })
+
+      expect(mockCreate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          targetFps: 30,
+          useAlternateScreen: true,
+          useMouse: false,
+          exitOnCtrlC: true,
+        })
+      )
+    })
+  })
+
+  // ============================================================================
+  // createRoot Tests
+  // ============================================================================
+
+  describe('createRoot', () => {
+    it('returns root with render/unmount methods', async () => {
+      const { createCliRenderer, createRoot } = await import('..')
+
+      const renderer = await createCliRenderer()
+      const root = createRoot(renderer)
+
+      expect(root).toBeDefined()
+      expect(typeof root.render).toBe('function')
+      expect(typeof root.unmount).toBe('function')
+    })
+
+    it('render() accepts React elements', async () => {
+      const { createCliRenderer, createRoot, Text } = await import('..')
+
+      const renderer = await createCliRenderer()
+      const root = createRoot(renderer)
+
+      const element = React.createElement(Text, {}, 'Hello')
+
+      // render() should not throw
+      await expect(root.render(element)).resolves.not.toThrow()
+    })
+
+    it('render() can be called multiple times', async () => {
+      const { createCliRenderer, createRoot, Text } = await import('..')
+
+      const renderer = await createCliRenderer()
+      const root = createRoot(renderer)
+
+      // Multiple renders should not throw
+      await root.render(React.createElement(Text, {}, 'First'))
+      await root.render(React.createElement(Text, {}, 'Second'))
+      await root.render(React.createElement(Text, {}, 'Third'))
+    })
+
+    it('unmount() cleans up properly', async () => {
+      const { createCliRenderer, createRoot, Text } = await import('..')
+
+      const renderer = await createCliRenderer()
+      const root = createRoot(renderer)
+
+      await root.render(React.createElement(Text, {}, 'Hello'))
+
+      // unmount should not throw
+      expect(() => root.unmount()).not.toThrow()
+    })
+
+    it('unmount() can be called before render()', async () => {
+      const { createCliRenderer, createRoot } = await import('..')
+
+      const renderer = await createCliRenderer()
+      const root = createRoot(renderer)
+
+      // unmount without render should not throw
+      expect(() => root.unmount()).not.toThrow()
+    })
+
+    it('render() reuses the same root instance on subsequent calls', async () => {
+      const { createCliRenderer, createRoot, Text } = await import('..')
+      const { createRoot: mockCreateRoot } = await import('@opentui/react')
+
+      const renderer = await createCliRenderer()
+      const root = createRoot(renderer)
+
+      // First render - should create root
+      await root.render(React.createElement(Text, {}, 'First'))
+      const callCount1 = (mockCreateRoot as ReturnType<typeof vi.fn>).mock.calls.length
+
+      // Second render - should reuse root
+      await root.render(React.createElement(Text, {}, 'Second'))
+      const callCount2 = (mockCreateRoot as ReturnType<typeof vi.fn>).mock.calls.length
+
+      // createRoot should only be called once
+      expect(callCount2).toBe(callCount1)
+    })
+  })
+
+  // ============================================================================
+  // CLI() High-Level API Tests
+  // ============================================================================
+
+  describe('CLI() high-level API', () => {
+    it('CLI() returns instance with render method', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      expect(cli).toBeDefined()
+      expect(typeof cli.render).toBe('function')
+    })
+
+    it('CLI() returns terminal dimensions', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      expect(typeof cli.width).toBe('number')
+      expect(typeof cli.height).toBe('number')
+      expect(cli.width).toBeGreaterThan(0)
+      expect(cli.height).toBeGreaterThan(0)
+    })
+
+    it('CLI() clear() works', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      // clear() should not throw
+      expect(() => cli.clear()).not.toThrow()
+    })
+
+    it('CLI() destroy() cleans up', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      // destroy() should not throw
+      expect(() => cli.destroy()).not.toThrow()
+    })
+
+    it('CLI() requestRender() works', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      // requestRender() should not throw
+      expect(() => cli.requestRender()).not.toThrow()
+    })
+
+    it('CLI() exposes underlying renderer and root', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      expect(cli.renderer).toBeDefined()
+      expect(cli.root).toBeDefined()
+      expect(typeof cli.renderer.start).toBe('function')
+      expect(typeof cli.root.render).toBe('function')
+    })
+
+    it('CLI() accepts options', async () => {
+      const { CLI } = await import('..')
+      const { createCliRenderer: mockCreate } = await import('@opentui/core')
+
+      await CLI({
+        colorSupport: 'truecolor',
+        targetFps: 60,
+        useAlternateScreen: true,
+        useMouse: true,
+        exitOnCtrlC: false,
+      })
+
+      expect(mockCreate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          targetFps: 60,
+          useAlternateScreen: true,
+          useMouse: true,
+          exitOnCtrlC: false,
+        })
+      )
+    })
+
+    it('CLI() render accepts React elements', async () => {
+      const { CLI, Text, Box } = await import('..')
+
+      const cli = await CLI()
+
+      // render should not throw with various elements
+      expect(() => cli.render(React.createElement(Text, {}, 'Hello'))).not.toThrow()
+      expect(() =>
+        cli.render(
+          React.createElement(
+            Box,
+            { border: 'single' },
+            React.createElement(Text, {}, 'Boxed')
+          )
+        )
+      ).not.toThrow()
+    })
+  })
+
+  // ============================================================================
+  // Component Rendering Tests
+  // ============================================================================
+
+  describe('Component rendering', () => {
+    it('Box component renders with borders', async () => {
+      const { CLI, Box, Text } = await import('..')
+
+      const cli = await CLI()
+
+      const boxElement = React.createElement(
+        Box,
+        { border: 'single', padding: 1 },
+        React.createElement(Text, {}, 'Content')
+      )
+
+      // Should not throw when rendering Box with borders
+      expect(() => cli.render(boxElement)).not.toThrow()
+    })
+
+    it('Text component renders with colors', async () => {
+      const { CLI, Text } = await import('..')
+
+      const cli = await CLI()
+
+      const textElement = React.createElement(
+        Text,
+        { color: 'cyan', bold: true },
+        'Styled text'
+      )
+
+      // Should not throw when rendering styled Text
+      expect(() => cli.render(textElement)).not.toThrow()
+    })
+
+    it('nested components render correctly', async () => {
+      const { CLI, Box, Text } = await import('..')
+
+      const cli = await CLI()
+
+      const nestedElement = React.createElement(
+        Box,
+        { border: 'double', padding: 2 },
+        React.createElement(
+          Box,
+          { border: 'single', padding: 1 },
+          React.createElement(Text, { color: 'green' }, 'Nested content')
+        )
+      )
+
+      // Should not throw when rendering nested components
+      expect(() => cli.render(nestedElement)).not.toThrow()
+    })
+
+    it('complex component trees render', async () => {
+      const { CLI, Box, Text } = await import('..')
+
+      const cli = await CLI()
+
+      // Build a dashboard-like layout
+      const dashboard = React.createElement(
+        Box,
+        { flexDirection: 'row' },
+        // Sidebar
+        React.createElement(
+          Box,
+          { width: 20, border: 'single', flexDirection: 'column' },
+          React.createElement(Text, { bold: true }, 'Menu'),
+          React.createElement(Text, {}, 'Item 1'),
+          React.createElement(Text, {}, 'Item 2')
+        ),
+        // Content
+        React.createElement(
+          Box,
+          { flexGrow: 1, padding: 1 },
+          React.createElement(Text, { color: 'cyan', bold: true }, 'Dashboard'),
+          React.createElement(Text, {}, 'Welcome message here')
+        )
+      )
+
+      // Should not throw when rendering complex trees
+      expect(() => cli.render(dashboard)).not.toThrow()
+    })
+  })
+
+  // ============================================================================
+  // Renderer Lifecycle Tests
+  // ============================================================================
+
+  describe('Renderer lifecycle', () => {
+    it('full lifecycle: create -> render -> clear -> destroy', async () => {
+      const { CLI, Text } = await import('..')
+
+      const cli = await CLI()
+
+      // Render content
+      cli.render(React.createElement(Text, {}, 'Hello'))
+
+      // Clear screen
+      cli.clear()
+
+      // Render again
+      cli.render(React.createElement(Text, {}, 'World'))
+
+      // Destroy
+      cli.destroy()
+
+      // After destroy, methods should still be callable (may no-op)
+      // This tests cleanup doesn't cause errors
+    })
+
+    it('renderer can be started and stopped', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      // Access underlying renderer for lifecycle control
+      cli.renderer.start()
+      cli.renderer.stop()
+      cli.renderer.start()
+      cli.renderer.destroy()
+    })
+
+    it('multiple CLI instances can coexist', async () => {
+      const { CLI, Text } = await import('..')
+
+      const cli1 = await CLI()
+      const cli2 = await CLI()
+
+      cli1.render(React.createElement(Text, {}, 'CLI 1'))
+      cli2.render(React.createElement(Text, {}, 'CLI 2'))
+
+      cli1.destroy()
+      cli2.destroy()
+    })
+  })
+
+  // ============================================================================
+  // Error Handling Tests
+  // ============================================================================
+
+  describe('Error handling', () => {
+    it('handles null render gracefully', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      // Rendering null should not throw (used by clear())
+      expect(() => cli.render(null)).not.toThrow()
+    })
+
+    it('handles undefined render gracefully', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      // Rendering undefined should not throw
+      expect(() => cli.render(undefined as any)).not.toThrow()
+    })
+
+    it('destroy can be called multiple times', async () => {
+      const { CLI } = await import('..')
+
+      const cli = await CLI()
+
+      cli.destroy()
+      cli.destroy()
+      cli.destroy()
+      // Should not throw
+    })
+  })
+})