Skip to content

feat: add TUI integration tests#549

Open
aidandaly24 wants to merge 8 commits intomainfrom
feat/tui-harness-tests
Open

feat: add TUI integration tests#549
aidandaly24 wants to merge 8 commits intomainfrom
feat/tui-harness-tests

Conversation

@aidandaly24
Copy link
Contributor

@aidandaly24 aidandaly24 commented Mar 17, 2026

Description

Adds 27 integration tests across 5 test suites that exercise the TUI harness against the real AgentCore CLI binary. These tests validate that AI agents can reliably drive the TUI through all major user flows.

Test suites:

  • harness.test.ts (9 tests) — Self-tests for TuiSession using simple Unix commands (echo, cat, bash). Validates launch, sendKeys, close, dead-session errors, waitFor success/timeout, LaunchError, concurrent sessions, and numbered readScreen.
  • navigation.test.ts (8 tests) — TUI navigation against the real CLI. HomeScreen rendering, HelpScreen rendering, forward/backward navigation, exit via double-Escape and Ctrl+C.
  • create-flow.test.ts (3 tests) — Full create-project wizard: create with agent (20+ step wizard), create without agent, and back-navigation during wizard.
  • add-flow.test.ts (4 tests) — Add-resource flow: navigate to Add Resource screen, drill into Add Agent wizard, and escape-back at each level.
  • deploy-screen.test.ts (3 tests) — Deploy screen: renders, shows AWS configuration, supports Escape-back. Never actually deploys.

Infrastructure:

  • setup.ts — Vitest global setup checking harness availability and cleaning up orphaned PTY sessions
  • helpers.ts — Re-exports createMinimalProjectDir from the harness library

Stacked on #548 — retarget to main after PR 1 merges.

Related Issue

Closes #

Documentation PR

N/A — test documentation is in docs/TESTING.md (included in PR #548)

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Other (please describe):

Testing

How have you tested the change?

  • I ran npm run test:unit and npm run test:integ
  • I ran npm run typecheck
  • I ran npm run lint
  • If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

All 27 tests pass: npm run test:tui → 27 passed, 0 failed.

Checklist

  • I have read the CONTRIBUTING document
  • I have added any necessary tests that prove my fix is effective or my feature works
  • I have updated the documentation accordingly
  • I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

@aidandaly24 aidandaly24 force-pushed the feat/tui-harness-tests branch from 3110b1e to 04533ce Compare March 17, 2026 19:14
aidandaly24 and others added 6 commits March 18, 2026 12:05
@aidandaly24 @claude
feat: add TUI harness core library
fc97823 
Headless terminal harness using node-pty + @xterm/headless that spawns
real CLI processes in a PTY and reads screen state programmatically.

Core components:
- TuiSession: spawn, sendKeys, sendSpecialKey, readScreen, waitFor, close
- SettlingMonitor: text-content comparison to filter cursor blink
- Screen reader: viewport/scrollback reading, numbered output
- Key map: named keys to escape sequence mapping
- Session manager: global registry with process-exit cleanup
- Availability check: graceful skip when node-pty is missing

waitFor() throws WaitForTimeoutError on timeout (not silent return).
launch() races settle vs process exit, throws LaunchError on crash.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@aidandaly24 @claude
feat: add MCP server for TUI harness
01cd102 
7 MCP tools exposed via stdio transport for AI agents to drive the TUI:
tui_launch, tui_send_keys, tui_read_screen, tui_wait_for,
tui_screenshot, tui_close, tui_list_sessions.

Session map with max 10 concurrent sessions. tui_wait_for catches
WaitForTimeoutError and returns {found: false} (not an MCP error).
tui_launch defaults to AgentCore CLI when no command specified.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@aidandaly24 @claude
chore: add dependencies and build config for TUI harness
d88dc56 
- devDependencies: @xterm/headless, @modelcontextprotocol/sdk
- optionalDependencies: node-pty (native addon, graceful skip)
- esbuild: second entry point for mcp-harness bundle
- vitest: new 'tui' project with fileParallelism: false
- .mcp.json: MCP server discovery for Claude Code
- package.json: bin entry + test:tui script

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@aidandaly24 @claude
docs: add TUI harness documentation
67a9502 
AGENTS.md: TUI harness section with MCP tool reference, complete 27-step
create wizard example (verified against real TUI), screen identification
markers table, screenshot format, error recovery patterns, navigation
patterns, and known limitations.

TESTING.md: TUI integration test guide with TuiSession API reference,
ScreenState type, special keys list, waitFor vs settling guidance,
WaitForTimeoutError output example, and LaunchError handling.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@aidandaly24 @claude
refactor: consolidate TUI harness into src/tui-harness/
cf56679 
Move harness code from two separate directories (src/test-utils/tui-harness/
and src/mcp-harness/) into a single src/tui-harness/ directory with lib/ and
mcp/ subdirectories. Also cleans up dead code in tools.ts, derives SpecialKey
type from SPECIAL_KEY_VALUES array (single source of truth), and fixes
cross-boundary import of createMinimalProjectDir.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@aidandaly24 @claude
chore: make TUI harness build opt-in for dev only
1541fc3 
The harness is dev-only tooling for AI agents and integration tests.
It should not ship to end users who install the CLI.

- Gate MCP harness esbuild behind BUILD_HARNESS=1 env var
- Remove agent-tui-harness bin entry from package.json
- Add !dist/mcp-harness to files array (npm publish exclusion)
- Remove node-pty from optionalDependencies (stays in devDependencies)
- Add build:harness script, update test:tui to use it
- Update AGENTS.md to reference npm run build:harness

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
jesseturner21 and others added 2 commits March 18, 2026 12:06
@jesseturner21 @claude @aidandaly24
docs: move TUI harness guide from AGENTS.md to docs/tui-harness.md
ec15d99 
Reduces AGENTS.md context overhead for agents that don't need TUI harness
details. Leaves a one-line pointer to the full guide in docs/.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@aidandaly24 @claude
feat: add TUI integration tests
6277067 
27 tests across 5 suites verifying the TUI harness against the real
AgentCore CLI: harness self-tests, navigation flows, create wizard,
add-resource flows, and deploy screen rendering.

Tests use describe.skipIf(!isAvailable) to gracefully skip when
node-pty is not installed. createMinimalProjectDir provides fast
(~10ms) project directory setup without npm install.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@aidandaly24 aidandaly24 force-pushed the feat/tui-harness-tests branch from 04533ce to 6277067 Compare March 18, 2026 16:06
Base automatically changed from feat/tui-harness to main March 19, 2026 12:47
@jesseturner21 jesseturner21 requested a review from a team March 19, 2026 12:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@aidandaly24 @jesseturner21