envision 0.17.0

A ratatui framework for collaborative TUI development with headless testing support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

//! Test harness for headless TUI testing.
//!
//! Envision provides three testing entry points. Pick the one that
//! matches the scope of what you're testing:
//!
//! | Harness | Use when… | Closure or App? | Time control |
//! |---|---|---|---|
//! | [`TestHarness`] | Testing a render closure or a widget in isolation | Closure | None (synchronous) |
//! | [`AppHarness`] | Testing a full `App` with async commands/subscriptions | App | Via `tokio::test(start_paused)` + `advance_time()` |
//! | [`Runtime::virtual_builder`][vb] | Programmatic control (agents, scripted demos, integration tests) | App | None |
//!
//! [vb]: crate::app::Runtime::virtual_builder
//!
//! ## `TestHarness` — widget-level testing
//!
//! Wraps a `CaptureBackend` with input simulation and assertion helpers.
//! Renders closures, not full `App` implementations. Synchronous — no
//! async runtime.
//!
//! ## `AppHarness` — App-level async testing
//!
//! Wraps a `Runtime<A, CaptureBackend>` and exposes time-control
//! primitives that pair with `#[tokio::test(start_paused = true)]`. Use
//! when your `App` has subscriptions, commands, or any time-dependent
//! logic.
//!
//! ## `Runtime::virtual_builder` — programmatic App control
//!
//! Constructed via `Runtime::<A, _>::virtual_builder(w, h).build()`.
//! Returns a `Runtime<A, CaptureBackend>` with `send()`, `dispatch()`,
//! `tick()`, and `display()` methods. Useful for AI agents, scripted
//! demos, and integration tests that need full App semantics without
//! the time-control ceremony of `AppHarness`.
//!
//! See `examples/test_harness.rs` for runnable examples of all three.
//!
//! # Example: TestHarness
//!
//! ```rust
//! use envision::harness::{TestHarness, Assertion};
//! use envision::annotation::Annotation;
//! use ratatui::widgets::Paragraph;
//!
//! let mut harness = TestHarness::new(80, 24);
//!
//! harness.render(|frame| {
//!     frame.render_widget(
//!         Paragraph::new("Hello, World!"),
//!         frame.area(),
//!     );
//! }).unwrap();
//!
//! harness.assert_contains("Hello, World!");
//! ```

mod app_harness;
mod assertions;
mod message_sender;
mod snapshot;
mod test_harness;

pub use app_harness::AppHarness;
pub use assertions::{Assertion, AssertionError, AssertionResult};
pub use message_sender::{MessageSendError, MessageSender, TrySendError};
pub use snapshot::{
    Snapshot, SnapshotFormat, SnapshotTest, assert_snapshot_eq, assert_snapshot_text,
};
pub use test_harness::TestHarness;