vue-tui/docs/superpowers/specs/2026-05-27-ink-test-parity-design.md

Ink Test Parity — Design Spec

Goal

Supplement ~290 missing tests to reach parity with Ink v7.0.4's test suite. Only covers code already implemented in vue-tui. Excludes kitty keyboard protocol management, alternateScreen, synchronized output (BSU/ESU), and React concurrent mode (assigned to other agents or N/A).

Approach

Expand existing test files in-place. No new test files unless a module has zero tests today. Follow existing test patterns: unit tests colocated with source (packages/runtime/src/**/*.test.ts), integration tests in packages/runtime-tests/integration/**/*.test.tsx.

All tests reference Ink's test suite at /tmp/ink/test/ as the source of truth. Each test should be adapted to Vue's API (defineComponent, h(), shallowRef) and vue-tui's test helper (render() from @vue-tui/testing).

Scope Exclusions

• kittyKeyboard (77 tests) — feature not implemented, separate agent
• alternateScreen (12 tests) — feature not implemented, separate agent
• synchronized output (5 tests) — feature not implemented
• concurrent mode (20 tests) — React-specific, N/A
• build-output (4 tests) — Ink build verification, not applicable
• reconciler (10 tests) — React reconciler internals, not applicable

---

Part A: Unit Tests (~125 tests)

Pure function tests. No render helper needed. Colocated with source in packages/runtime/src/.

A1: sanitize-ansi (+24 tests)

File: packages/runtime/src/paint/sanitize-ansi.test.ts (5 → 29) Ink ref: /tmp/ink/test/sanitize-ansi.ts

Missing categories:

• C1 variant stripping (CSI, OSC with C1/ESC ST/BEL terminators)
• DCS passthrough stripping (tmux, incomplete, BEL in payload)
• SOS control strings (all terminator variants, escaped ESC in payload, SGR preserved around SOS)
• Private-parameter m-sequences
• ESC ST stripping, malformed ESC sequences, incomplete CSI
• Standalone ST bytes, standalone C1 controls

A2: ansi-tokenizer (+19 tests)

File: packages/runtime/src/paint/ansi-tokenizer.test.ts (7 → 26) Ink ref: /tmp/ink/test/ansi-tokenizer.ts

Missing categories:

• C1 CSI with intermediates, C1 SGR CSI, incomplete C1 CSI/OSC
• OSC with ST terminator (vs BEL)
• tmux DCS as single token, DCS with BEL in payload
• ESC/C1 SOS (ST, C1 ST, BEL-invalid, incomplete, escaped ESC)
• Incomplete CSI/ESC-intermediate marked as invalid
• Standalone C1 controls

A3: input-parser (+32 tests)

File: packages/runtime/src/io/input-parser.test.ts (12 → 44) Ink ref: /tmp/ink/test/input-parser.ts

Missing categories:

