Struct TestAppContext 

pub struct TestAppContext { /* private fields */ }

The test version of App, passed to #[gpui::test] functions.

TestAppContext implements AppContext and adds helpers for windows, input, prompts and executors. Unlike TestApp, its methods don’t run pending tasks unless the method says so. Call TestAppContext::run_until_parked to run them. See the testing guide.

Create one directly with TestAppContext::single when you don’t need the macro.

Implementations

impl TestAppContext

pub fn build(dispatcher: TestDispatcher, fn_name: Option<&'static str>) -> Self

Creates a context that runs on dispatcher.

#[gpui::test] calls this for you.

pub fn build_with_text_system( dispatcher: TestDispatcher, fn_name: Option<&'static str>, platform_text_system: Arc<dyn PlatformTextSystem>, ) -> Self

Creates a test context backed by the provided platform text system.

pub fn disable_accessibility(&mut self)

Disables accessibility for subsequently created test windows.

pub fn skip_drawing(&mut self)

Turns off drawing for this app for the rest of the test.

pub fn single() -> Self

Creates a context with seed 0 that isn’t tied to a test function.

Use this in doctests and in code that runs outside #[gpui::test].

pub fn test_function_name(&self) -> Option<&'static str>

Returns the name of the test function that created this context, if known.

pub fn did_prompt_for_new_path(&self) -> bool

Returns whether a new-path prompt is waiting for TestAppContext::simulate_new_path_selection.

pub fn active_idle_sleep_preventions(&self) -> usize

Returns the number of active idle sleep prevention tokens.

pub fn set_idle_sleep_prevention_delay(&self, delay: Duration)

Sets the delay for subsequent idle sleep prevention acquisitions.

pub fn set_idle_sleep_prevention_fails(&self, fails: bool)

Makes subsequent idle sleep prevention acquisitions fail or succeed.

pub fn new_app(&self) -> TestAppContext

Creates another app that shares this context’s scheduler, so tasks from both apps interleave deterministically.

The new app has its own state, windows and globals.

pub fn quit(&self)

Runs the cleanup registered with TestAppContext::on_quit, then shuts the app down.

#[gpui::test] calls this when the test ends.

pub fn on_quit(&mut self, f: impl FnOnce() + 'static)

Registers f to run when the test ends, before the app shuts down.

pub fn refresh(&mut self) -> Result<()>

Marks every window for redraw on the next effect cycle. Always returns Ok(()).

pub fn executor(&self) -> BackgroundExecutor

Returns a clone of the background executor.

pub fn foreground_executor(&self) -> &ForegroundExecutor

Returns the foreground executor.

pub fn update<R>(&self, f: impl FnOnce(&mut App) -> R) -> R

Runs f with mutable access to the App.

Unlike TestApp::update, this doesn’t run pending tasks. Call TestAppContext::run_until_parked afterward if you need them.

Example

let cx = TestAppContext::single();
let finished = Rc::new(Cell::new(false));

let flag = finished.clone();
cx.foreground_executor().spawn(async move { flag.set(true) }).detach();

cx.update(|_| ());
assert!(!finished.get(), "update doesn't run pending tasks");

cx.run_until_parked();
assert!(finished.get());

pub fn read<R>(&self, f: impl FnOnce(&App) -> R) -> R

Runs f with read-only access to the App.

pub fn add_window<F, V>(&mut self, build_window: F) -> WindowHandle<V>

where F: FnOnce(&mut Window, &mut Context<'_, V>) -> V, V: 'static + Render,

Opens a window with maximized bounds and returns its handle.

The window is backed by a test platform window, so input and resize helpers work on it. This doesn’t run pending tasks.

Panics

Panics if the window can’t be opened.

pub fn open_window<F, V>( &mut self, window_size: Size<Pixels>, build_window: F, ) -> WindowHandle<V>

where F: FnOnce(&mut Window, &mut Context<'_, V>) -> V, V: 'static + Render,

Opens a window of window_size at the origin and returns its handle.

Use this when a layout test needs a known size. TestAppContext::add_window uses the size of the test display instead. This doesn’t run pending tasks.

Panics

Panics if the window can’t be opened.

pub fn add_empty_window(&mut self) -> &mut VisualTestContext

Opens a window with an empty root view and returns a VisualTestContext for it.

Runs pending tasks before it returns.

pub fn add_window_view<F, V>( &mut self, build_root_view: F, ) -> (Entity<V>, &mut VisualTestContext)

where F: FnOnce(&mut Window, &mut Context<'_, V>) -> V, V: 'static + Render,

Opens a window whose root view build_root_view builds.

Returns the root view’s entity and a VisualTestContext for the window. Use the returned context from then on, which is the usual pattern: let (view, cx) = cx.add_window_view(...);. Runs pending tasks before it returns. See testing a window for an example.

pub fn text_system(&self) -> &Arc<TextSystem>

Returns the text system.

pub fn cursor_style(&self) -> CursorStyle

Returns the cursor most recently applied to the test platform.

pub fn write_to_clipboard(&self, item: ClipboardItem)

Writes item to the test clipboard.

pub fn read_from_clipboard(&self) -> Option<ClipboardItem>

Returns the item most recently written to the test clipboard, or None.

pub fn simulate_new_path_selection( &self, select_path: impl FnOnce(&Path) -> Option<PathBuf>, )

Answers the oldest pending new-path prompt.

select_path receives the directory the app asked about and returns the chosen path, or None to cancel.

Panics

Panics if no new-path prompt is pending.

pub fn simulate_path_prompt_response( &self, select_paths: impl FnOnce(&PathPromptOptions) -> Option<Vec<PathBuf>>, )

Answers the oldest pending prompt_for_paths request.

select_paths receives the prompt’s options and returns the chosen paths, or None to cancel.

Panics

Panics if no paths prompt is pending. Also panics if select_paths returns more than one path for a prompt that doesn’t allow multiple selection.

pub fn did_prompt_for_paths(&self) -> bool

Returns whether a prompt_for_paths request is waiting for TestAppContext::simulate_path_prompt_response.

pub fn simulate_prompt_answer(&self, button: &str)

Presses the button labelled button on the oldest pending prompt.

Panics

Panics if no prompt is pending, or if no button on the prompt has the label button.

pub fn has_pending_prompt(&self) -> bool

Returns whether a prompt is waiting for an answer.

pub fn pending_prompt(&self) -> Option<(String, String)>

Returns the message and detail of the oldest pending prompt, or None.

The detail is an empty string when the prompt has none.

pub fn opened_url(&self) -> Option<String>

Returns the URL most recently passed to open_url, or None.

Only the last URL is kept.

pub fn app_identity(&self) -> Option<(SharedString, SharedString)>

Returns the identifier and name set with set_app_identity, or None if none was set.

pub fn shown_system_notifications(&self) -> Vec<SystemNotification>

Returns every system notification shown during the test, in order.

A notification shown before the app has an identity is dropped and doesn’t appear here.

pub fn delivered_system_notifications(&self) -> Vec<SystemNotification>

Returns the notifications that are shown and not yet dismissed.

A notification with the same tag as an earlier one replaces it.

pub fn dismissed_system_notifications(&self) -> Vec<SharedString>

Returns the tags of the notifications dismissed during the test, in order.

pub fn simulate_system_notification_response( &self, response: SystemNotificationResponse, )

Delivers response to the response handlers, as if the user had activated the notification.

pub fn simulate_window_resize( &self, window_handle: AnyWindowHandle, size: Size<Pixels>, )

Resizes window_handle to size. See VisualTestContext::simulate_resize.

pub fn simulate_window_visibility_change( &self, window_handle: AnyWindowHandle, visibility: WindowVisibility, )

Simulates a change in whether the platform is presenting the window.

pub fn simulate_display_added( &self, display_id: DisplayId, refresh_interval: Option<Duration>, )

Simulates connecting a display.

pub fn simulate_display_removed(&self, display_id: DisplayId)

Simulates disconnecting a display.

pub fn simulate_display_refresh_interval_change( &self, display_id: DisplayId, refresh_interval: Option<Duration>, )

Simulates a connected display changing its refresh interval.

pub fn simulate_window_visual_viewport_change( &self, window_handle: AnyWindowHandle, bounds: Bounds<Pixels>, )

Simulates visible viewport changes without resizing the window’s layout area.

pub fn simulate_window_scale_factor_change( &self, window_handle: AnyWindowHandle, scale_factor: f32, )

Simulates the window moving to a display with a different scale factor.

pub fn expect_restart(&self) -> Receiver<(Option<PathBuf>, Vec<OsString>)>

Returns a receiver that gets the path and arguments of the next restart request.

The app doesn’t restart in a test. Calling this again replaces the previous sender, so the previous receiver is cancelled.

pub fn set_screen_capture_sources(&self, sources: Vec<TestScreenCaptureSource>)

Sets the sources that screen capture queries return.

pub fn windows(&self) -> Vec<AnyWindowHandle>

Returns the handles of all open windows.

pub fn spawn<Fut, R>(&self, f: impl FnOnce(AsyncApp) -> Fut) -> Task<R>

where Fut: Future<Output = R> + 'static, R: 'static,

Spawns a future on the foreground executor, with an AsyncApp for this app.

The future runs when tasks run, such as during TestAppContext::run_until_parked or a simulate_* method. A plain update doesn’t run it.

pub fn has_global<G: Global>(&self) -> bool

Returns whether a global of type G is set.

pub fn read_global<G: Global, R>(&self, read: impl FnOnce(&G, &App) -> R) -> R

Runs read with the global of type G.

Panics

Panics if no global of type G is set. Use TestAppContext::try_read_global when it might not be.

pub fn try_read_global<G: Global, R>( &self, read: impl FnOnce(&G, &App) -> R, ) -> Option<R>

Runs read with the global of type G if it is set, and returns None otherwise.

pub fn set_global<G: Global>(&mut self, global: G)

Sets the global of type G, replacing any previous value.

pub fn update_global<G: Global, R>( &mut self, update: impl FnOnce(&mut G, &mut App) -> R, ) -> R

Runs update with mutable access to the global of type G.

Panics

Panics if no global of type G is set.

pub fn to_async(&self) -> AsyncApp

Returns an AsyncApp for this app.

The handle holds a weak reference, so it can’t keep the app alive.

pub fn run_until_parked(&self)

Runs pending tasks until none can make progress.

This doesn’t move the simulated clock. Use executor().advance_clock for that. Timers that haven’t expired stay pending.

pub fn dispatch_action<A>(&mut self, window: AnyWindowHandle, action: A)

where A: Action,

Dispatches action to the focused element in window, then runs pending tasks.

Panics

Panics if window has been closed.

pub fn simulate_keystrokes(&mut self, window: AnyWindowHandle, keystrokes: &str)

Sends each keystroke in a space-separated list to window, then runs pending tasks.

Each part is parsed as in TestAppWindow::simulate_keystroke. The space bar is the key "space", which can’t appear in this list, because a space separates keystrokes. Two spaces in a row send an empty keystroke.

Panics

Panics if any part isn’t a valid keystroke.

pub fn simulate_input(&mut self, window: AnyWindowHandle, input: &str)

Types input into window by sending one keystroke per character, then runs pending tasks.

Each character is parsed as a keystroke, so the text reaches text inputs. A space is sent with the key " ", not "space".

Splitting on an empty string also sends an empty keystroke before the first character and after the last. Don’t rely on those.

pub fn dispatch_keystroke( &mut self, window: AnyWindowHandle, keystroke: Keystroke, )

Dispatches one keystroke to the focused element in window.

This doesn’t run pending tasks. TestAppContext::simulate_keystrokes does.

pub fn notifications<T: 'static>( &mut self, entity: &Entity<T>, ) -> impl Stream<Item = ()> + use<T>

Returns a stream that yields () each time entity notifies.

The stream ends when the entity is released.

pub fn events<Evt, T: 'static + EventEmitter<Evt>>( &mut self, entity: &Entity<T>, ) -> UnboundedReceiver<Evt>

where Evt: 'static + Clone,

Returns a stream of the events entity emits, cloned, in order.

pub async fn condition<T: 'static>( &mut self, entity: &Entity<T>, predicate: impl FnMut(&mut T, &mut Context<'_, T>) -> bool, )

Waits until predicate returns true for entity, checking after each notification.

Panics

Panics if the predicate isn’t true within 3 seconds of simulated time, or if the entity is released while waiting.

pub fn set_name(&mut self, name: &'static str)

Sets this app’s name.

Trait Implementations

impl AppContext for TestAppContext

fn new<T: 'static>( &mut self, build_entity: impl FnOnce(&mut Context<'_, T>) -> T, ) -> Entity<T>

Creates an entity from build_entity, and returns a handle to it.

fn reserve_entity<T: 'static>(&mut self) -> Reservation<T>

Reserves an entity slot, and returns a Reservation for it.

fn insert_entity<T: 'static>( &mut self, reservation: Reservation<T>, build_entity: impl FnOnce(&mut Context<'_, T>) -> T, ) -> Entity<T>

Creates the entity for a Reservation from AppContext::reserve_entity.

fn update_entity<T: 'static, R>( &mut self, handle: &Entity<T>, update: impl FnOnce(&mut T, &mut Context<'_, T>) -> R, ) -> R

