Testing and Advanced Features

This document covers the testing infrastructure, fallback mechanisms for non-interactive environments, and advanced input processing in hypervel/prompts. These features enable robust test coverage, graceful degradation in CI/CD environments, and sophisticated keyboard interaction patterns.

Scope of This Document:

• Testing prompts with mocked terminal I/O using the FakesInputOutput trait
• Implementing fallback behavior for non-interactive environments with the Fallback trait
• Understanding key input handling, event listeners, and navigation patterns

For information about the core prompt lifecycle and state management, see The Prompt Lifecycle. For details on implementing custom prompts, see Core Architecture.

---

Testing with Mocked Terminal I/O

The FakesInputOutput trait provides a comprehensive testing infrastructure for prompts, allowing tests to simulate terminal interactions without requiring actual terminal I/O. This trait is designed for use with PHPUnit and Mockery.

The FakesInputOutput Trait

The FakesInputOutput trait src/Concerns/FakesInputOutput.php13-114 enables tests to:

• Mock the Terminal instance to prevent real terminal interaction
• Queue simulated key presses for automated testing
• Capture buffered output for assertions
• Strip ANSI escape sequences for simplified assertions

Initializing Test Mode

The fake() method sets up the testing environment:

When called, this method src/Concerns/FakesInputOutput.php20-44:

1. Forces interactive mode by calling static::interactive()
2. Creates a Mockery mock of the Terminal class
3. Configures default method stubs for common terminal operations:
   • write() - Output operations (no-op in tests)
   • exit() - Terminal exit handling
   • setTty() / restoreTty() - TTY state management
   • cols() / lines() - Returns fixed dimensions (80×24)
   • initDimensions() - Dimension initialization
4. Queues the provided $keys array for sequential reading
5. Replaces the static $terminal property with the mock
6. Sets output to BufferedConsoleOutput for capture

Testing Workflow Diagram

Sources: src/Concerns/FakesInputOutput.php13-114

Simulating Key Presses

The fakeKeyPresses() method src/Concerns/FakesInputOutput.php56-61 provides the mechanism for queueing keyboard input:

This method iterates over the $keys array and invokes the provided $callable for each key. The default implementation in fake() configures the mock to return each key sequentially when Terminal->read() is called src/Concerns/FakesInputOutput.php35-38

Key Press Simulation Example:

Output Assertions

The trait provides four assertion methods for validating prompt output:

Method	Purpose	Line Reference
assertOutputContains(string $string)	Assert raw output contains string (including ANSI codes)	src/Concerns/FakesInputOutput.php66-69
assertOutputDoesntContain(string $string)	Assert raw output excludes string	src/Concerns/FakesInputOutput.php74-77
assertStrippedOutputContains(string $string)	Assert stripped output contains string (no ANSI codes)	src/Concerns/FakesInputOutput.php82-85
assertStrippedOutputDoesntContain(string $string)	Assert stripped output excludes string	src/Concerns/FakesInputOutput.php90-93

These methods rely on two helper methods:

• content() src/Concerns/FakesInputOutput.php98-105: Returns raw buffered output including ANSI escape sequences. Throws RuntimeException if fake() was not called first.

