Module headless 

Driving a ui app without a display.

--shots renders a cold-start frame offscreen but never delivers input, so it can’t answer does a change survive a restart? FrameHarness does: it stands up the app’s widget tree over a Taffy layout at a fixed viewport and feeds it the same WindowEvents winit would, through the same Widget::handle_event the live app uses — nothing stubbed, including CRDT mutations.

Every app launched through the standard lifecycle takes a --headless-drive '<json>' flag:

ebook --headless-drive '{"actions":[{"click_named":"library_item[0]"}]}'
ebook --headless-drive '{"dump":"/tmp/after.json"}'

The first process changes state and exits (flushing its store); the second loads the store and dumps the document as JSON. Diffing the two dumps is the persistence proof for the app’s document.

Modules

driver

One drive, run in-process: the steps a scenario names, performed through the shipped FrameHarness path, answering what the app showed rather than writing it to files.

host_media

A retained component’s local media lane for in-process hosts. Requests retain their exact component lifetime; a reply cannot reach a replacement.

Structs

AccessibilityAudit

Result of auditing the same semantic tree exported to assistive technology.

AccessibilityIssue

One deterministic accessibility-contract violation found in a laid-out retained or synthetic semantic node.

Capture

One offscreen picture of the window, taken once the actions ran and the window settled: {"path": "...", "theme": "light", "viewport": [w, h]}.

Control

One control as the exported accessibility tree carries it now.

FrameHarness

FrameOptions

Construction options for FrameHarness::for_root_with.

FrameOutput

FrameRenderInput

Borrowed paint input without constructing an accessibility snapshot.

FrameSchedule

The canonical display-independent frame pipeline.

Framed

A FrameHarness over one concrete root that reads as that root.

InspectionNode

One node in a developer inspection snapshot; semantics is the AccessNode the exported AccessKit tree was built from, and children include virtualized rows and cells that own no retained widget.

InspectionPatchStats

How much of a tree a patch carries.

InspectionSnapshot

A coherent post-layout snapshot of the retained and semantic trees.

Invocation

Invoke one action the app publishes, by its (resource, action) address, through the same door every other caller uses. No coordinates: the scenario names what to do, not where to click.

NativeAppAudit

Runtime proof over the app’s actual laid-out widget and resource trees.

NativeAppIssue

One reason an app cannot yet be certified as fully action-native.

Outcome

Everything one drive answers: the state the app is in once the steps ran, step by step, and the first step that failed.

ProvidedInvocation

One invocation of another provider’s action (FrameHarness::serve_provider).

RelayoutStats

What one completed FrameHarness::relayout did with its layout tree.

RootAndStateMut

The root of a FrameHarness and its live document, to change (FrameHarness::root_and_state_mut); let go of as a RootMut.

RootDispatch

What the root reported for one FrameHarness::dispatch_to_root_outcome.

RootMut

The root of a FrameHarness, to change (FrameHarness::root_mut). Letting go of it takes what the widgets report changed, as the live host does after each event.

SemanticExpectation

Semantic outcome required at this point in a saved scenario.

SidebarShown

Where the window’s sidebar stands after a press on the bar’s button.

Spec

StepRecord

One step, and what it did.

WindowBarNotice

How the window’s bar shows the notice up (FrameHarness::window_bar_notice).

WindowBarNoticeButton

The notice’s button as the window’s bar shows it.

Enums

Action

One thing to do to the app.

ControlInput

What a person can do to a control.

FrameDemand

Why a widget asks a live host for a frame (FrameHarness::frame_requesters).

SemanticAction

Step

One step of a drive. Every action --headless-drive accepts is a step, and so is a question about the app’s state that no action asks.

StepStatus

What driving one step did.

Constants

ACCESSIBILITY_AUDIT_VERSION

Current machine-readable accessibility-audit report format.

CONTROL_RESOURCE_PREFIX

Resource id prefix of a projected control (ui:<percent-encoded node>).

DEFAULT_VIEWPORT

Viewport the driver lays out at unless a spec overrides it. Matches the default --shots viewport so a driven frame and a screenshot agree.

FIXTURE_PICTURE

A small data: picture, for a capture or a test that shows one: a 64-by-64 image in two colours, small enough to travel in its own address.

NATIVE_APP_AUDIT_VERSION

Current machine-readable Tilo-native contract report format.

WINDOW_SLOTS

The name the row goes by in the frame’s inspection and in its semantic actions: its slots are performed on this owner with their targets.

Functions

drive

Run steps against the app harness hosts and answer what it shows.

parse_spec

Parse and strictly validate one complete headless-driver payload.

run_component

Drive the same prepared component with existing actions, audit, and output formats. Returns 0 for success, 1 for an action/output failure, and 3 for durability failure.

run_component_staged

run_component, with stage run on the mounted window before the actions: the named scenario’s selection, open menu or drag, as a capture of it shows them. A stage that fails fails the drive (1).

viewport

A logical (width, height) as a harness viewport: fractions truncate and negative or NaN sizes become zero, so a float size names the same viewport it would as an integer.

write_inspection_patch

Write the operations that turn old into new to out, as a JSON array (see the module documentation), and say how much they carry. new is lent mutably only to write a node’s own fields without its children; it is left as it was.

Type Aliases

ServedProvider

What answers another provider’s action in a harness, in place of the workspace broker.