Struct HeadlessApp 

pub struct HeadlessApp<A: ResourceApp> { /* private fields */ }

One framework app mounted headlessly: a test, a fixture seeder or an inspection tool drives it through the real runtime.

Implementations

impl<A: ResourceApp> HeadlessApp<A>

pub fn content(&self) -> ContentStore

The content store the app’s profile keeps the bytes its record names in: what cx.content() reads and writes on this device.

pub fn new() -> Result<Self, LaunchError>

The app as its owner opens it on a fresh private profile.

Errors

Returns any launch, storage or construction failure.

pub fn in_room(room: &str) -> Result<Self, LaunchError>

The app as its owner opens it on a fresh private profile, in room: one of several windows of the app in one process, each in a room of its own.

Errors

Returns any launch, storage or construction failure.

pub fn on_device(device: &str) -> Result<Self, LaunchError>

The app as its owner opens it on a fresh profile on the device device: one of two devices sharing a record, each carrying out what is queued for it.

Errors

Returns any launch, storage or construction failure.

pub fn with_role(role: Role) -> Result<Self, LaunchError>

The app as a participant with role opens it on a fresh profile.

Errors

Returns any launch, storage or construction failure.

pub fn for_person(person: &str) -> Result<Self, LaunchError>

The app as person (the hex of a root public key) opens it on a fresh profile: one of that person’s devices, whose person records (RecordEnv::person) are theirs.

Errors

Returns any launch, storage or construction failure.

pub fn for_person_with_lent<S: 'static>( person: &str, service: S, ) -> Result<Self, LaunchError>

Open a fresh person profile with a service lent by its mounting host. The loan follows production HostContext::lend and is not retained on reopen: the next host must authorize and lend its own service again.

Errors

Returns any launch, storage or construction failure.

pub fn open_person_records(&mut self) -> usize

How many of the person’s records the window holds open, the records a settings section keeps among them: a section’s opens only when it is first written or stepped.

pub fn person<P: Resource>(&mut self) -> Option<PersonRecord<P>>

The person’s own record of P the running app keeps, as its views open it.

pub fn shared_person<P: SharedRecord>(&mut self) -> Option<PersonRecord<P>>

The person’s shared record P, as the app’s views open it.

pub fn capture(scenario: Option<&str>) -> Result<Self, LaunchError>

The frame --shots --scenario writes for scenario (None for a plain --shots): the app built for a capture on a fresh profile, from the scenario’s fixture, with its actions applied and its view state staged, at the scenario’s viewport.

Errors

Returns any launch failure, or the host’s refusal of a scenario action.

pub fn capture_at( scenario: Option<&str>, viewport: (u32, u32), ) -> Result<Self, LaunchError>

Self::capture at viewport, as --shots --viewport draws it.

Errors

As Self::capture.

pub fn capture_launched( scenario: Option<&str>, arguments: &[&str], ) -> Result<Self, LaunchError>

Self::capture of the app launched with arguments, as --shots --scenario NAME ARGUMENTS draws it: a capture of a file the app was launched on.

Errors

As Self::capture.

pub fn launched(arguments: &[&str]) -> Result<Self, LaunchError>

The app launched by its owner with arguments, as app ARGUMENTS on the command line: on the record ResourceApp::launch_record names, after its ResourceApp::launch actions. The app’s own options and switches among them reach it as options.

Errors

Returns any launch, storage or construction failure.

pub fn launched_replica( arguments: &[&str], document: &mut Doc, ) -> Result<Self, LaunchError>

Launch on a private receiving profile after hydrating an existing record in the same room. The production installer validates its identity before the app can initialize or open it.

Errors

Returns invalid record scope, storage or launch failures.

pub fn handed_off( arguments: &[&str], handoff: PlaybackHandoff, ) -> Result<Self, LaunchError>

The app launched with arguments to continue handoff’s playback, as the session launches the target of a media handoff.

Errors

Returns any launch, storage or construction failure.

pub fn handed(file: OpenFile) -> Result<Self, LaunchError>

The app handed file to open by a host that already chose its record (the default one here), as the shell’s “open with” does.

Errors

Returns any launch, storage or construction failure, and the refusal of a file of a type the app does not open.

pub fn open_data_dir(directory: &Path) -> Result<Self, LaunchError>

