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.

pub fn in_workspace(workspace: &str) -> Result<Self, LaunchError>

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

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.

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

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

pub fn hosted( resource: &str, answers: impl Answers + 'static, ) -> Result<Self, LaunchError>

The app as its owner opens it over answers, the session’s document host: no record is opened here, the view reads the reading answers publishes at resource, and everything it submits goes back to answers (one-app-model.md §4).

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 shared records (RecordEnv::shared_person) are theirs.

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

Self::for_person, with the app open in the workspace workspace (a workspace id), whose records sync on their routes.

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.

pub fn for_person_shown_by( person: &str, held: &PersonRecords, ) -> Result<Self, LaunchError>

The app as person opens it in a host that keeps the person’s shared records itself, in held, and lends them to the apps it shows in its process (a session showing Settings).

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_workspace<P: Resource>( &mut self, owner: &'static str, ) -> Option<WorkspaceRecord<P>>

The record P every app of the workspace opens that owner keeps, as the app’s views open it.

pub fn shared_record<P: Resource>( &mut self, owner: &'static str, id: &str, ) -> Option<WorkspaceRecord<P>>

The record id that owner keeps, as the app’s 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.

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 drive(scenario: &str) -> Result<Self, LaunchError>

The window --headless-drive drives when it names scenario ("scenario" in the spec, or --scenario NAME beside it): built and staged as Self::capture is, from the scenario’s fixtures, but the actions invoked on it run, as the drive’s invoke steps run them. It starts no work on its own, so what it shows stays the scenario’s. A drive that names no scenario drives the app someone uses (Self::new).

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.

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 workspace. The production installer validates its identity before the app can initialize or open it.

pub fn with_window_records(documents: &mut [Doc]) -> Result<Self, LaunchError>

A new window of the app on a fresh profile that already holds documents, each a record a window of the app kept in the test workspace (window_record): how an app that now keeps one record per workspace first opens where it used to keep one per window.

pub fn with_workspace_record(document: &mut Doc) -> Result<Self, LaunchError>

A new window of an app that keeps one record per workspace on a fresh profile whose workspace record is already document: how a workspace an earlier version of the app wrote opens.

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.

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 replaying(file: OpenFile) -> Result<Self, LaunchError>

The app replaying the recording file holds, as the session opens a recording a report carries: in a private window of its own.

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.

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, 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 workspace’s grants change. Takes effect on the next frame, which this runs.

pub fn leave_workspace(&mut self)

Take the participant out of the workspace 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.

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.

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

Close the app and open a new window of it on the same profile and in the same workspace, as the launcher opens one: an instance it never had, whose fallback record is a fresh record of that window’s own unless the app keeps one per workspace.

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

Open another window of the app beside this one, on the same profile and in the same workspace, while this one stays open: two windows a person has open at once. Its fallback record is the workspace’s when the app keeps one per workspace, so both show one record; Self::deliver_changes_to carries edits between them.

pub fn deliver_changes_to(&mut self, other: &mut Self) -> Result<bool, String>

Deliver this window’s changes to the record to other, a window showing the same record, as the workspace’s broker fans each window’s document changes out to every other window on the record; other takes them in and draws its next frame, without reopening. Whether other changed.

pub fn deliver_record_to( &mut self, other: &mut Self, id: &RecordId, ) -> Result<bool, String>

Deliver what this window holds of id, a record the app keeps beside its own (a part of a chain), to other, which holds it too, as the workspace’s record sync sends a device a record it opened: other takes it in and draws its next frame. Whether other changed.

pub fn workspace_answered(&mut self, id: RecordId)

The workspace’s hosts sent everything they hold of id, a record this window asked for, or none is connected to ask (ui_core::record::RecordStore::note_workspace_answered).

pub fn window_records(&self) -> Vec<(RecordId, Doc)>

The workspace’s default records of the app’s windows kept on this profile, as SeedCx::window_records reads them.

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

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.

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

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

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.

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

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

pub fn texts(&mut self) -> Vec<String>

Every text the window shows now, as assistive technology reads it: what the app’s view drew of its state.

pub fn open_records(&self) -> Vec<RecordId>

The records this window’s store has open: what the app process opened itself, which an app the session serves opens none of.

pub fn submit(&mut self, submit: impl Submit<A::Resource>) -> Result<(), String>

Submit submit through the running view’s own dispatcher, as a control’s press or a field’s edit hands it over: over the session’s connection when the app is the session’s, into the record here when it is not.

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.

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.

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.

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 search_index_entries(&mut self) -> Vec<IndexEntry>

What the system’s persistent search index keeps of this window now: the entries the app publishes to it, found after it closes too.

pub fn refused(&mut self) -> Option<Refused>

The last action refused here (super::Dispatcher::refused): by the door, or by the workspace after this window applied it.

pub fn refused_by_workspace( &mut self, changes: &[[u8; 32]], reason: &str, ) -> Result<bool, String>

The workspace refused changes (Automerge hashes) of this window’s record, reason what a person is told (a host replicating the record reads it from the workspace’s words with tilo_relay_protocol::refusal::plain_reason): withdraw them and what was built on them, as that host does, and run the frame that tells the app. Whether anything was withdrawn.

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

What the workspace kept that the app said it did (super::Dispatcher::say_when_kept): the last such text.

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

From now on a host replicates this window’s record to a workspace that decides its changes, as a browser page in a workspace does: what the app says it did waits for the workspace (Self::workspace_publishes, Self::workspace_keeps).

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

The host publishes what changed since it last did, as its next pass does; whether anything was published.

pub fn workspace_keeps(&mut self)

The workspace answered every commit the host published, keeping them, and the frame that tells the app runs.

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 idle(&mut self)

What the live window does once input stops, and no more: what its components’ workers woke them for taken up, the frame the input asked for, control invocations dispatched and edits offered to the record’s writer (FrameHarness::idle). Unlike Self::settle it forces no frame to sync and publish, so it costs what the live window costs: what the perf measurements run after each interaction.

pub fn frame(&mut self) -> bool

One frame of the live window, when it asks for one: what its components’ workers woke them for taken up, as the window’s frame takes it, then the frame a redraw, an animation or a due deadline asks for. Whether a frame ran.

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_finished( &mut self, resource: &str, id: &str, arguments: Value, ) -> Result<ActionOutput, DoorError>

Self::call_on, waiting for the job the action started, as Self::effect does: what it finished with.

Errors

As Self::effect.

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 question it asks. 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 (Enter on its question), 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

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.

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.

pub fn replica_arrives( &mut self, record: &RecordId, edit: impl FnOnce(&mut Doc), ) -> Result<bool, String>

Another replica’s change to record, a record open in the app’s store (its own, or a part of a chain beside it), arriving as a workspace’s replication delivers it: edit writes on that replica as it stands now, under its own actor, and the change is merged into the store. Nothing else runs: no frame is laid out or forced, so what the window shows of it is what its own frames (Self::frame) take up, as for a person who is only watching. Whether the record changed.

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.

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.

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.