Struct TestBackend

pub struct TestBackend { /* private fields */ }

A Backend implementation used for integration testing that renders to an memory buffer.

Note: that although many of the integration and unit tests in ratatui are written using this backend, it is preferable to write unit tests for widgets directly against the buffer rather than using this backend. This backend is intended for integration tests that test the entire terminal UI.

Example

use ratatui::backend::{Backend, TestBackend};

let mut backend = TestBackend::new(10, 2);
backend.clear()?;
backend.assert_buffer_lines(["          "; 2]);

Implementations

impl TestBackend

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

Creates a new TestBackend with the specified width and height.

pub fn with_lines<'line, Lines>(lines: Lines) -> Self

where Lines: IntoIterator, Lines::Item: Into<Line<'line>>,

Creates a new TestBackend with the specified lines as the initial screen state.

The backend’s screen size is determined from the initial lines.

pub const fn buffer(&self) -> &Buffer

Returns a reference to the internal buffer of the TestBackend.

pub const fn scrollback(&self) -> &Buffer

Returns a reference to the internal scrollback buffer of the TestBackend.

The scrollback buffer represents the part of the screen that is currently hidden from view, but that could be accessed by scrolling back in the terminal’s history. This would normally be done using the terminal’s scrollbar or an equivalent keyboard shortcut.

The scrollback buffer starts out empty. Lines are appended when they scroll off the top of the main buffer. This happens when lines are appended to the bottom of the main buffer using Backend::append_lines.

The scrollback buffer has a maximum height of u16::MAX. If lines are appended to the bottom of the scrollback buffer when it is at its maximum height, a corresponding number of lines will be removed from the top.

pub fn resize(&mut self, width: u16, height: u16)

Resizes the TestBackend to the specified width and height.

pub fn assert_buffer(&self, expected: &Buffer)

Asserts that the TestBackend’s buffer is equal to the expected buffer.

This is a shortcut for assert_eq!(self.buffer(), &expected).

Panics

When they are not equal, a panic occurs with a detailed error message showing the differences between the expected and actual buffers.

pub fn assert_scrollback(&self, expected: &Buffer)

Asserts that the TestBackend’s scrollback buffer is equal to the expected buffer.

This is a shortcut for assert_eq!(self.scrollback(), &expected).

Panics

When they are not equal, a panic occurs with a detailed error message showing the differences between the expected and actual buffers.

pub fn assert_scrollback_empty(&self)

Asserts that the TestBackend’s scrollback buffer is empty.

Panics

When the scrollback buffer is not equal, a panic occurs with a detailed error message showing the differences between the expected and actual buffers.

pub fn assert_buffer_lines<'line, Lines>(&self, expected: Lines)

where Lines: IntoIterator, Lines::Item: Into<Line<'line>>,

Asserts that the TestBackend’s buffer is equal to the expected lines.

This is a shortcut for assert_eq!(self.buffer(), &Buffer::with_lines(expected)).

Panics

When they are not equal, a panic occurs with a detailed error message showing the differences between the expected and actual buffers.

pub fn assert_scrollback_lines<'line, Lines>(&self, expected: Lines)

where Lines: IntoIterator, Lines::Item: Into<Line<'line>>,

Asserts that the TestBackend’s scrollback buffer is equal to the expected lines.

This is a shortcut for assert_eq!(self.scrollback(), &Buffer::with_lines(expected)).

Panics

When they are not equal, a panic occurs with a detailed error message showing the differences between the expected and actual buffers.

pub fn assert_cursor_position<P: Into<Position>>(&mut self, position: P)

Asserts that the TestBackend’s cursor position is equal to the expected one.

This is a shortcut for assert_eq!(self.get_cursor_position().unwrap(), expected).

Panics

When they are not equal, a panic occurs with a detailed error message showing the differences between the expected and actual position.

Trait Implementations

impl Backend for TestBackend

fn append_lines(&mut self, line_count: u16) -> Result<()>

Inserts n line breaks at the current cursor position.

After the insertion, the cursor x position will be incremented by 1 (unless it’s already at the end of line). This is a common behaviour of terminals in raw mode.

If the number of lines to append is fewer than the number of lines in the buffer after the cursor y position then the cursor is moved down by n rows.

If the number of lines to append is greater than the number of lines in the buffer after the cursor y position then that number of empty lines (at most the buffer’s height in this case but this limit is instead replaced with scrolling in most backend implementations) will be added after the current position and the cursor will be moved to the last row.

fn draw<'a, I>(&mut self, content: I) -> Result<()>

where I: Iterator<Item = (u16, u16, &'a Cell)>,

Draw the given content to the terminal screen.

fn hide_cursor(&mut self) -> Result<()>

Hide the cursor on the terminal screen.

fn show_cursor(&mut self) -> Result<()>

Show the cursor on the terminal screen.

fn get_cursor_position(&mut self) -> Result<Position>

Get the current cursor position on the terminal screen.

fn set_cursor_position<P: Into<Position>>(&mut self, position: P) -> Result<()>

Set the cursor position on the terminal screen to the given x and y coordinates.

fn clear(&mut self) -> Result<()>

Clears the whole terminal screen

fn clear_region(&mut self, clear_type: ClearType) -> Result<()>

Clears a specific region of the terminal specified by the ClearType parameter

fn size(&self) -> Result<Size>

Get the size of the terminal screen in columns/rows as a Size.

fn window_size(&mut self) -> Result<WindowSize>

Get the size of the terminal screen in columns/rows and pixels as a WindowSize.

fn flush(&mut self) -> Result<()>

Flush any buffered content to the terminal screen.

fn get_cursor(&mut self) -> Result<(u16, u16)>

👎Deprecated: the method get_cursor_position indicates more clearly what about the cursor to get

Get the current cursor position on the terminal screen.

fn set_cursor(&mut self, x: u16, y: u16) -> Result<()>

👎Deprecated: the method set_cursor_position indicates more clearly what about the cursor to set

Set the cursor position on the terminal screen to the given x and y coordinates.

impl Clone for TestBackend

fn clone(&self) -> TestBackend

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TestBackend

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for TestBackend

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the TestBackend for display by calling the buffer_view function on its internal buffer.

impl Hash for TestBackend

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for TestBackend

fn eq(&self, other: &TestBackend) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for TestBackend

impl StructuralPartialEq for TestBackend