Contributor validation matrix

What to run after which kind of change. For the full guide, see Testing and debugging.

---

Quick reference

Change type	Run
Any change	cargo fmt --check && cargo clippy --all-targets --all-features -- -D warnings
Any change	cargo test
Any change	cargo test --all-features
Any change	cargo test --no-default-features
Config-facing	cargo run --bin evil -- --check-config --config examples/<config>.lua

---

By change area

Canvas / geometry / math

cargo test -p evil canvas:: output_layout:: move_resize:: window_policy::
cargo test --no-default-features

Headless runtime / Lua session / snapshots

cargo test -p evil headless_runtime:: lua_session:: lua_config::
cargo test --no-default-features

Input / bindings / key handling

cargo test -p evil input_actions::
cargo test --all-features

Window management / focus / placement

cargo test -p evil window_policy:: headless_runtime:: lua_session::
cargo test --all-features

Hook payloads / Lua API shape

cargo test -p evil lua_session:: lua_config::
cargo test --all-features

Live compositor behavior

cargo test --all-features
EVIL_RUN_LIVE_TESTS=1 cargo test --test live_smoke

Live smoke tests require a display and the env var set.

TTY / udev backend

cargo test --all-features
scripts/tty-virt-smoke.sh --dry-run

Real tty runs need vkms, openvt, root, and a spare VT.

Output management

cargo test --all-features
EVIL_RUN_LIVE_TESTS=1 cargo test --test live_smoke protocol_advertisement::

Layer-shell

EVIL_RUN_LIVE_TESTS=1 cargo test --test live_smoke layer_shell::

IPC / screenshots / snapshot format

cargo test -p evil ipc_snapshot::
cargo test --all-features
EVIL_RUN_LIVE_TESTS=1 cargo test --test live_smoke ipc::

Config validation (shipped examples)

for config in tty-baseline tiling; do
  cargo run --bin evil -- --check-config --config examples/${config}.lua
done

XWayland

cargo test --all-features
EVIL_RUN_LIVE_TESTS=1 cargo test --test live_smoke xwayland:: mixed_session::

---

Feature-gate coverage

Test command	Covers
cargo test	Default features: lua + winit + xwayland
cargo test --all-features	Default + udev (catches #[cfg(all(lua, udev))] gaps)
cargo test --no-default-features	Pure-core (catches accidental backend coupling)

All three are run in CI (.forgejo/workflows/ci.yml).

---

Artifacts

Test type	Artifact path
Live smoke	target/test-artifacts/live-smoke/
TTY virt	target/test-artifacts/tty-virt/
TTY hardware	target/test-artifacts/tty-hardware/

Each contains compositor.stdout.log, compositor.stderr.log, event log, IPC trace, and summary.json.

---

Env vars

Var	Effect
EVIL_RUN_LIVE_TESTS=1	Enable live smoke tests
EVIL_EVENT_LOG	Path for structured event JSONL
EVIL_IPC_TRACE_DIR	Directory for IPC request/response JSONL
RUST_LOG	Control tracing verbosity (e.g. RUST_LOG=evil=debug)

---

See also

• Testing and debugging — full guide
• Feature and support matrix — what works where