Struct HeadlessAppContext 

pub struct HeadlessAppContext {
    pub app: Rc<AppCell>,
    pub background_executor: BackgroundExecutor,
    pub foreground_executor: ForegroundExecutor,
    /* private fields */
}

A headless app for tests that need real text layout, without a window on screen.

Like TestAppContext, this runs on a deterministic scheduler and a test platform. Unlike it, you supply the text system, so text is measured the way the platform measures it. Windows are hidden and unfocused. Use HeadlessAppContext::debug_bounds and the *_bounds methods to check where things were painted, and HeadlessAppContext::capture_screenshot to get pixels when a renderer is configured.

The text system comes from a platform or text crate. For example, the ParleyTextSystem in the gpui_ce_parley crate measures text with real fonts. This example uses TestTextSystem, which is for tests that don’t check text metrics:

use std::sync::Arc;

use gpui::{AppContext, HeadlessAppContext, TestTextSystem};

let mut cx = HeadlessAppContext::new(Arc::new(TestTextSystem));
let count = cx.new(|_| 1usize);
assert_eq!(cx.read_entity(&count, |count, _| *count), 1);

Fields

app: Rc<AppCell>

The underlying app cell.

background_executor: BackgroundExecutor

The background executor for running async tasks.

foreground_executor: ForegroundExecutor

The foreground executor for running tasks on the main thread.

Implementations

impl HeadlessAppContext

pub fn new(platform_text_system: Arc<dyn PlatformTextSystem>) -> Self

Creates a headless context that measures text with platform_text_system.

It has no asset source and no renderer, so HeadlessAppContext::capture_screenshot returns an error. Use HeadlessAppContext::with_platform for screenshots.

pub fn with_asset_source( platform_text_system: Arc<dyn PlatformTextSystem>, asset_source: Arc<dyn AssetSource>, ) -> Self

Creates a headless context with platform_text_system and asset_source, and no renderer.

pub fn with_platform( platform_text_system: Arc<dyn PlatformTextSystem>, asset_source: Arc<dyn AssetSource>, renderer_factory: impl Fn() -> Result<Option<Box<dyn PlatformHeadlessRenderer>>> + 'static, ) -> Self

Creates a headless context with a text system, an asset source and a renderer factory.

renderer_factory creates the renderer that windows draw with. Return None from it to draw without a renderer, which disables screenshots. The scheduler seed is read from SEED, and is 0 when it’s unset or isn’t a number.

pub fn open_window<V: Render + 'static>( &mut self, size: Size<Pixels>, build_root: impl FnOnce(&mut Window, &mut App) -> Entity<V>, ) -> Result<WindowHandle<V>>

Opens a hidden, unfocused window of size at the origin, with a root view from build_root.

Errors

Returns an error if the window can’t be opened.

pub fn run_until_parked(&self)

Runs pending tasks until none can make progress. This doesn’t move the simulated clock.

pub fn advance_clock(&self, duration: Duration)

Moves the simulated clock forward by duration, and runs the tasks that become ready.

pub fn allow_parking(&self)

Lets blocking waits in the scheduler sleep in real time, for tests that wait on real I/O.

Pair it with HeadlessAppContext::forbid_parking. See BackgroundExecutor::allow_parking.

pub fn forbid_parking(&self)

Turns off the parking mode from HeadlessAppContext::allow_parking, returning to deterministic execution.

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

Runs f with mutable access to the App. This doesn’t run pending tasks.

pub fn update_window<R>( &mut self, window: AnyWindowHandle, f: impl FnOnce(AnyView, &mut Window, &mut App) -> R, ) -> Result<R>

Runs f with the window’s root view, the Window and the App.

This doesn’t paint the window. Methods that read painted output, such as HeadlessAppContext::debug_bounds, see the last frame that was painted.

Errors

Returns an error if window has been closed.

pub fn debug_bounds( &mut self, window: AnyWindowHandle, selector: &str, ) -> Result<Option<Bounds<Pixels>>>

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

Errors

Returns an error if window has been closed.

pub fn solid_quad_bounds( &mut self, window: AnyWindowHandle, color: Hsla, ) -> Result<Vec<Bounds<ScaledPixels>>>

Returns the device-pixel bounds of each solid quad in color in the last painted frame.

The color must match exactly. Quads with other colors are skipped.

Errors

Returns an error if window has been closed.

pub fn glyph_bounds( &mut self, window: AnyWindowHandle, color: Hsla, ) -> Result<Vec<Bounds<ScaledPixels>>>

Returns the device-pixel bounds of each monochrome glyph painted in color in the last painted frame.

The color must match exactly.

Errors

Returns an error if window has been closed.

pub fn underline_bounds( &mut self, window: AnyWindowHandle, color: Hsla, ) -> Result<Vec<Bounds<ScaledPixels>>>

Returns the device-pixel bounds of each underline painted in color in the last painted frame.

The color must match exactly.

Errors

Returns an error if window has been closed.

pub fn capture_screenshot( &mut self, window: AnyWindowHandle, ) -> Result<RgbaImage>

Renders window’s last painted frame to an image.

Errors

Returns an error if the context was created without a renderer, which is the case for HeadlessAppContext::new and HeadlessAppContext::with_asset_source. Also returns an error if the window has been closed.

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

Returns the text system.

pub fn background_executor(&self) -> &BackgroundExecutor

Returns the background executor.

pub fn foreground_executor(&self) -> &ForegroundExecutor

Returns the foreground executor.

Trait Implementations

impl AppContext for HeadlessAppContext

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 Drop for HeadlessAppContext

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.