• strippedContent() src/Concerns/FakesInputOutput.php110-113: Returns output with ANSI escape sequences removed using regex pattern /\e\\[[0-9;?]*[A-Za-z]/.

Testing Example:

Sources: src/Concerns/FakesInputOutput.php13-114

---

Fallback Implementations

The Fallback trait provides a mechanism for prompts to use alternative implementations in non-interactive environments, such as CI/CD pipelines, Docker containers, or automated scripts where terminal control is unavailable.

Fallback Architecture

The Fallback trait src/Concerns/Fallback.php10-63 maintains:

• $shouldFallback src/Concerns/Fallback.php15: Static boolean flag indicating whether fallback mode is active
• $fallbacks src/Concerns/Fallback.php22: Static array mapping class names to fallback closures

Fallback Decision Flow

Sources: src/Concerns/Fallback.php10-63

Enabling Fallback Mode

The fallbackWhen() method src/Concerns/Fallback.php27-30 conditionally enables fallback mode:

This method uses OR logic to preserve the fallback state once enabled:

Common Fallback Conditions:

Registering Fallback Implementations

The fallbackUsing() method src/Concerns/Fallback.php45-48 registers a closure to be invoked when fallback mode is active:

The closure receives the prompt instance ($this) and should return the same type as the prompt's normal return value.

Fallback Registration Example:

Executing Fallback Logic

The shouldFallback() method src/Concerns/Fallback.php35-38 determines whether to use fallback:

The fallback() method src/Concerns/Fallback.php53-62 executes the registered fallback:

This method:

1. Retrieves the registered closure for the current prompt class
2. Throws RuntimeException if no fallback is registered src/Concerns/Fallback.php58
3. Invokes the closure with $this as the argument
4. Returns the closure's result

Fallback State Table

$shouldFallback	Fallback Registered?	Behavior
false	No	Normal execution
false	Yes	Normal execution
true	No	Normal execution
true	Yes	Calls fallback()

Sources: src/Concerns/Fallback.php10-63

---

Key Handling and Input Processing

Prompts process keyboard input through a sophisticated event-driven system that translates raw terminal input into high-level navigation and editing commands.

Key Constants and Input Events

While the specific Key class file is not provided in the sources, the system uses key constants throughout the codebase. Based on the architecture diagrams and trait implementations, key handling follows this pattern:

Key Input Processing Flow

Navigation Patterns Across Prompt Types

Different prompt types implement specialized key handling patterns:

Prompt Type Key Handling Matrix

Prompt Type	Navigation Keys	Editing Keys	Control Keys	Special Behavior
SelectPrompt	UP/DOWN, HOME/END	N/A	ENTER (submit), ESC (cancel)	Uses Scrolling trait for list navigation
MultiSelectPrompt	UP/DOWN, HOME/END	SPACE (toggle)	ENTER (submit), ESC (cancel)	Multiple selection state tracking
SearchPrompt	UP/DOWN (filtered)	Character keys, BACKSPACE	ENTER (submit), ESC (cancel)	Uses TypedValue + Scrolling, dynamic filtering
TextPrompt	LEFT/RIGHT, HOME/END	Character keys, BACKSPACE, DELETE	ENTER (submit), ESC (cancel)	Inline cursor positioning
TextareaPrompt	UP/DOWN/LEFT/RIGHT	Character keys, ENTER (newline)	CTRL+D (submit), ESC (cancel)	Multi-line editing

Event Listener Integration

The Events trait provides the foundation for key handling through an observer pattern. While the specific implementation details are in src/Concerns/Events.php (not provided in sources), prompts use this pattern:

Event Registration Pattern:

Key Press Event Flow:

1. Terminal reads raw input via Terminal->read()
2. Base Prompt's input loop emits 'key' event
3. Registered listeners receive the key constant
4. Traits (Scrolling, TypedValue) update internal state
5. Prompt-specific logic handles state transitions
6. Cursor trait updates terminal cursor position
7. Renderer displays updated state

Advanced Input Processing Features

Multi-byte Character Support:

The system handles UTF-8 multi-byte characters for international keyboard input, particularly important for:

• Text input prompts accepting Unicode characters
• Search prompts filtering international option labels
• Display components rendering multi-byte text correctly

Viewport Management:

The Scrolling trait (see Scrolling Lists) calculates visible windows for long lists:

• highlighted: Current selection index
• firstVisible: First visible option index
• Automatic scrolling when selection moves beyond viewport boundaries
• Configurable scroll distance via scroll property

Input Validation Integration:

Key handling integrates with the validation system (see State Management and Validation):

• ENTER key triggers validation before submission
• Invalid input displays error state without exiting
• ESC key bypasses validation and cancels prompt
• Validation errors maintain current input value for correction

Sources: High-level architecture diagrams, src/Concerns/FakesInputOutput.php1-114 src/Concerns/Fallback.php1-63

---

Testing Strategy Summary

The testing infrastructure enables comprehensive test coverage through three complementary mechanisms:

1. Terminal Mocking (FakesInputOutput): Simulates terminal I/O with predictable key sequences
2. Fallback System (Fallback): Provides alternative implementations for non-interactive contexts
3. Event System (Events trait): Decouples key handling from prompt logic for testability

This layered approach allows testing at multiple levels:

• Unit tests: Mock terminal, assert output contains expected strings
• Integration tests: Use fallback implementations to test without terminal
• End-to-end tests: Run in actual terminal with keyboard simulation

For information about implementing custom prompts with these features, see The Base Renderer and Reusable Traits and Concerns.