• Multi-key chunks, CSI parameters, SS3 sequences
• Meta+CSI/SS3 double escape, escaped printable/supplementary codepoints
• Legacy ESC[[ (mixed, across chunks, combined)
• Incomplete holding states (legacy, SS3, double-escape)
• Flush pending (escape, CSI, SS3, legacy), meta+SS3
• Empty chunk handling, text + incomplete escape
• 14 backspace/delete splitting cases
• 10 bracketed paste tests (event creation, split delivery, empty paste, chunk assembly, backspace in paste)

A4: cursor-helpers (+7 tests)

File: packages/runtime/src/io/cursor-helpers.test.ts (10 → 17) Ink ref: /tmp/ink/test/cursor-helpers.tsx

Missing:

• buildCursorSuffix (first line, single-line output)
• buildReturnToBottom (moves down, no cursorDown at bottom)
• buildCursorOnlySequence (full sequence with hide prefix, no hide when cursor not shown)
• buildReturnToBottomPrefix (undefined previousCursorPosition)

A5: frame-writer / log-update (+34 tests)

File: packages/runtime/src/io/frame-writer.test.ts (1 → 35) Ink ref: /tmp/ink/test/log-update.tsx

vue-tui's frame-writer wraps a self-built log-update. Tests should cover the frame-writer's public API (not log-update internals).

Missing categories:

• Standard rendering: render, update, skip identical output
• Incremental rendering: render, update, skip identical, surgical line updates, cursor rewind, clear extra lines, grow, single write call, shrinking output
• clear()/done() reset behavior, multiple clear(), sync()+update
• 14 cursor positioning tests (setCursorPosition, cursor suffix, return-to-bottom)
• 6 no-trailing-newline tests (fullscreen mode behavior)
• Render-to-empty edge case

A6: text-width (+9 tests)

File: packages/runtime/src/host/text-measure.test.ts (4 → 13) Ink ref: /tmp/ink/test/text-width.tsx

Missing:

• Wide chars in fixed-width Box, CJK fixed-width
• Mixed ASCII+wide char width
• ANSI styled text width
• Empty Text sibling
• Truncate CJK (3 variants + box-width)
• Overlay CJK 2nd/1st cell, CJK overlay on CJK
• Clipped empty write

---

Part B: Component & Composable Tests (~114 tests)

Functional tests using render() from @vue-tui/testing. Located in packages/runtime-tests/integration/.

B1: text component (+15 tests)

File: packages/runtime-tests/integration/components/text.test.tsx (31 → 46) Ink ref: /tmp/ink/test/text.tsx

Missing: ANSI sanitization integration through <Text> — the text component should strip non-SGR ANSI sequences while preserving SGR styling and OSC hyperlinks. Ink has ~18 tests for this; ~15 are unique after deduplication.

Categories:

• Strip cursor movement/position/erase sequences
• Preserve SGR, OSC hyperlinks (BEL+ST), C1 OSC, SGR colon params
• Strip non-SGR CSI, C1 non-SGR CSI, ESC controls
• Strip tmux DCS (BEL+ST), C1 DCS, PM/APC, C1 PM/APC, ESC/C1 SOS
• Strip malformed SOS, preserve SGR around SOS
• Strip incomplete DCS/C1 DCS/OSC/C1 OSC/ESC, standalone ST/C1

B2: use-animation (+36 tests)

File: packages/runtime-tests/integration/composables/use-animation.test.tsx (9 → 45) Ink ref: /tmp/ink/test/use-animation.tsx

Missing categories:

• Shared timer: same/different intervals, cleanup/recreation, stays alive, inactive animations
• Timer leak prevention, frame catch-up
• isActive/interval reset behavior (frame, time, delta)
• Different interval rates
• Edge intervals: NaN, Infinity, -Infinity, oversized, zero, negative
• maxFps interaction (4 tests)
• Delta with throttled ticks
• Pausing stops ticks, interval change unsubscribes
• Wall clock protection, debug+non-interactive modes
• Newly mounted/activated don't inherit time
• Same-interval rerender stability
• time/delta progression
• reset() (function, stable ref, while paused)
• Unmount before first tick, resume cycles, isActive false from mount

B3: use-box-metrics / measure (+19 tests)

Files:

• packages/runtime-tests/integration/composables/use-box-metrics.test.tsx (9 → ~24)
• packages/runtime/src/host/text-measure.test.ts (see A6) Ink ref: /tmp/ink/test/use-box-metrics.tsx + measure-element.tsx + measure-text.tsx

Missing useBoxMetrics (11):

• Resize updates, tracked ref on resize
• Sibling content changes (2 variants)
• Tracked ref attaches after initial render
• No extra re-renders, resize listener cleanup
• No crash after unmount+resize, zeros when ref unattached
• hasMeasured lifecycle (3), resets on unmount

Missing measure-element (4):

• After state update, multiple updates, useLayoutEffect, throttled

Missing measure-text (4, beyond A6):

• Cache behavior, multiline+wide chars

B4: screen-reader (+11 tests)

File: packages/runtime-tests/integration/accessibility/screen-reader.test.tsx (14 → 25) Ink ref: /tmp/ink/test/screen-reader.tsx

Missing:

• aria-label on Text/Box in screen-reader mode
• Omit ANSI styling
• Multiple Text components, nested Box+Text, null component
• aria-state variants (busy, disabled, expanded, multiline, multiselectable, readonly, required, selected)
• Multi-line text/nested row layout, roles on multi-line
• Listbox with multiselectable

B5: render-to-string (+18 tests)

File: packages/runtime-tests/integration/render-to-string.test.tsx (14 → 32) Ink ref: /tmp/ink/test/render-to-string.tsx

Missing:

• Text with variable, nested text, empty fragment
• Box padding, flex row/column, margin, gap
• Fixed width+height, Spacer, Newline, Border
• Colored/bold text, wrap/truncate
• Default/custom columns, Transform
• Static (3 variants)
• Effect behavior (3: initial before effects, useLayoutEffect, cleanup)
• Error handling (3: propagation, text-outside-Text, recovery)
• Independent calls, deeply nested tree

B6: cursor composable (+7 tests)

File: packages/runtime-tests/integration/composables/use-cursor.test.tsx (5 → 12) Ink ref: /tmp/ink/test/cursor.tsx

Missing:

• Cursor follows text input, space input cursor move
• Cursor cleared on unmount
• No screen scroll on subsequent renders
• useStdout/useStderr write with cursor
• Debug mode write interactions

B7: components general (+8 tests)

Files: various in packages/runtime-tests/integration/components/ Ink ref: /tmp/ink/test/components.tsx (63 in-scope after exclusions)

vue-tui already covers most. Gap is ~8 tests:

• OSC hyperlink wrapping (6: BEL/ST wrap, non-hyperlink, hard-wrap BEL/ST single-word)
• Text with fragment
• Link ANSI escapes closed properly

---

Part C: Layout Tests (+22 tests)

Small gaps across 9 existing layout test files. All use render() helper.

File	Current	Target	Gap
display.test.tsx	2	4	+2
gap.test.tsx	3	6	+3
flex-direction.test.tsx	5	7	+2
flex-justify-content.test.tsx	10	12	+2
margin.test.tsx	11	13	+2
padding.test.tsx	12	14	+2
width-height.test.tsx	18	22	+4
overflow.test.tsx	36	40	+4
position.test.tsx	11	12	+1

---

Part D: Render Lifecycle & Integration (+29 tests)

D1: render lifecycle (+27 tests)

Files: packages/runtime-tests/integration/lifecycle/*.test.tsx + pty/render.test.ts Ink ref: /tmp/ink/test/render.tsx (56 in-scope after exclusions)

Missing categories:

• Clear output behavior
• Console intercept
• Rerender on resize
• Throttle to maxFps
• onRender metrics
• No throttled render after unmount, unmount forces pending
• waitUntilExit timing
• waitUntilRenderFlush suite (6 tests)
• Issue-596 effect timing
• Exit value ordering (3 tests)
• Cross-realm Error (2 tests)
• Unmount with ended stdout (3 tests)
• Primary screen cleanup
• CI/non-TTY rendering (4 tests)
• Non-interactive mode suite

D2: hooks misc (+2 tests)

Files: existing use-input / use-stdout tests Ink ref: /tmp/ink/test/hooks.tsx

Missing:

• "ignore input if not active" (multiple hooks variant)
• useStdout PTY write variant

---

Execution

4 Parts, executed sequentially via subagent-driven development. Each Part produces a branch → PR.

Estimated effort:

• Part A: ~125 tests, mostly mechanical (copy Ink test logic, adapt to vitest/vue-tui API)
• Part B: ~114 tests, moderate (need render helper, Vue component adaptation)
• Part C: ~22 tests, small (fill gaps in existing files)
• Part D: ~29 tests, moderate (lifecycle timing, some may need PTY)

Total: ~290 tests across ~25 existing files.