Testing

Helix has three layers of automated tests: unit tests, doc tests, and integration tests. All three run in CI on every push and PR.

Unit tests

Unit tests are inline #[cfg(test)] mod tests blocks next to the code. Most modules in helix-core have them — they're the primary regression net for the editing primitives.

Run all unit tests:

cargo test --workspace

Run a subset:

cargo test -p helix-core
cargo test -p helix-core movement
cargo test -p helix-term commands::test

Selection-aware test helpers

The test module in helix-core/src/test.rs makes multi-cursor assertions concise. The string syntax:

#[anchor|]selected text[|head]

A test:

use helix_core::test::*;

assert_apply_in_place_eq!(
    "hello #[w|]orld",
    Selection::single(6, 7),
    Transaction::change(...),
    "hello #[Wo|]rld",
);

This style appears throughout helix-core/src/movement.rs, selection.rs, and transaction.rs. Prefer it for new tests touching selections.

Doc tests

/// # Examples blocks in doc comments are also tests. Run with:

cargo test --workspace --doc

helix-parsec leans heavily on doc tests — most of its API is documented through executable examples.

Integration tests

Integration tests live in helix-term/tests/test/ and exercise the full application via TestBackend (helix-tui/src/backend/test.rs). They use the integration feature gate (in helix-event and helix-term) and the integration profile (which turns on optimization for helix-core, helix-tui, and helix-term so the suite finishes in reasonable time).

Run with:

cargo integration-test

This is an alias defined in .cargo/config.toml for cargo test --features integration --profile integration.

Test helpers

helix-term/tests/test/helpers.rs provides:

• test_with_config(config, scenario) — start an Application with a custom config, drive a sequence of key events, assert the resulting state.
• Snapshot assertions on the rendered TestBackend buffer.

Existing tests double as good examples — when adding a new command, copy a similar test file and adapt.

macOS file-handle limit

Per docs/CONTRIBUTING.md, on macOS the integration suite can hit "Too many open files (os error 24)". Bump the soft limit:

ulimit -n 10240

Logging during tests

Set HELIX_LOG_LEVEL=debug (or trace) before running:

HELIX_LOG_LEVEL=debug cargo integration-test

The integration test setup configures fern to log to stdout (see setup_integration_logging in helix-term/src/application.rs).

Coverage

There is no enforced coverage threshold. The maintainers prefer thoughtful tests over raw coverage numbers — a regression test for a fix is more valuable than padding tests on already-stable code.

Tree-sitter and theme checks

Two pseudo-tests run via xtask:

cargo xtask query-check    # validates every runtime/queries/<lang>/*.scm
cargo xtask theme-check    # loads every runtime/themes/*.toml

Both are CI gates. If you add a new theme or query, run these before pushing.

Performance regressions

There is no formal performance test suite. For changes that might affect performance (movement code, syntax highlighting, picker filtering), the convention is:

1. Demonstrate the intended behaviour with a benchmark in your PR description.
2. Use criterion in a one-off branch if you need numbers, but do not check criterion configs into the repo.
3. Run cargo run --release -- <large file> to ensure a release build still feels snappy.

CI matrix

Tests run on:

• ubuntu-latest
• macos-latest
• windows-latest
• ubuntu-24.04-arm

The windows matrix uses crossterm rather than termina; the others use termina. If your change touches platform-specific code (signals, file I/O, the clipboard), check both backends.

When tests fail

• For local failures, re-run with --nocapture to see println output: cargo test -- --nocapture.
• For flaky integration tests, increase HELIX_LOG_LEVEL=trace and inspect timing.
• For CI failures that don't repro locally, check whether the failure is in the lints or docs job — those tend to be fmt/clippy/docgen forgetfulness.