Runs update with the entity and a Context for it, and returns the result.

fn as_mut<'a, T>(&'a mut self, _: &Entity<T>) -> GpuiBorrow<'a, T>

where T: 'static,

Borrows the entity mutably, without a closure.

fn read_entity<T, R>( &self, handle: &Entity<T>, read: impl FnOnce(&T, &App) -> R, ) -> R

where T: 'static,

Reads the entity with a shared borrow, and returns the result of read.

fn notify(&mut self, entity_id: EntityId)

Tells GPUI that the entity with entity_id changed. Its observers run and windows that show it redraw.

fn emit<EntityType, EventType>( &mut self, entity: &Entity<EntityType>, event: EventType, )

where EntityType: EventEmitter<EventType>, EventType: 'static,

Emits event from entity.

fn update_window<T, F>(&mut self, window: AnyWindowHandle, f: F) -> Result<T>

where F: FnOnce(AnyView, &mut Window, &mut App) -> T,

Runs f with the window’s root view, the window and the app, and returns the result.

fn with_window<R>( &mut self, entity_id: EntityId, f: impl FnOnce(&mut Window, &mut App) -> R, ) -> Option<R>

Runs f with the window that most recently rendered the entity entity_id, and returns the result.

fn read_window<T, R>( &self, window: &WindowHandle<T>, read: impl FnOnce(Entity<T>, &App) -> R, ) -> Result<R>

where T: 'static,

Reads the root view of window with the app, and returns the result.

fn background_spawn<R>( &self, future: impl Future<Output = R> + Send + 'static, ) -> Task<R>

where R: Send + 'static,

Runs future on the background executor and returns a task for its result.

fn read_global<G, R>(&self, callback: impl FnOnce(&G, &App) -> R) -> R

where G: Global,

Calls callback with the global of type G and the app, and returns the result.

fn insert_global_entity<T: 'static>(&mut self, entity: Entity<T>)

Keeps entity alive without a handle to it.

fn remove_global_entity<T: 'static>(&mut self, entity: &Entity<T>)

Stops keeping entity alive. It’s dropped once no other handle refers to it.

fn global_entities<T: 'static>(&self) -> impl Iterator<Item = Entity<T>>

Returns the entities stored with AppContext::insert_global_entity whose type is T.

impl Clone for TestAppContext

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.