Warp Rust Unit Tests

Rust Unit Tests in warp

Scope

• This skill focuses on crate-level unit tests.
• Favor incremental, well-scoped tests that exercise a single function or behavior per case.
• For how to structure and run tests, read on. For whether a change needs a test and at what level, start with "What to unit test".

What to unit test

Default to a unit test when the logic is deterministic and reachable without booting the app:

• Parsing, encoding, escaping, and any pure data transformation.
• Domain logic and state machines (block lifecycle, selection, ranges, diffing).
• Boundary and edge cases: empty input, single element, off-by-one at range ends, min/max, invalid UTF-8, zero-width and wide grapheme clusters.
• Error paths and fallbacks, not just the happy path.
• Bug fixes, where the bug is reachable at this level. A reproducible bug usually means a case was missing from the suite, so add the failing test first and then fix it. Not every bug is unit-testable — a rendering artifact, a PTY timing race, or a crash that needs a real window will not reduce to one. Cover those at the level where they actually reproduce, and don't reshape the code just to force a unit test.

Prefer unit tests for anything that fits: they are fast, deterministic, and point straight at the failure.

When a unit test is the wrong level

Be honest about this codebase. Warp is a terminal emulator with a GPU renderer, PTY and shell integration, and IPC. The common "80% unit tests" heuristic assumes a business-logic-heavy system where units exchange messages and transform data. Large parts of this repo are not that, and forcing them under a unit test usually means mocking away the only thing that could actually break.

Escalate to a higher level when any of these hold:

• The behavior needs a real PTY, shell, window, or display to exist at all.
• What can break is the wiring between components — a setting taking effect, a keybinding dispatching, focus moving across panes — rather than logic inside any one of them.
• Reproducing it requires real IO, spawned processes, or cross-process timing.
• The only way to make it unit-testable is to add a trait and an indirection layer that exist solely for the test.
• You find yourself stubbing so much that the test no longer exercises anything real.

Where to go instead:

• gui-integration-test — GUI end-to-end behavior, terminal and shell integration, settings and keybinding wiring.
• tui-testing — TUI element and screen rendering.
• gui-integration-test-video or computer_use — when the real question is visual and someone needs to look at it.

Before escalating, try splitting the problem. Most "untestable" code is a thin shell of IO wrapped around logic that tests fine once separated: extract the decision-making into a pure function, unit test that, and let an integration test cover the thin shell that remains. That is usually cheaper than either a heavily stubbed unit test or a full app-boot test.

That said, weigh the indirection on its own merits. Code that is hard to test is sometimes genuinely badly designed — if extracting the logic would make the code clearer regardless of testing, do it. If the seam would exist only to satisfy a test, don't.

When NOT to write a unit test

Tests cost real maintenance, and a bad test costs more than no test. Skip or delete these:

• Change-detector tests. A test that restates the implementation — inject two collaborators, assert they were called in order — fails on every refactor and catches no defects. It has negative value. Rewrite it as a state assertion or delete it.
• Trivial code with no logic. Getters, From/Into passthroughs, Default impls, plain struct construction. There is nothing that can break independently.
• Code you don't own. Don't test the standard library, tokio, or wgpu. Test your usage of them.
• Redundant tests. If a case is already covered, a near-identical test adds maintenance cost and no signal. Prune tests as ruthlessly as production code.

Don't chase a coverage number. Coverage says a line executed, not that anything was verified, and a target reliably turns into a ceiling.

Where unit tests live

• Put unit tests in separate files named ${filename}_tests.rs or mod_test.rs.
• Include the test module at the end of the corresponding source file:

#[cfg(test)]
#[path = "filename_tests.rs"] // or "mod_test.rs"
mod tests;

Writing good tests

Aim for a test you never touch again unless the behavior changes. Refactors, new features, and bug fixes should not require editing existing tests; only a deliberate behavior change should. If a refactor breaks your tests, that is usually a defect in the tests.

Test behavior through the public API

Exercise the unit the way its callers do. Reaching into private state makes the test fail on refactors no caller would notice. If a helper type exists only to serve one or two callers, test it through them rather than directly.

Assert on state, not on interactions

Assert what the system is after the action, not which functions it called to get there.

// Brittle: still passes if the entry is dropped right after insertion, and
// fails on an equivalent refactor that calls a different internal method.
assert!(recorder.saw_call_to_insert(id));

// Better: asserts the outcome the caller actually cares about.
store.insert(id, entry.clone());
assert_eq!(store.get(id), Some(&entry));

One behavior per test, named after that behavior

The test name is often the only thing visible in a failure report, so make it a sentence about behavior rather than about the method:

#[test]
fn parses_utf8_sequence_when_valid() { /* ... */ }

#[test]
fn returns_replacement_char_for_invalid_utf8() { /* ... */ }

If the name needs an "and", you are testing two behaviors — split it. Structure the body as arrange / act / assert, separated by blank lines.

Keep the test complete and concise

Everything a reader needs to understand the result belongs in the test body; everything irrelevant belongs out of it. Prefer a builder or helper constructor that takes only the fields the test cares about over one large shared fixture. If a test asserts on a specific value, set that value in the test rather than inheriting it from shared setup.

Prefer duplication over indirection

Test code has no tests of its own, so it has to be obviously correct on inspection. Some repetition is a fair price for a test that reads top to bottom. Extract a helper when it removes noise, not merely to remove repetition.

No logic in tests

No conditionals, loops, arithmetic, or string concatenation to compute an expected value. Write expected values literally — computing them re-implements the code under test and can reproduce the same bug in the assertion.

Make failures diagnosable

• Prefer assert_eq!/assert_ne! over assert! for readable diffs.
• Add a message when the values alone aren't self-explanatory: assert_eq!(got, want, "cursor should clamp to line end for {input:?}").
• Use #[should_panic] only when panicking is intended API, and pin the message with expected = "...".