From 66a4128c341f36a3850434c8ef9ede7722a58fd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?= Date: Thu, 1 Oct 2026 13:34:47 -0400 Subject: [PATCH] =?UTF-8?q?T48l=20Docs=20=C2=B7=20Testing:=20the=20feature?= =?UTF-8?q?,=20an=20app's=20limit,=20writing=20a=20test=20inside=20Ely,=20?= =?UTF-8?q?tests=20to=20read?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- frontend/src/docs/guides.ts | 2 +- frontend/src/docs/testing.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 frontend/src/docs/testing.md diff --git a/frontend/src/docs/guides.ts b/frontend/src/docs/guides.ts index 9ad65e6..8bae956 100644 --- a/frontend/src/docs/guides.ts +++ b/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. */ diff --git a/frontend/src/docs/testing.md b/frontend/src/docs/testing.md new file mode 100644 index 0000000..5ea8b1f --- /dev/null +++ b/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.