The app on the profile --data-dir directory opens, as its owner. Only one writer may hold a profile: this fails while the app (or another HeadlessApp) has it open.

Errors

Returns any launch, storage or construction failure.

pub fn files(&self) -> AppFiles

The app’s file areas in this profile, which the running app writes instead of the person’s.

pub fn settings<T: SettingsSchema>(&self) -> Settings<T>

The app’s typed settings in this profile’s settings document, which the running app follows: a write here is what another window, the Settings app or another of the person’s devices writing them does.

pub fn set_role(&mut self, role: Role)

Change the participant’s role while the app runs, as the record’s owner changing their access does. Takes effect on the next frame, which this runs.

pub fn permissions(&self) -> PermissionContext

The participant’s permissions in force now.

pub fn set_permissions(&mut self, permissions: PermissionContext)

Change the participant’s permissions while the app runs, as the host does when the room’s grants change. Takes effect on the next frame, which this runs.

pub fn leave_room(&mut self)

Take the participant out of the room while the app runs: no role and no grant left, as when the owner removes them.

pub fn reopen(self) -> Result<Self, LaunchError>

Close the app (flushing its record) and open it again on the same profile, as a relaunch would.

Errors

Returns the flush or relaunch failure.

pub fn relaunch(self, arguments: &[&str]) -> Result<Self, LaunchError>

Close the app and launch it again on the same profile with arguments, as app ARGUMENTS run again would.

Errors

Returns the flush or relaunch failure.

pub fn open_here(&mut self, arguments: &[&str]) -> Result<(), String>

Open what a launch naming arguments opens in this window, as the app’s view does with RecordEnv::open_here, and run the frame that shows it.

Errors

Returns why the record cannot be opened: the window keeps the one it shows.

pub fn record(&self) -> &RecordId

The record the app shows.

pub fn take_save_retry(&mut self) -> Result<bool, String>

Consume the hosted window’s explicit save-retry request, as its record owner does before reporting durability again.

Errors

Returns an error if the framework root is absent.

pub fn flush(&mut self) -> Result<(), LaunchError>

Make every edit so far durable, as closing the app does.

Errors

Returns the record writer’s storage failure.

pub fn surface_mut<S: 'static>(&mut self) -> &mut S

The custom surface of type S the view hosts, without running a frame: for a test reading it, or setting it up, between the events it sends.

Panics

Panics when the view hosts no surface of type S.

pub fn harness(&mut self) -> &mut FrameHarness

The headless frame harness, for input-level tests (click_named, type_text, targets).

Panics

Panics after the app was closed, which the API does not allow.

pub fn with_surface<S: 'static, T>( &mut self, visit: impl FnOnce(&mut S) -> T, ) -> Option<T>

Visit the custom surface of type S the app’s view hosts (ViewCx::surface), as the frame shows it now; None when the view hosts none. The frame is laid out again after the visit, so what the visit changed is what the next frame draws.

pub fn invoke(&mut self, invoke: Invoke<A::Resource>) -> Result<(), DoorError>

Invoke a declared action through the host door, exactly as a control, the palette, an agent or a script does.

Errors

Returns the host’s refusal: unknown action, bad arguments, denied permission or the action’s own refusal.

pub fn invoke_child<C: Resource>( &mut self, resource: &str, invoke: Invoke<C>, ) -> Result<(), DoorError>

Invoke an action of the resource nested in this one at resource — a child resource a view edits through Dispatcher::child — through the host door, as the palette, an agent or a script addresses it.

Errors

As Self::invoke.

pub fn invoke_confirmed( &mut self, invoke: Invoke<A::Resource>, ) -> Result<(), DoorError>

Self::invoke after the caller confirmed it, as the host’s confirmation prompt does for a destructive action.

Errors

As Self::invoke, except that no confirmation is required.

pub fn actions(&mut self) -> Result<Vec<ActionDescriptor>, DoorError>

Discover the actions this participant may invoke on the running app, including item and child resources. Descriptors include the complete parameter, permission, confirmation and result contracts; discovery never invokes an action. Addresses stay stable across relayouts.

A saved descriptor is not an authority grant: every call checks the running app’s current permissions and resource state again.

Errors

