Struct Session 

pub struct Session {
    pub id: String,
    pub app_name: String,
    pub app_bus_name: String,
    pub app_path: String,
    pub a11y_connection: Option<Connection>,
    /* private fields */
}

A running UI test session: a compositor, input + capture backends, the target application process, and an AT-SPI connection to drive it.

Construct via Session::start. Callers are responsible for pre-starting the compositor (so they can wire mutually-dependent backends like waydriver-input-mutter / waydriver-capture-mutter, which share state with the compositor via Arc<MutterState>).

Fields

id: String

app_name: String

app_bus_name: String

app_path: String

a11y_connection: Option<Connection>

Implementations

impl Session

pub async fn start( compositor: Box<dyn CompositorRuntime>, input: Box<dyn InputBackend>, capture: Box<dyn CaptureBackend>, cfg: SessionConfig, ) -> Result<Self>

Build a session from a pre-started compositor plus matching input and capture backends. The caller is responsible for calling CompositorRuntime::start before passing the compositor in; this is what lets the caller construct backend-specific input/capture types from whatever state the compositor exposes after startup (for mutter, that’s waydriver_compositor_mutter::MutterCompositor::state()).

pub async fn kill(self) -> Result<()>

Shut down the session in the required order.

Ordering is load-bearing:

1. Kill the app first. Its Wayland connection holds a reference into the compositor; killing the compositor first can make the app block on its Wayland socket during shutdown.
2. Drop the input and capture trait objects. For backends that share state with the compositor via Arc (e.g. mutter’s Arc<MutterState> holding the private D-Bus connection), the strong count has to reach zero before the compositor tears the underlying resource down.
3. Stop the compositor.

pub async fn press_keysym(&self, keysym: u32) -> Result<()>

Send a key press + release for the given X11 keysym.

pub async fn press_chord(&self, chord: &str) -> Result<()>

Press a chord like "Ctrl+Shift+A" — modifiers are held in order, the target key is pressed and released, then modifiers are released in reverse order.

Accepts single key names ("Return", "a") as chords with no modifiers. See crate::keysym::parse_chord for the full grammar. Returns an error if the chord can’t be parsed.

pub async fn pointer_motion_relative(&self, dx: f64, dy: f64) -> Result<()>

Move the pointer by a relative offset in logical pixels.

pub async fn pointer_motion_absolute(&self, x: f64, y: f64) -> Result<()>

Move the pointer to a screen-relative absolute position in logical pixels. Requires an active capture stream on backends that route through the compositor’s ScreenCast pipeline (mutter).

pub async fn pointer_button(&self, button: PointerButton) -> Result<()>

Press and release a pointer button.

pub async fn pointer_button_down(&self, button: PointerButton) -> Result<()>

Hold a pointer button down until a matching pointer_button_up fires. Used to build drag gestures — press, move across intermediate coordinates, then release.

pub async fn pointer_button_up(&self, button: PointerButton) -> Result<()>

Release a pointer button previously pressed with pointer_button_down.

pub async fn type_text(&self, text: &str) -> Result<()>

Type a string as keyboard input, one X11 keysym per char. Latin-1 characters map directly; other Unicode uses the 0x01000000 + codepoint encoding (see crate::keysym::char_to_keysym). Does not manage focus — call crate::Locator::focus or click the target widget first.

Observes the session’s cancellation token between characters so a long typed string bails promptly on kill_session instead of typing every remaining character before noticing. Cancellation latency is capped at one keystroke (~50ms backend-internal sleep); mid-keystroke cancel would require plumbing the token through the InputBackend trait.

pub async fn pointer_axis_discrete( &self, axis: PointerAxis, steps: i32, ) -> Result<()>

Emit a discrete pointer-axis (wheel) event. axis selects vertical or horizontal; steps is the number of wheel detents — positive scrolls down/right, negative scrolls up/left.

pub fn wayland_display(&self) -> &str

Wayland display socket name this session is running against.

pub async fn take_screenshot(&self) -> Result<Vec<u8>>

Capture a PNG screenshot from the keepalive stream.

pub fn default_timeout(&self) -> Duration

Default timeout applied to auto-wait on action methods and to explicit wait_for_* calls when the locator hasn’t overridden it via Locator::with_timeout.

Initialized at session start from the WAYDRIVER_DEFAULT_TIMEOUT_MS env var (milliseconds), falling back to 5 seconds. Mutable via set_default_timeout.

pub fn set_default_timeout(&self, timeout: Duration)

Override the default timeout for this session. Takes effect on the next wait / auto-wait call; in-flight waits keep the deadline they started with.

pub fn cancellation_token(&self) -> &CancellationToken

Cancellation token observed by long-running auto-wait loops in Locator. Returned as a reference because the internal handle is already cheap to clone (Arc<AtomicBool> under the hood); callers that need to stash a copy can call .clone() on the returned ref.

pub fn cancel(&self)

Trigger the session’s cancellation token. Idempotent — cancelling an already-cancelled token is a no-op. After calling this, any in-flight auto-wait will resolve promptly with Error::Cancelled so the caller can shut the session down cleanly.

pub fn stdout_lines(&self) -> Vec<String>

Snapshot of every stdout line the app process has printed so far.

The returned vector is a copy; later lines won’t appear in it even as the app continues to emit. Combine with stdout_cursor + wait_for_stdout_line for event-driven assertions, or call this directly after a wait_for_stdout_line if you want the full buffer.

pub fn stdout_cursor(&self) -> usize

Current length of the stdout buffer — useful as a high-water mark before an action so wait_for_stdout_line can ignore older lines from the buffer and only wait for ones emitted afterwards.

let before = session.stdout_cursor();
locator.click().await?;
session
    .wait_for_stdout_line(before, |l| l == "fixture-event: clicked ok", Duration::from_secs(1))
    .await?;

pub async fn wait_for_stdout_line<F>( &self, after: usize, pred: F, timeout: Duration, ) -> Result<String>

where F: Fn(&str) -> bool,

Wait for a stdout line matching pred to appear at or after index after in the buffer. Returns the matched line on success, Error::Timeout if no matching line arrives before the deadline, or Error::Cancelled if the session’s cancellation token trips while waiting (typically because kill_session fired).

Lines already in the buffer at or after after count as matches — there’s no “only future lines” mode. Pass self.stdout_cursor() before kicking off the action to exclude history.

pub async fn dump_tree(&self) -> Result<String>

Serialize the live AT-SPI accessibility tree rooted at this session’s application to XML. The same snapshot format XPath locators resolve against — useful for debugging selectors.

impl Session

XPath-based element targeting entry points. Implemented on Arc<Session> so the returned Locator can carry a shared reference back to the session for lazy resolution.

pub fn locate(self: &Arc<Self>, xpath: &str) -> Locator

Build a locator for the given XPath expression. Resolution is lazy — the tree is snapshotted and the selector evaluated fresh on each action or metadata read.

pub fn root(self: &Arc<Self>) -> Locator

Locator for the root element of the application’s accessibility tree.

pub fn find_by_id(self: &Arc<Self>, id: &str) -> Locator

Locator matching any element whose toolkit id attribute equals id. Convenience shorthand for session.locate("//*[@id='<id>']").

pub fn find_by_name(self: &Arc<Self>, name: &str) -> Locator

Locator matching any element whose accessible name equals name.

pub fn find_by_role_name(self: &Arc<Self>, role: &str, name: &str) -> Locator

Locator matching an element by PascalCase role and accessible name. For example, find_by_role_name("PushButton", "OK") compiles to //PushButton[@name='OK'].

Trait Implementations

impl Drop for Session

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.