GPUI.Test supports three complementary ExUnit layers. Choose the lowest layer
that can truthfully prove the behavior:
| Test layer | Use it for | Do not claim |
|---|---|---|
Renderer-independent use GPUI.Test | Elixir state, callbacks, validation, snapshots, topology, and protocol policy | GPUI layout, native focus, or OS behavior |
Deterministic use GPUI.Test, native: ... | GPUI layout, bounds, hit testing, focus, keyboard dispatch, and component mechanics | OS clipboard, IME, compositor, or real-window behavior |
Desktop E2E use GPUI.Test, desktop: true | Window-server, accessibility-adapter, clipboard, IME, external transfer, and compositor facts | A replacement for focused component tests |
Pixel-level appearance belongs to synchronized visual capture rather than a behavioral assertion.
Choose a guide
- Application tests covers fast renderer-independent view and runtime tests, tree queries, semantic event helpers, and repository test layout.
- Deterministic native tests covers real GPUI component
mechanics through
TestAppContextwithout a desktop window. - Desktop E2E and visual evidence covers platform-aware orchestration, real native windows, and synchronized captures.
- Test coverage ownership is the authoritative behavior-by-layer matrix.
Configure consumers with:
config :gpui_native, build_native: config_env() != :testThis keeps ordinary application tests free of GPUI compilation and native library loading. The repository isolates the ordinary, deterministic-native, and desktop native artifacts, so switching modes does not require deleting a shared NIF.
Avoid duplicated coverage
Do not duplicate deterministic component assertions in desktop E2E. Once native interaction coverage proves a component mechanic, retain only the platform-specific smoke assertion in E2E. Conversely, renderer-independent event injection does not prove focus, hit testing, keyboard dispatch, or native layout.
Full quality gate
Run the normal project gate with:
mix ci
It checks generated Rust freshness, Cargo formatting and feature matrices, Clippy with warnings denied, Rust unit tests, ExUnit, Credo, Dialyzer, duplication, and architecture policy.
Real-window coverage is deliberately separate because it requires platform orchestration:
mix gpui.test.e2e apps/gpui_native/test/e2e/gpui/native
When changing native modes or validating artifact isolation, run:
mix gpui.test.mode_switch
See Desktop E2E and visual evidence for focused commands and platform requirements.