Tui Tests
Testing & Qualitytui-testsTui Tests is an Agent Skill for testing & quality published in the gitbutlerapp/gitbutler repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when adding or modifying tests for the GitButler TUI (`but tui`) under `crates/but/src/command/legacy/status/tui/tests`.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/gitbutlerapp/gitbutler/blob/HEAD/.agents/skills/tui-tests/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tui-tests, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Where tests live
- Main TUI tests:
crates/but/src/command/legacy/status/tui/tests/ - Test harness/helpers:
crates/but/src/command/legacy/status/tui/tests/utils.rs - Snapshots:
crates/but/src/command/legacy/status/tui/tests/snapshots/
Basic pattern
#[test]
fn describes_behavior_under_test() {
let env = Sandbox::init_scenario_with_target_and_default_settings("one-stack").unwrap();
env.setup_metadata(&["A"]).unwrap();
let mut tui = test_tui(env);
tui.input_then_render(KeyCode::Down)
.assert_rendered_term_svg_eq(file!["snapshots/describes_behavior_under_test_001.svg"]);
}
Driving the TUI
Useful input examples:
tui.input_then_render(None); // render without inputs
tui.input_then_render('j'); // single char input
tui.input_then_render(KeyCode::Down); // special key
tui.input_then_render((KeyModifiers::SHIFT, KeyCode::Char('J'))); // keys with modifiers
tui.input_then_render([KeyCode::Down, KeyCode::Down]); // multiple keys from array
tui.input_then_render("commit message text"); // multiple keys from string
tui.reload(); // reload state after making external changes
Assertions
Generally prefer
assert_current_line_eq(str![...])for cursor/selection behavior.assert_rendered_term_svg_eq(file!["snapshots/test_function_name_001.svg"])for everything else.
Generally you should include one assert_rendered_term_svg_eq per logical
group of inputs, to catch bad states early.
Be careful using assert_rendered_contains and assert_rendered_not_contains
since they might lead to false positives. They're intended to use while
iterating on a test where snapshots would cause too much churn.
Read crates/but/src/command/legacy/status/tui/tests/utils.rs for more
specialized assertions.
Running tests
cargo test -p but <test-name>to run one test.SNAPSHOTS=overwrite cargo test -p but <test-name>to run and update snapshots.cargo test -p but tuito run all tui tests. Do this after changing things.
If a test fails the output will include the rendered state of the test backend. This can be used when iterating on a test as a way of inspecting the state.