ratatui_testlib/lib.rs
1//! # ratatui_testlib
2//!
3//! A Rust library for integration testing of terminal user interface (TUI) applications.
4//!
5//! ## Overview
6//!
7//! `ratatui_testlib` provides a comprehensive testing framework for TUI applications built with
8//! libraries like Ratatui, with first-class support for:
9//!
10//! - **PTY-based testing**: Real terminal emulation with pseudo-terminal support
11//! - **Sixel graphics testing**: Position verification and bounds checking for Sixel images
12//! - **Bevy ECS integration**: Test Bevy-based TUI applications with `bevy_ratatui`
13//! - **Async runtime support**: Full Tokio async/await support
14//! - **Snapshot testing**: Integration with `insta` for visual regression testing
15//! - **Headless CI/CD**: Works without X11/Wayland for GitHub Actions
16//!
17//! ## Quick Start
18//!
19//! ```rust,no_run
20//! use ratatui_testlib::{TuiTestHarness, Result};
21//! use portable_pty::CommandBuilder;
22//!
23//! #[test]
24//! fn test_my_tui_app() -> Result<()> {
25//! // Create a test harness with 80x24 terminal
26//! let mut harness = TuiTestHarness::new(80, 24)?;
27//!
28//! // Spawn your TUI application
29//! let mut cmd = CommandBuilder::new("./my-tui-app");
30//! harness.spawn(cmd)?;
31//!
32//! // Wait for initial render
33//! harness.wait_for(|state| {
34//! state.contents().contains("Welcome")
35//! })?;
36//!
37//! // Send keyboard input
38//! harness.send_text("hello")?;
39//!
40//! // Capture screen state
41//! let contents = harness.screen_contents();
42//! assert!(contents.contains("hello"));
43//!
44//! Ok(())
45//! }
46//! ```
47//!
48//! ## Testing Sixel Graphics
49//!
50//! With the `sixel` feature enabled, you can verify Sixel graphics positioning:
51//!
52//! ```rust,no_run
53//! # #[cfg(feature = "sixel")]
54//! # {
55//! use ratatui_testlib::TuiTestHarness;
56//!
57//! # fn test_sixel() -> ratatui_testlib::Result<()> {
58//! let mut harness = TuiTestHarness::new(80, 24)?;
59//! // ... spawn your app and trigger Sixel rendering ...
60//!
61//! // Verify all Sixel graphics are within the preview area
62//! let preview_area = (5, 5, 30, 15); // row, col, width, height
63//! let sixel_regions = harness.state().sixel_regions();
64//! for region in sixel_regions {
65//! assert!(region.start_row >= preview_area.0);
66//! assert!(region.start_col >= preview_area.1);
67//! }
68//! # Ok(())
69//! # }
70//! # }
71//! ```
72//!
73//! ## Feature Flags
74//!
75//! - `async-tokio`: Enable Tokio async runtime support
76//! - `bevy`: Enable Bevy ECS integration
77//! - `bevy-ratatui`: Enable bevy_ratatui plugin support
78//! - `ratatui-helpers`: Enable Ratatui-specific test helpers
79//! - `sixel`: Enable Sixel graphics position tracking and testing
80//! - `snapshot-insta`: Enable snapshot testing with `insta`
81//! - `mvp`: Enable all MVP features (recommended for dgx-pixels)
82//!
83//! ## Architecture
84//!
85//! The library is organized into several layers:
86//!
87//! 1. **PTY Management** (`pty`): Pseudo-terminal creation and lifecycle
88//! 2. **Terminal Emulation** (`screen`): VT100 parsing and screen state
89//! 3. **Test Harness** (`harness`): High-level testing API
90//! 4. **Sixel Support** (`sixel`): Graphics protocol testing (MVP requirement)
91//! 5. **Bevy Integration** (`bevy`): ECS testing support (MVP requirement)
92//!
93//! ## Primary Use Case: dgx-pixels
94//!
95//! This library was built to support comprehensive integration testing for the
96//! [dgx-pixels](https://github.com/raibid-labs/dgx-pixels) project, with focus on:
97//!
98//! - Sixel graphics positioning within designated preview areas
99//! - Sixel clearing on screen transitions
100//! - Bevy ECS entity and component testing
101//! - Text input and cursor position verification
102//! - Async Tokio runtime compatibility
103
104#![warn(
105 missing_docs,
106 missing_debug_implementations,
107 rust_2018_idioms,
108 unreachable_pub
109)]
110#![deny(unsafe_code)]
111
112mod error;
113pub mod events;
114mod harness;
115mod pty;
116mod screen;
117
118#[cfg(feature = "sixel")]
119pub mod sixel;
120
121#[cfg(feature = "bevy")]
122pub mod bevy;
123
124// Public API exports
125pub use error::{Result, TermTestError};
126pub use events::{KeyCode, KeyEvent, Modifiers};
127pub use harness::TuiTestHarness;
128pub use pty::TestTerminal;
129pub use screen::{Cell, ScreenState, SixelRegion};
130
131#[cfg(feature = "sixel")]
132pub use sixel::{SixelCapture, SixelSequence};
133
134#[cfg(feature = "bevy")]
135pub use bevy::BevyTuiTestHarness;
136
137// Re-export commonly used types for convenience
138pub use portable_pty::CommandBuilder;