T48l Docs · Testing: the feature, an app's limit, writing a test inside Ely, tests to read

frontend/src/docs/guides.ts

@@ -6,7 +6,7 @@ import { Marked, type Tokens } from "marked";
 const at = (relative: string) => fileURLToPath(new URL(relative, import.meta.url));
 
 /** The guides in reading order, by file name. */
-const ORDER = ["introduction", "installation", "getting-started", "theme", "focus", "motion", "icons", "overlays", "i18n", "webassembly"];
+const ORDER = ["introduction", "installation", "getting-started", "theme", "focus", "motion", "icons", "overlays", "i18n", "webassembly", "testing"];
 
 export interface Guide {
   /** The path segment; the introduction has none. */

frontend/src/docs/testing.md

@@ -0,0 +1,31 @@
+# Testing
+
+Ely tests itself on GPUI's test platform: every chapter has tests, and `cargo test --lib --features test-support` runs them all. `scripts/check.sh` runs them with formatting, clippy and the house rules.
+
+## The `test-support` feature
+
+`test-support` turns on GPUI's own `test-support`, which brings `TestAppContext`, `#[gpui::test]` and the simulated input. It stays off for the gallery and for apps: GPUI then tracks every entity handle for leaks and records every `debug_selector`'s bounds each frame.
+
+## Testing an app that uses Ely
+
+GPUI's `TestAppContext` serves no assets, so `ely_gpui_component::init` panics there, and Ely's theme has no setup outside `init`. An app cannot draw Ely's components in a GPUI unit test today. Test the app's own state there, and see Ely's components in the gallery and in Ely's own tests.
+
+## Writing a test inside Ely
+
+| Need | How |
+| --- | --- |
+| A window | `#[gpui::test] fn name(cx: &mut TestAppContext)`, `Theme::init` in `cx.update`, then `cx.add_window_view(..)`, which returns the view and a `VisualTestContext`. |
+| A drawn frame | `cx.run_until_parked()`, `window.refresh()`, then `run_until_parked()` again. The test platform has no display link; a test refreshes the window instead. |
+| Next-frame callbacks | They run only when the test calls `Window::simulate_next_frame`. |
+| Keys | `simulate_keystrokes("tab enter")` sends key downs alone. GPUI presses a focused element on a key's release, so a test of that dispatches a `KeyUp` as well. |
+| Focus events | GPUI calls focus listeners only while the window is active: call `window.activate_window()`. |
+| Text | Each character takes a fixed advance, unless the context comes from `TestAppContext::build_with_text_system`. Click where layout does not hang on text, such as padding. |
+| Time | Timers run on the executor's clock, which the test advances. Animations run on the wall clock; to see one settled, turn on the theme's reduced motion and wait past its 1 ms. |
+| Bounds | GPUI clears `debug_bounds` each frame, so a test sees an element leave as well as appear. |
+
+## Tests to read
+
+- [Layers](https://github.com/ZacharyZhang-NY/Ely-GPUI-Components/blob/main/src/primitives/tests.rs): what is raised inside a raise lies over it, and keeps its state.
+- [Feedback](https://github.com/ZacharyZhang-NY/Ely-GPUI-Components/blob/main/src/feedback/tests/mod.rs): toasts and alerts, and focus handed to the root when a focused toast leaves.
+- [Tables](https://github.com/ZacharyZhang-NY/Ely-GPUI-Components/blob/main/src/tables/tests/mod.rs): clicks, double presses, Tab across a grid.
+- [Internationalization](https://github.com/ZacharyZhang-NY/Ely-GPUI-Components/blob/main/src/i18n/tests/mod.rs): catalogs, locales and a mirrored row.