Struct ScreenState 

pub struct ScreenState { /* private fields */ }

Represents the current state of the terminal screen.

ScreenState is the core terminal emulator that tracks:

• Text content at each cell position
• Current cursor position
• Sixel graphics regions (when rendered via DCS sequences)

It wraps a vtparse parser that processes VT100/ANSI escape sequences and maintains the screen state accordingly.

Usage

The typical workflow is:

1. Create a ScreenState with desired dimensions
2. Feed PTY output bytes using feed()
3. Query the state using various accessor methods

Example

use ratatui_testlib::ScreenState;

let mut screen = ScreenState::new(80, 24);

// Feed some terminal output
screen.feed(b"\x1b[2J"); // Clear screen
screen.feed(b"\x1b[5;10H"); // Move cursor to (5, 10)
screen.feed(b"Hello!");

// Query the state
assert_eq!(screen.cursor_position(), (4, 16)); // 0-indexed
assert_eq!(screen.text_at(4, 9), Some('H'));
assert!(screen.contains("Hello"));

Implementations

impl ScreenState

pub fn new(width: u16, height: u16) -> Self

Creates a new screen state with the specified dimensions.

Initializes an empty screen filled with spaces, with the cursor at (0, 0).

Arguments

• width - Screen width in columns
• height - Screen height in rows

Example

use ratatui_testlib::ScreenState;

let screen = ScreenState::new(80, 24);
assert_eq!(screen.size(), (80, 24));
assert_eq!(screen.cursor_position(), (0, 0));

pub fn feed(&mut self, data: &[u8])

Feeds data from the PTY to the parser.

This processes VT100/ANSI escape sequences and updates the screen state, including:

• Text output
• Cursor movements
• Sixel graphics (tracked via DCS callbacks)

This method can be called multiple times to incrementally feed data. The parser maintains state across calls, so partial escape sequences are handled correctly.

Arguments

• data - Raw bytes from PTY output

Example

use ratatui_testlib::ScreenState;

let mut screen = ScreenState::new(80, 24);

// Feed data incrementally
screen.feed(b"Hello, ");
screen.feed(b"World!");

assert!(screen.contains("Hello, World!"));

pub fn contents(&self) -> String

Returns the screen contents as a string.

This includes all visible characters, preserving layout with newlines between rows. Empty cells are represented as spaces.

Returns

A string containing the entire screen contents, with rows separated by newlines.

Example

use ratatui_testlib::ScreenState;

let mut screen = ScreenState::new(10, 3);
screen.feed(b"Hello");

let contents = screen.contents();
// First line contains "Hello     " (padded to 10 chars)
// Second and third lines are all spaces
assert!(contents.contains("Hello"));

pub fn row_contents(&self, row: u16) -> String

Returns the contents of a specific row.

Arguments

• row - Row index (0-based)

Returns

The row contents as a string, or empty string if row is out of bounds.

pub fn text_at(&self, row: u16, col: u16) -> Option<char>

Returns the character at a specific position.

Arguments

• row - Row index (0-based)
• col - Column index (0-based)

Returns

The character at the position, or None if out of bounds.

pub fn get_cell(&self, row: u16, col: u16) -> Option<&Cell>

Returns the complete cell (character + attributes) at a specific position.

This method provides access to the full cell state including colors and text attributes, enabling verification of ANSI escape sequence handling.

Arguments

• row - Row index (0-based)
• col - Column index (0-based)

Returns

A reference to the cell, or None if out of bounds.

Example

use ratatui_testlib::ScreenState;

let mut screen = ScreenState::new(80, 24);
screen.feed(b"\x1b[31mRed\x1b[0m");

if let Some(cell) = screen.get_cell(0, 0) {
    assert_eq!(cell.c, 'R');
    assert_eq!(cell.fg, Some(1)); // Red = color 1
}

pub fn cursor_position(&self) -> (u16, u16)

Returns the current cursor position.

Returns

A tuple of (row, col) with 0-based indexing.

pub fn size(&self) -> (u16, u16)

Returns the screen dimensions.

Returns

A tuple of (width, height) in columns and rows.

pub fn sixel_regions(&self) -> &[SixelRegion]

Returns all Sixel graphics regions currently on screen.

This method provides access to all Sixel graphics that have been rendered via DCS (Device Control String) sequences. Each region includes position and dimension information.

This is essential for verifying Sixel positioning in tests, particularly for ensuring that graphics appear within designated preview areas.

Returns

A slice of SixelRegion containing all detected Sixel graphics.

Example

use ratatui_testlib::ScreenState;

let mut screen = ScreenState::new(80, 24);
// ... render some Sixel graphics ...

let regions = screen.sixel_regions();
for (i, region) in regions.iter().enumerate() {
    println!("Region {}: position ({}, {}), size {}x{}",
        i, region.start_row, region.start_col,
        region.width, region.height);
}

pub fn has_sixel_at(&self, row: u16, col: u16) -> bool

Checks if a Sixel region exists at the given position.

This method checks if any Sixel region has its starting position at the exact (row, col) coordinates provided.

Arguments

• row - Row to check (0-indexed)
• col - Column to check (0-indexed)

Returns

true if a Sixel region starts at the given position, false otherwise.

Example

use ratatui_testlib::ScreenState;

let mut screen = ScreenState::new(80, 24);
// ... render Sixel at position (5, 10) ...

assert!(screen.has_sixel_at(5, 10));
assert!(!screen.has_sixel_at(0, 0));

pub fn debug_contents(&self) -> String

Returns the screen contents for debugging purposes.

This is currently an alias for contents(), but may include additional debug information in the future.

Returns

A string containing the screen contents.

pub fn contains(&self, text: &str) -> bool

Checks if the screen contains the specified text.

This is a convenience method that searches the entire screen contents for the given substring. It’s useful for simple text-based assertions in tests.

Arguments

• text - Text to search for

Returns

true if the text appears anywhere on the screen, false otherwise.

Example

use ratatui_testlib::ScreenState;

let mut screen = ScreenState::new(80, 24);
screen.feed(b"Welcome to the application");

assert!(screen.contains("Welcome"));
assert!(screen.contains("application"));
assert!(!screen.contains("goodbye"));