Returns a refusal if the hosted component cannot be observed.

pub fn agent_surface(&mut self) -> Value

What an agent sees of the running app: every published action with its address, label, description and typed parameters, in a stable order. Snapshot it so a change shows how it altered the vocabulary an agent, a script or a screen reader works with, and what it costs in context.

pub fn operate( &mut self, invoke: Invoke<A::Resource>, ) -> Result<Option<ActionOutput>, DoorError>

Run a view or effect operation (look, export) through the host door, as an agent or script does, and answer with what it produced; None while it is still running.

Errors

As Self::invoke.

pub fn effect<E: Effect>( &mut self, effect: &E, ) -> Result<ActionOutput, DoorError>

Invoke one of the app’s effects through the host door, as a button, the palette or an agent does, and wait for its answer: what it reported at once, or the result of the job it started. Progress the job reported is in FrameHarness::job_updates.

Errors

Returns the host’s refusal or the effect’s failure.

pub fn effect_by<E: Effect>( &mut self, actor: &str, effect: &E, ) -> Result<ActionOutput, DoorError>

Self::effect invoked by actor — an agent or a collaborator the host admitted for the effect — rather than the person at this device: what the effect submits is applied as theirs, and only as far as the effect they were admitted for allows.

Errors

As Self::effect; the refusal of an edit the effect submitted fails it.

pub fn call_by( &mut self, invoker: ActionInvoker, resource: &str, id: &str, arguments: Value, ) -> Result<ActionOutput, DoorError>

Any published action of resource, by id with JSON arguments, delivered for invoker as the host delivers an admitted execution’s invocation: what it builds is bound to the invoker’s own participant view, and what it submits is applied as theirs.

Errors

As Self::effect.

pub fn effect_confirmed<E: Effect>( &mut self, effect: &E, ) -> Result<ActionOutput, DoorError>

Self::effect after the caller confirmed it, as the host’s confirmation prompt does for a destructive effect.

Errors

As Self::effect.

pub fn effect_on<E: Effect>( &mut self, row: &str, effect: &E, ) -> Result<ActionOutput, DoorError>

Self::effect as the published child or live row row offers it, bound to its arguments (Effect::bound): the caller names only the row and the effect, as the palette or an agent does on an item.

Errors

As Self::effect.

pub fn effect_on_confirmed<E: Effect>( &mut self, row: &str, effect: &E, ) -> Result<ActionOutput, DoorError>

Self::effect_on after the caller confirmed it.

Errors

As Self::effect.

pub fn start_effect<E: Effect>( &mut self, effect: &E, ) -> Result<InvocationId, DoorError>

Start effect through the host door without waiting for it, as a caller that may cancel it does, confirmed: the invocation its job runs under.

Errors

The host’s refusal, the effect’s failure, or that it answered at once and so started no job.

pub fn start_effect_on<E: Effect>( &mut self, row: &str, effect: &E, ) -> Result<InvocationId, DoorError>

Self::start_effect as the published child or live row row offers it, bound to its arguments.

Errors

As Self::start_effect.

pub fn cancel_effect( &mut self, invocation: InvocationId, ) -> Option<InvocationUpdate>

Cancel the job of an effect Self::start_effect started, as its caller does: what it ended as, Cancelled when it stopped. None when it already finished.

pub fn effect_progress(&mut self) -> Vec<InvocationUpdate>

What the job of the last Self::effect reported, in order: its progress, then its result.

pub fn with_widget<T: 'static, O>( &mut self, visit: impl FnOnce(&mut T) -> O, ) -> Option<O>

Run visit on the app’s widget of type T — a custom surface, a widget its view built — for assertions about view state the accessibility tree does not show, then run the frame after it. None when the view has no such widget.

pub fn settle(&mut self)

Run the frame the app runs after an event: edits the views and effects submitted are applied, and what they change is drawn.

pub fn call( &mut self, id: &str, arguments: Value, ) -> Result<Option<Value>, DoorError>

Invoke any published action of the resource by id with JSON arguments, as an agent’s tilo_invoke does — the framework’s own (undo, history, render) as well as the app’s — and answer with what it reported.

Errors

As Self::invoke.

pub fn call_in_run( &mut self, run: &str, id: &str, arguments: Value, ) -> Result<Option<Value>, DoorError>

