tui-tests

Source excerpt starting at line 1.

1---2name: tui-tests3description: Use when adding or modifying tests for one of GitButler's Ratatui TUIs4---5 6## Where tests live7 8- Main TUI tests: `crates/but/src/command/legacy/status/tui/tests/`9- Test harness/helpers: `crates/but/src/tui/test_utils.rs` and `crates/but/src/command/legacy/status/tui/tests/utils.rs`10- Snapshots: `crates/but/src/command/legacy/status/tui/tests/snapshots/`11 12## Basic pattern13 14```rust15#[test]16fn describes_behavior_under_test() {17    let env = Sandbox::init_scenario_with_target_and_default_settings("one-stack").unwrap();18    env.setup_metadata(&["A"]).unwrap();19 20    let mut tui = test_status_tui(env);21 22    tui.input_then_render(KeyCode::Down)23        .assert_rendered_term_svg_eq(file!["snapshots/describes_behavior_under_test_001.svg"]);24}25```26 27## Driving the TUI28 29Useful input examples:30 31```rust32tui.input_then_render(None);                                       // render without inputs33tui.input_then_render('j');                                        // single char input34tui.input_then_render(KeyCode::Down);                              // special key35tui.input_then_render(Shift('j'));                                 // keys with shift36tui.input_then_render(Control('j'));                               // keys with control37tui.input_then_render([KeyCode::Down, KeyCode::Down]);             // multiple keys from array38tui.input_then_render("commit message text");                      // multiple keys from string39tui.reload();                                                      // reload state after making external changes40```41 42## Assertions43 44Generally prefer45 46- `assert_current_line_eq(str![...])` for cursor/selection behavior.47- `assert_rendered_term_svg_eq(file!["snapshots/test_function_name_001.svg"])`48  for everything else.49 50Generally you should include one `assert_rendered_term_svg_eq` per logical51group of inputs, to catch bad states early.52 53Be careful using `assert_rendered_contains` and `assert_rendered_not_contains`54since they might lead to false positives. They're intended to use while55iterating on a test where snapshots would cause too much churn.56 57Read `crates/but/src/tui/test_utils.rs` and58`crates/but/src/command/legacy/status/tui/tests/utils.rs` for more specialized59assertions.60 61You're not allowed to add new kinds of assertions to `crates/but/src/tui/test_utils.rs` or62`crates/but/src/command/legacy/status/tui/tests/utils.rs`. Rely entirely on the63existing assertions.64 65Don't reuse snapshots from other tests. Give each test its own snapshots.66 67Avoid using `tui.env().invoke_git("...")`. Prefer performing operations via the TUI.68 69## Running tests70 71- `cargo test -p but <test-name>` to run one test.72- `SNAPSHOTS=overwrite cargo test -p but <test-name>` to run and update73  snapshots.74- `cargo test -p but tui` to run all tui tests. Do this after changing75  things.76 77If a test fails the output will include the rendered state of the test backend.78This can be used when iterating on a test as a way of inspecting the state.79