Struct VisualTestContext 

pub struct VisualTestContext {
    pub cx: TestAppContext,
    /* private fields */
}

A TestAppContext bound to one window, the test equivalent of a Window and App.

Use it to run window-specific test code. It implements VisualContext and dereferences to the TestAppContext it wraps. Clones refer to the same window.

Fields

cx: TestAppContext

The underlying TestAppContext. Methods on it are also available through deref.

Implementations

impl VisualTestContext

pub fn virtual_keyboard_requests(&self) -> usize

Returns the number of virtual keyboard show requests sent to this test window.

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

Runs f with the window and the app. This doesn’t run pending tasks.

pub fn from_window(window: AnyWindowHandle, cx: &TestAppContext) -> Self

Creates a context for window that shares cx’s app.

Shadow the TestAppContext with the result, which is usually what you want: let cx = VisualTestContext::from_window(window, cx);.

pub fn run_until_parked(&self)

Runs pending tasks until none can make progress.

This runs the same scheduler as TestAppContext::run_until_parked. It doesn’t move the simulated clock.

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

where A: Action,

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

pub fn window_title(&mut self) -> Option<String>

Returns the title set with Window::set_window_title, or None if none was set.

pub fn document_path(&mut self) -> Option<PathBuf>

Returns the document path set with Window::set_document_path, or None if none was set.

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

Sends a space-separated list of keystrokes to this window, then runs pending tasks.

This is TestAppContext::simulate_keystrokes for this window. The same rules apply: a space separates keystrokes, so use the key name "space" only as one keystroke.

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

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

See TestAppContext::simulate_input for how characters are sent.

pub fn simulate_mouse_move( &mut self, position: Point<Pixels>, button: impl Into<Option<MouseButton>>, modifiers: Modifiers, )

Moves the pointer to position, with button held if it’s Some.

pub fn simulate_mouse_down( &mut self, position: Point<Pixels>, button: MouseButton, modifiers: Modifiers, )

Presses button at position with modifiers held. The click count is always 1.

pub fn simulate_mouse_up( &mut self, position: Point<Pixels>, button: MouseButton, modifiers: Modifiers, )

Releases button at position with modifiers held. The click count is always 1.

pub fn simulate_click(&mut self, position: Point<Pixels>, modifiers: Modifiers)

Presses and releases the left button at position, with click count 1 on both events.

pub fn simulate_modifiers_change(&mut self, modifiers: Modifiers)

Sends a modifiers-changed event with modifiers. Caps lock is reported as off.

pub fn simulate_capslock_change(&mut self, on: bool)

Sends a modifiers-changed event with no modifiers and caps lock set to on.

pub fn simulate_resize(&self, size: Size<Pixels>)

Resizes the window to size. See TestAppContext::simulate_window_resize.

This doesn’t paint the window. Call VisualTestContext::draw to paint at the new size.

pub fn simulate_visibility_change(&self, visibility: WindowVisibility)

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

pub fn simulate_scale_factor_change(&self, scale_factor: f32)

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

pub fn debug_bounds(&mut self, selector: &'static str) -> Option<Bounds<Pixels>>

Returns the bounds of the element with debug_selector(selector) in the last painted frame, or None.

Draw the view first, so that the frame contains the element. Use this to click an element without guessing its position. Builds without debug_assertions don’t record selectors, so there this always returns None; see InteractiveElement::debug_selector.

pub fn draw<E>( &mut self, origin: Point<Pixels>, space: impl Into<Size<AvailableSpace>>, f: impl FnOnce(&mut Window, &mut App) -> E, ) -> (E::RequestLayoutState, E::PrepaintState)

where E: Element,

Lays out and paints f’s element as a root at origin, within space.

Use this to paint an element on its own, without a root view. It returns the element’s request-layout and prepaint state. The window is refreshed afterward.

pub fn simulate_event<E: InputEvent>(&mut self, event: E)

Sends event to the window as platform input, then runs pending tasks.

Call VisualTestContext::draw first, so that hit tests see the current layout.

pub fn deactivate_window(&mut self)

Makes this window inactive, as if the user had switched to another window.

Does nothing if the window isn’t active. Runs pending tasks.

pub fn simulate_close(&mut self) -> bool

Runs the window’s should-close callback and returns its result.

Returns false if the window has no callback. This doesn’t remove the window from the app, even when the callback returns true.

pub fn into_mut(self) -> &'static mut Self

Leaks this context and returns a mutable reference that stays valid until the test ends.

TestAppContext::add_window_view and TestAppContext::add_empty_window use this to return a context that borrows from the test. The memory is freed when the test quits.

Methods from Deref<Target = TestAppContext>

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 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 VisualTestContext

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, R>( &mut self, handle: &Entity<T>, update: impl FnOnce(&mut T, &mut Context<'_, T>) -> R, ) -> R

where T: 'static,

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

fn as_mut<'a, T>(&'a mut self, handle: &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 VisualTestContext

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Deref for VisualTestContext

type Target = TestAppContext

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for VisualTestContext

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl VisualContext for VisualTestContext

fn window_handle(&self) -> AnyWindowHandle

Get the underlying window handle underlying this context.

type Result<T> = T

The return type of window operations.

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

Creates an entity with access to the window.

fn update_window_entity<V: 'static, R>( &mut self, view: &Entity<V>, update: impl FnOnce(&mut V, &mut Window, &mut Context<'_, V>) -> R, ) -> R

Runs update with the entity, its window and a Context for the entity, and returns the result, wrapped in VisualContext::Result.

fn replace_root_view<V>( &mut self, build_view: impl FnOnce(&mut Window, &mut Context<'_, V>) -> V, ) -> Entity<V>

where V: 'static + Render,

Replaces the root view of the window with the view that build_view creates, and returns a handle to the new view.

fn focus<V: Focusable>(&mut self, view: &Entity<V>)

Moves keyboard focus to entity, using its Focusable::focus_handle.