Struct TestApp 

pub struct TestApp { /* private fields */ }

A headless app for tests.

TestApp runs a real App on a deterministic scheduler. Its platform keeps the clipboard, opened URLs and prompts in memory, so you can assert on them instead of seeing them on screen. Each TestApp is independent: state set in one doesn’t appear in another.

See the testing guide.

Implementations

impl TestApp

pub fn new() -> Self

Creates a test app with scheduler seed 0.

Text is shaped by the test text system, not by real fonts. Use TestApp::with_text_system when a test measures real glyphs.

pub fn with_seed(seed: u64) -> Self

Creates a test app whose scheduler orders ready tasks by seed.

The seed decides which ready task runs first. The same seed gives the same order every time, so a failing seed can be replayed.

pub fn with_text_system(text_system: Arc<dyn PlatformTextSystem>) -> Self

Creates a test app that shapes text with text_system. Uses seed 0.

Pass a real text system to measure glyphs as the app would on a platform.

pub fn with_text_system_and_assets( text_system: Arc<dyn PlatformTextSystem>, asset_source: Arc<dyn AssetSource>, ) -> Self

Creates a test app with the given text system and asset source.

This is TestApp::with_text_system plus an AssetSource, so views can load icons and other assets. Uses seed 0.

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

Runs f with mutable access to the App, then runs pending tasks until none can make progress.

Effects such as observers and subscriptions run when f returns, before the pending tasks run. Timers that haven’t expired stay pending; use TestApp::advance_clock to fire them.

Example

let mut app = TestApp::new();
let finished = Rc::new(Cell::new(false));

let flag = finished.clone();
app.spawn(|_| async move { flag.set(true) }).detach();

// Any update runs the task that was spawned above.
app.update(|_| ());
assert!(finished.get());

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

Runs f with read-only access to the App.

This doesn’t run pending tasks. A task that is still waiting to run doesn’t run before f is called.

pub fn new_entity<T: 'static>( &mut self, build: impl FnOnce(&mut Context<'_, T>) -> T, ) -> Entity<T>

Creates an entity from build and runs pending tasks until parked.

This is cx.new(build) inside TestApp::update.

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

Updates an entity and runs pending tasks until parked.

pub fn read_entity<T: 'static, R>( &self, entity: &Entity<T>, f: impl FnOnce(&T, &App) -> R, ) -> R

Reads an entity without running pending tasks.

pub fn open_window<V: Render + 'static>( &mut self, build_view: impl FnOnce(&mut Window, &mut Context<'_, V>) -> V, ) -> TestAppWindow<V>

Opens a window sized to the test display and returns a TestAppWindow for its root view.

The window’s bounds are the maximized bounds of the test display. Use TestApp::open_window_with_options to choose other bounds.

Panics

Panics if the window can’t be opened.

pub fn open_window_with_options<V: Render + 'static>( &mut self, options: WindowOptions, build_view: impl FnOnce(&mut Window, &mut Context<'_, V>) -> V, ) -> TestAppWindow<V>

Opens a window with options and returns a TestAppWindow for its root view.

Panics

Panics if the window can’t be opened.

pub fn run_until_parked(&self)

Runs tasks until none can make progress.

This doesn’t move the simulated clock. A timer that hasn’t expired stays pending until TestApp::advance_clock moves time past it.

Example

let mut app = TestApp::new();
let fired = Rc::new(Cell::new(false));

let flag = fired.clone();
app.spawn(|cx| async move {
    cx.background_executor().timer(Duration::from_secs(1)).await;
    flag.set(true);
})
.detach();

app.run_until_parked();
assert!(!fired.get(), "the timer hasn't expired yet");

app.advance_clock(Duration::from_secs(1));
app.run_until_parked();
assert!(fired.get());

pub fn advance_clock(&self, duration: Duration)

Moves the simulated clock forward by duration.

Tasks that become ready run during the call, including timers that expire within the window. Use this to test timeouts and delays, as in the example for TestApp::run_until_parked.

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, given an AsyncApp for this app.

The future runs when the app runs tasks: during TestApp::run_until_parked, TestApp::advance_clock or the next update. Await, store or detach the returned Task, as in a real app. See async work.

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

where R: Send + 'static,

Spawns a Send future on the background executor.

Like TestApp::spawn, the future runs when the app runs tasks.

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 background_executor(&self) -> &BackgroundExecutor

Returns the test background executor.

pub fn foreground_executor(&self) -> &ForegroundExecutor

Returns the test foreground executor.

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

Returns the text system the app uses to shape and measure text.

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

Returns whether a global of type G is set.

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

Sets the global of type G, replacing any previous value, then runs pending tasks.

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

Runs f with the global of type G.

Panics

Panics if no global of type G is set. Check with TestApp::has_global first.

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

Runs f with mutable access to the global of type G, then runs pending tasks.

Panics

Panics if no global of type G is set.

pub fn write_to_clipboard(&self, item: ClipboardItem)

Writes item to the test clipboard.

TestApp::read_from_clipboard returns the item until something else is written.

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

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

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

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

Nothing is launched. Only the last URL is kept, so open a second URL and the first is no longer reported.

Example

let mut app = TestApp::new();
app.update(|cx| cx.open_url("https://example.com"));
assert_eq!(app.opened_url().as_deref(), Some("https://example.com"));

pub fn did_prompt_for_new_path(&self) -> bool

Returns whether a App::prompt_for_new_path request is waiting for an answer.

Answer it with TestApp::simulate_new_path_selection.

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

Answers the oldest pending App::prompt_for_new_path request.

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

Panics

Panics if no new-path request is pending.

pub fn has_pending_prompt(&self) -> bool

Returns whether a prompt from Window::prompt is waiting for an answer.

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

Answers the oldest pending prompt by pressing the button labelled button.

The prompt is removed before the label is checked, so a wrong label still consumes it.

Panics

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

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

Returns the handles of all open windows.

Trait Implementations

impl Default for TestApp

fn default() -> Self

Returns the “default value” for a type.