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<AccessibilityConnection>,
    /* 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<AccessibilityConnection>

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_button(&self, button: u32) -> Result<()>

Press and release a pointer button (Linux evdev code, e.g. BTN_LEFT = 0x110).

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 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, or Error::Timeout if no matching line arrives before the deadline.

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.