Self::call as one agent run: every call naming the same run belongs to it, the way an agent’s connection groups its invocations.

Errors

As Self::invoke.

pub fn call_on( &mut self, resource: &str, id: &str, arguments: Value, ) -> Result<Option<Value>, DoorError>

Self::call on another published resource than the app’s own: a child, an item, or a live row a surface shows ("job:7"), addressed by its id.

Errors

As Self::invoke.

pub fn call_on_output( &mut self, resource: &str, id: &str, arguments: Value, ) -> Result<Option<ActionOutput>, DoorError>

Self::call_on, answering the whole output: the value and the resources the call produced, such as the items a verb created.

Errors

As Self::invoke.

pub fn asking(&mut self) -> Option<(ActionAddress, String)>

What the host is asking the person to confirm right now — a destructive verb or a removal that a button, a menu, the palette or an immediate application submitted — and the text that confirms it. None while nothing is asked.

pub fn confirm_asked(&mut self) -> Option<ActionAddress>

Confirm what the host asks, through its real dialog, as the person does (type the confirming text, press Enter), and settle: the action applies. Answers the action confirmed; None, changing nothing, when nothing was asked. A test of a delete from a menu clicks the menu item, then calls this.

pub fn call_confirmed( &mut self, id: &str, arguments: Value, ) -> Result<Option<Value>, DoorError>

Self::call after the caller explicitly confirmed this invocation. Argument validation and current permissions are still enforced.

Errors

As Self::call, except that no confirmation is required.

pub fn call_confirmed_on( &mut self, resource: &str, id: &str, arguments: Value, ) -> Result<Option<Value>, DoorError>

Self::call_on after the caller explicitly confirmed this invocation on an item or child resource. Use the address returned by Self::actions; no item id needs to be guessed or parsed from a label. Confirmation applies to this call only and grants no authority.

Errors

As Self::call_on, except that no confirmation is required.

pub fn state(&self) -> <A::Resource as Resource>::State

The resource state as stored.

Panics

Panics when the record is unreadable, which a test should surface.

pub fn read_document<T>(&self, read: impl FnOnce(&Doc) -> T) -> T

Read the stored document itself — the parts of a large resource its state does not hold until a view demands them.

Panics

Panics when the record is not open, which the API does not allow.

pub fn peer_document(&self) -> Doc

A copy of the stored document written by another participant: a collaborator’s replica, for a test to edit and Self::merge_peer back.

pub fn merge_peer(&mut self, peer: &mut Doc) -> Result<(), String>

Exchange edits with a collaborator’s replica, as sync does both ways: the peer’s edits arrive in the running app (and its views), and the app’s edits arrive in peer.

Errors

Returns why either side refused the other’s document.

pub fn versions(&self) -> Vec<Version>

The record’s version history.

pub fn history(&self) -> Vec<ActionContext>

What each version did through an action, oldest first.

pub fn sentences<'e>( &self, entries: impl IntoIterator<Item = &'e ActionContext>, ) -> Vec<String>

The sentences History shows for entries in en-US, through the app’s own catalogue.

pub fn past_version( &self, heads: &[ChangeHash], ) -> Result<PastVersion<A::Resource>, String>

The version at heads as History mode previews it: the app’s own view, read-only, over the document as it was then.

Errors

Returns why that version cannot be read or drawn.

pub fn merge_peer_edit(&mut self, edit: impl FnOnce(&mut Doc))

A collaborator’s edit arriving: edit writes on their own replica of the record as it stands now, under their own actor, and the change is merged in as sync merges a peer’s. It is not the local participant’s action, so it never lands on their undo stack.

Panics

Panics when the record is not open or the change does not merge, which a test should surface.

pub fn surface<S: 'static, O>( &mut self, visit: impl FnOnce(&mut S) -> O, ) -> Option<O>

Run visit on the app’s custom surface of type S — its view state, which no action reaches — then the frames that follow. None when the app’s view is not an S.

pub fn undo(&mut self) -> bool

Undo the local participant’s last action, as Ctrl+Z does.

pub fn redo(&mut self) -> bool

Redo, as Ctrl+Shift+Z does.

Trait Implementations

impl<A: ResourceApp> Drop for HeadlessApp<A>

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.