WayDriver

https://docs.rs/waydriver
Admin
WayDriver is a headless GUI testing library for Wayland applications that launches apps in isolated...
Tokens:444,815
Snippets:4,195
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start Video Recording

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=

Initiates video recording for the session if a video output path is configured. It uses provided bitrate and FPS, falling back to defaults if not specified. This function is part of the session setup process.

```rust
let video_recorder = if let Some(ref path) = cfg.video_output {
            let bitrate = cfg
                .video_bitrate
                .unwrap_or(crate::capture::DEFAULT_VIDEO_BITRATE);
            let fps = cfg.video_fps.unwrap_or(crate::capture::DEFAULT_VIDEO_FPS);
            Some(
                capture
                    .start_recording(&keepalive_stream, path, bitrate, fps)
                    .await?,
            )
        } else {
            None
        };
```

--------------------------------

### Start Video Recording (Synchronous)

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/capture.rs.html?search=std%3A%3Avec

Initializes GStreamer, sets PipeWire environment variables, builds and starts a GStreamer pipeline for video recording. Requires a grab_png lock guard to serialize with screenshot operations.

```rust
fn start_recording_sync(
    node_id: u32,
    pipewire_socket: &Path,
    runtime_dir: &Path,
    output_path: PathBuf,
    bitrate: u32,
    fps: u32,
) -> Result<VideoRecorder> {
    let _guard = GRAB_PNG_LOCK
        .lock()
        .map_err(|e| Error::screenshot(format!("grab_png lock poisoned: {e}")))?;

    gst::init().map_err(|e| Error::screenshot_with("gstreamer init failed", e))?;

    // pipewiresrc reads these from the environment during state-transition to
    // READY. The GRAB_PNG_LOCK guard serializes us with screenshot grabs.
    unsafe {
        std::env::set_var("PIPEWIRE_REMOTE", pipewire_socket);
        std::env::set_var("XDG_RUNTIME_DIR", runtime_dir);
    }

    let pipeline_str = build_recording_pipeline_str(node_id, &output_path, bitrate, fps);

    let pipeline = gst::parse::launch(&pipeline_str)
        .map_err(|e| Error::screenshot_with("recording pipeline parse failed", e))?;
    let pipeline = pipeline
        .dynamic_cast::<gst::Pipeline>()
        .map_err(|_| Error::screenshot("parsed element is not a Pipeline"))?;

    pipeline
        .set_state(gst::State::Playing)
        .map_err(|e| Error::screenshot_with("failed to start recording pipeline", e))?;

    tracing::info!(path = %output_path.display(), node_id, "video recording started");

    Ok(VideoRecorder {
        pipeline: Some(pipeline),
        output_path,
    })
}
```

--------------------------------

### Start Video Recording

Source: https://docs.rs/waydriver/0.2.6/waydriver/capture/struct.VideoRecorder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a WebM recording from a PipeWire node to a specified output path, bitrate, and FPS. The function returns once the pipeline is in the PLAYING state.

```rust
pub async fn start( node_id: u32, pipewire_socket: &Path, output_path: &Path, bitrate: u32, fps: u32, ) -> Result<VideoRecorder>
```

--------------------------------

### Start New Session

Source: https://docs.rs/waydriver/0.2.6/waydriver/session/struct.Session.html?search=std%3A%3Avec

Constructs a new session from a pre-started compositor and matching input/capture backends. The caller must start the compositor first.

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

--------------------------------

### Start a New Session

Source: https://docs.rs/waydriver/0.2.6/waydriver/session/struct.Session.html

Constructs a new UI test session by combining a pre-started compositor with matching input and capture backends. Ensure the compositor is started before calling this function.

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

--------------------------------

### start_recording

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/backend.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a continuous WebM recording of a stream.

```APIDOC
## start_recording

### Description
Start a continuous WebM recording of `stream` written to `output_path` at the given `bitrate` (bits/sec) and `fps`. Returns a handle whose `stop()` must be awaited to finalize the file cleanly.

### Method
`async fn start_recording(&self, stream: &PipeWireStream, output_path: &Path, bitrate: u32, fps: u32) -> Result<crate::capture::VideoRecorder>`

### Parameters
- **stream** (`&PipeWireStream`): A reference to the active PipeWire stream to record.
- **output_path** (`&Path`): The path where the recording will be saved.
- **bitrate** (`u32`): The desired bitrate in bits per second.
- **fps** (`u32`): The desired frames per second.

### Returns
- `Result<crate::capture::VideoRecorder>`: A `Result` containing a `VideoRecorder` handle on success, or an error on failure. The `stop()` method of this handle must be awaited to finalize the recording.
```

--------------------------------

### Example Searches for FocusOutcome

Source: https://docs.rs/waydriver/0.2.6/waydriver/atspi/enum.FocusOutcome.html?search=

Provides examples of how to perform searches within the FocusOutcome enum, illustrating common patterns for type conversions and option handling.

```APIDOC
## Example Searches

This section provides examples of common search patterns that can be used with the FocusOutcome enum.

### Example 1: Searching for a specific type

```
std::vec
```

### Example 2: Searching for a type conversion

```
u32 -> bool
```

### Example 3: Searching for Option type transformations

```
Option<T>, (T -> U) -> Option<U>
```
```

--------------------------------

### Session::start

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=

Builds and starts a new Waydriver session. It takes pre-initialized compositor, input, and capture backends, along with a session configuration. The caller is responsible for ensuring the compositor is started before passing it.

```APIDOC
## Session::start

### Description
Builds and starts a new Waydriver session. It takes pre-initialized compositor, input, and capture backends, along with a session configuration. The caller is responsible for ensuring the compositor is started before passing it.

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- `Self`: A new `Session` instance.

#### Response Example
None
```

--------------------------------

### Basic Search Example

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/enum.PointerButton.html?search=

Demonstrates a basic search query for a standard library vector.

```rust
* std::vec
```

--------------------------------

### Type Conversion Search Example

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/enum.PointerButton.html?search=

Shows how to search for type conversions, specifically from u32 to bool.

```rust
u32 -> bool
```

--------------------------------

### start_recording

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/trait.CaptureBackend.html?search=u32+-%3E+bool

Starts a continuous WebM video recording from a stream to a specified output path, bitrate, and FPS.

```APIDOC
## fn start_recording

### Description
Start a continuous WebM recording of `stream` written to `output_path` at the given `bitrate` (bits/sec) and `fps`. Returns a handle whose `stop()` must be awaited to finalize the file cleanly.

### Method
`start_recording`

### Parameters
- **stream** (`&PipeWireStream`) - A reference to the active PipeWire stream.
- **output_path** (`&Path`) - The path where the recording will be saved.
- **bitrate** (`u32`) - The desired bitrate in bits per second.
- **fps** (`u32`) - The desired frames per second.

### Returns
A `Pin<Box<dyn Future<Output = Result<VideoRecorder>> + Send + 'async_trait>>>` representing the asynchronous operation to start the recording. The returned `VideoRecorder` handle must have its `stop()` method awaited.
```

--------------------------------

### Start a Waydriver Session

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=

Initializes a new Waydriver session by spawning the application process and setting up necessary backends. Requires a pre-started compositor, input, and capture backends, along with a configuration. The caller is responsible for ensuring the compositor is started before passing it.

```rust
impl Session {
    /// 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 start(
        compositor: Box<dyn CompositorRuntime>,
        input: Box<dyn InputBackend>,
        capture: Box<dyn CaptureBackend>,
        cfg: SessionConfig,
    ) -> Result<Self> {
        let id = compositor.id().to_string();
        tracing::info!(id, "starting session");

        let dbus_address = get_host_session_bus()?;
        let mut app = spawn_app(
            &cfg,
            compositor.wayland_display(),
            compositor.runtime_dir(),
            &dbus_address,
        )?;
        tracing::debug!(id, app_name = %cfg.app_name, "app spawned");

        let stdout = Arc::new(AppStdout::default());

```

--------------------------------

### start_recording

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/trait.CaptureBackend.html?search=

Starts a continuous WebM video recording from a PipeWire stream to a specified output path, bitrate, and frame rate.

```APIDOC
## start_recording

### Description
Start a continuous WebM recording of `stream` written to `output_path` at the given `bitrate` (bits/sec) and `fps`. Returns a handle whose `stop()` must be awaited to finalize the file cleanly.

### Method
`start_recording`

### Parameters
- `self`: A reference to the CaptureBackend implementation.
- `stream`: A reference to the `PipeWireStream` to record from.
- `output_path`: The path where the recording will be saved.
- `bitrate`: The desired bitrate in bits per second.
- `fps`: The desired frames per second.

### Return Value
A `Pin<Box<dyn Future<Output = Result<VideoRecorder>> + Send + 'async_trait>>>` representing an asynchronous operation that yields a `VideoRecorder` handle on success.
```

--------------------------------

### Generic Function Search Example

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/enum.PointerButton.html?search=

Illustrates searching for generic function signatures involving Option and type mapping.

```rust
Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### start_stream

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/backend.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a PipeWire capture stream. The returned PipeWireStream remains active until explicitly stopped.

```APIDOC
## start_stream

### Description
Starts a PipeWire capture stream. The returned `PipeWireStream` stays alive until explicitly stopped.

### Method
`async fn start_stream(&self) -> Result<PipeWireStream>`

### Parameters
None

### Returns
- `Result<PipeWireStream>`: A `Result` containing a `PipeWireStream` on success, or an error on failure.
```

--------------------------------

### Locate and Get XPath

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/locator.rs.html

Demonstrates locating a specific element by name and index, then asserting its generated XPath.

```rust
            .locate("PushButton")
            .nth(1);
        assert_eq!(loc.xpath(), "((//Dialog[@name='Confirm'])//PushButton)[2]");
```

--------------------------------

### Get a locator for the root element

Source: https://docs.rs/waydriver/0.2.6/waydriver/session/struct.Session.html?search=

Obtains a `Locator` that targets the root element of the application's accessibility tree. This is useful for starting element searches from the top of the tree.

```rust
session.root()
```

--------------------------------

### start Method Signature

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/trait.CompositorRuntime.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Spawns the compositor with an optional resolution and waits for it to be ready. Ensures Wayland display and runtime directories are available upon successful return.

```rust
fn start<'life0, 'life1, 'async_trait>(
    &'life0 mut self,
    resolution: Option<&'life1 str>,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: 'async_trait,
      'life0: 'async_trait,
      'life1: 'async_trait,
```

--------------------------------

### Handling File Metadata Operations

Source: https://docs.rs/waydriver/0.2.6/waydriver/error/type.Result.html?search=

Shows how to use `and_then` to chain fallible operations like getting file metadata and its modification time. It includes examples for both successful and failed path lookups.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Start Video Recording

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/capture.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes GStreamer, sets environment variables for PipeWire, and launches a recording pipeline. Ensures the recording is synchronized with screenshot captures.

```rust
fn start_recording_sync(
    node_id: u32,
    pipewire_socket: &Path,
    runtime_dir: &Path,
    output_path: PathBuf,
    bitrate: u32,
    fps: u32,
) -> Result<VideoRecorder> {
    let _guard = GRAB_PNG_LOCK
        .lock()
        .map_err(|e| Error::screenshot(format!("grab_png lock poisoned: {e}")))?;

    gst::init().map_err(|e| Error::screenshot_with("gstreamer init failed", e))?;

    // pipewiresrc reads these from the environment during state-transition to
    // READY. The GRAB_PNG_LOCK guard serializes us with screenshot grabs.
    unsafe {
        std::env::set_var("PIPEWIRE_REMOTE", pipewire_socket);
        std::env::set_var("XDG_RUNTIME_DIR", runtime_dir);
    }

    let pipeline_str = build_recording_pipeline_str(node_id, &output_path, bitrate, fps);

    let pipeline = gst::parse::launch(&pipeline_str)
        .map_err(|e| Error::screenshot_with("recording pipeline parse failed", e))?;
    let pipeline = pipeline
        .dynamic_cast::<gst::Pipeline>()
        .map_err(|_| Error::screenshot("parsed element is not a Pipeline"))?;

    pipeline
        .set_state(gst::State::Playing)
        .map_err(|e| Error::screenshot_with("failed to start recording pipeline", e))?;

    tracing::info!(path = %output_path.display(), node_id, "video recording started");

    Ok(VideoRecorder {
        pipeline: Some(pipeline),
        output_path,
    })
}

```

--------------------------------

### Test Session Initialization and Chord Press

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=

Demonstrates how to initialize a test session with stub backends and simulate a keyboard chord press. It verifies the sequence of recorded input events.

```rust
struct StubInput;
        #[async_trait]
        impl InputBackend for StubInput {
            async fn pointer_motion_relative(
                &self,
                _: f64,
                _: f64,
                _: &CancellationToken,
            ) -> Result<()> {
                Ok(())
            }
            async fn pointer_motion_absolute(
                &self,
                _: f64,
                _: f64,
                _: &CancellationToken,
            ) -> Result<()> {
                Ok(())
            }
            async fn pointer_button_down(
                &self,
                _: crate::backend::PointerButton,
                _: &CancellationToken,
            ) -> Result<()> {
                Ok(())
            }
            async fn pointer_button_up(
                &self,
                _: crate::backend::PointerButton,
                _: &CancellationToken,
            ) -> Result<()> {
                Ok(())
            }
            async fn pointer_axis_discrete(
                &self,
                _: crate::backend::PointerAxis,
                _: i32,
                _: &CancellationToken,
            ) -> Result<()> {
                Ok(())
            }
        }

        struct StubCompositor;
        #[async_trait]
        impl CompositorRuntime for StubCompositor {
            async fn start(&mut self, _: Option<&str>) -> Result<()> {
                Ok(())
            }
            async fn stop(&mut self) -> Result<()> {
                Ok(())
            }
            fn id(&self) -> &str {
                "s"
            }
            fn wayland_display(&self) -> &str {
                "d"
            }
            fn runtime_dir(&self) -> &Path {
                Path::new("/tmp")
            }
        }
        struct StubCapture;
        #[async_trait]
        impl CaptureBackend for StubCapture {
            async fn start_stream(&self) -> Result<PipeWireStream> {
                unimplemented!()
            }
            async fn stop_stream(&self, _: PipeWireStream) -> Result<()> {
                Ok(())
            }
            fn pipewire_socket(&self) -> PathBuf {
                PathBuf::from("/tmp")
            }
        }

        let events = Arc::new(Mutex::new(Vec::<Event>::new()));
        let s = Session::new_for_test(
            "t".into(),
            "a".into(),
            Box::new(RecordingInput(events.clone())),
            Box::new(StubCapture),
            Box::new(StubCompositor),
        );

        s.press_chord("Ctrl+Shift+A").await.unwrap();

        let ctrl = 0xffe3_u32;
        let shift = 0xffe1_u32;
        let a = crate::keysym::char_to_keysym('A');
        let recorded = events.lock().unwrap().iter().collect::<Vec<_>>().len();
        let got: Vec<Event> = std::mem::take(&mut *events.lock().unwrap());
        assert_eq!(recorded, 5);
        // Expected dispatch: ctrl down, shift down, press(A), shift up, ctrl up.
        assert_eq!(
            got,
            vec![
                Event::Down(ctrl),
                Event::Down(shift),
                Event::Press(a),
                Event::Up(shift),
                Event::Up(ctrl),
            ]
        );
```

--------------------------------

### Test Get Host Session Bus Fallback

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=

Tests the fallback mechanism for getting the session bus address when not provided in the environment.

```rust
    let result = get_host_session_bus_inner(None);
    assert!(
        result.contains("/run/user/"),
        "expected /run/user/ path, got: {result}"
    );
```

--------------------------------

### CompositorRuntime::start Method

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/trait.CompositorRuntime.html

Spawns the compositor with an optional virtual display resolution. It waits for the compositor to be ready, after which `wayland_display()` and `runtime_dir()` will be valid.

```rust
fn start<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        resolution: Option<&'life1 str>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
```

--------------------------------

### Test Get Host Session Bus Fallback

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html

Tests the fallback mechanism for getting the host session bus address when it is not set in the environment.

```rust
#[test]
fn test_get_host_session_bus_fallback() {
    let result = get_host_session_bus_inner(None);
    assert!(
        result.contains("/run/user/"),
        "expected /run/user/ path, got: {result}"
    );
}
```

--------------------------------

### Session::start

Source: https://docs.rs/waydriver/0.2.6/waydriver/session/struct.Session.html?search=std%3A%3Avec

Builds a new session from pre-started compositor, input, and capture backends. The caller must ensure the compositor is started before calling this method.

```APIDOC
## Session::start

### Description
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()`)

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **Self** (Session) - The newly created Session object.

#### Response Example
None
```

--------------------------------

### Session::start

Source: https://docs.rs/waydriver/0.2.6/waydriver/session/struct.Session.html

Builds a new Session instance. It requires a pre-started compositor along with matching input and capture backends. The caller is responsible for starting the compositor before invoking this method.

```APIDOC
## Session::start

### Description
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()`)

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

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **Self** (Session) - A new Session instance.

#### Response Example
None
```

--------------------------------

### Wait for Stdout Line Example

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=std%3A%3Avec

Demonstrates how to use `stdout_cursor` and `wait_for_stdout_line` to assert specific output after an action. This example is illustrative and marked as ignored.

```rust
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?;
```

--------------------------------

### Unsafe Undefined Behavior Example: unwrap_err_unchecked on Ok

Source: https://docs.rs/waydriver/0.2.6/waydriver/error/type.Result.html?search=std%3A%3Avec

This snippet shows an example of undefined behavior when `unwrap_err_unchecked` is called on a `Result` that is an `Ok`. This code should not be run.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

--------------------------------

### Session::start

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=std%3A%3Avec

Builds a new Session instance. It takes pre-initialized compositor, input, and capture backends, along with a SessionConfig. The caller must ensure the compositor is started before passing it.

```APIDOC
## Session::start

### Description
Builds a new Session instance. It takes pre-initialized compositor, input, and capture backends, along with a SessionConfig. The caller must ensure the compositor is started before passing it.

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Example usage (assuming necessary imports and setup)
// let compositor = ...;
// let input = ...;
// let capture = ...;
// let cfg = SessionConfig { ... };
// let session = Session::start(compositor, input, capture, cfg).await?;
```

### Response
#### Success Response
- `Self` (Session): A new Session instance.

#### Response Example
```rust
// On success, returns a Session instance.
```

### Error Handling
- Returns `Result<Self>` which can be an Err if session startup fails.
```

--------------------------------

### Unsafe Undefined Behavior Example: unwrap_unchecked on Err

Source: https://docs.rs/waydriver/0.2.6/waydriver/error/type.Result.html?search=std%3A%3Avec

This snippet shows an example of undefined behavior when `unwrap_unchecked` is called on a `Result` that is an `Err`. This code should not be run.

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

--------------------------------

### Session Start Method

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=u32+-%3E+bool

Constructs a new Waydriver session by initializing backends and spawning the application process. Requires a pre-started compositor.

```rust
impl Session {
    /// 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 start(
        compositor: Box<dyn CompositorRuntime>,
        input: Box<dyn InputBackend>,
        capture: Box<dyn CaptureBackend>,
        cfg: SessionConfig,
    ) -> Result<Self> {
        let id = compositor.id().to_string();
        tracing::info!(id, "starting session");

        let dbus_address = get_host_session_bus()?;
        let mut app = spawn_app(
            &cfg,
            compositor.wayland_display(),
            compositor.runtime_dir(),
            &dbus_address,
        )?;
        tracing::debug!(id, app_name = %cfg.app_name, "app spawned");

        let stdout = Arc::new(AppStdout::default());

```

--------------------------------

### Test Get Host Session Bus Fallback

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=std%3A%3Avec

Tests the fallback mechanism for getting the host session bus address when it is not set in the environment, ensuring it defaults to a path under /run/user/.

```rust
    #[test]
    fn test_get_host_session_bus_fallback() {
        let result = get_host_session_bus_inner(None);
        assert!(
            result.contains("/run/user/"),
            "expected /run/user/ path, got: {result}"
        );
    }
```

--------------------------------

### Start Video Recording

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/trait.CaptureBackend.html?search=

Initiates a WebM video recording from a PipeWire stream. Specify the output path, bitrate, and frames per second. Returns a `VideoRecorder` handle.

```rust
fn start_recording<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    stream: &'life1 PipeWireStream,
    output_path: &'life2 Path,
    bitrate: u32,
    fps: u32,
) -> Pin<Box<dyn Future<Output = Result<VideoRecorder>> + Send + 'async_trait>>
   where Self: 'async_trait,
         'life0: 'async_trait,
         'life1: 'async_trait,
         'life2: 'async_trait;
```

--------------------------------

### Session::start Method

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html

Initializes and starts a new Waydriver session. It requires pre-started compositor, input, and capture backends, along with session configuration. This function spawns the application process and sets up necessary session components.

```rust
pub async fn start(
        compositor: Box<dyn CompositorRuntime>,
        input: Box<dyn InputBackend>,
        capture: Box<dyn CaptureBackend>,
        cfg: SessionConfig,
    ) -> Result<Self> {
        let id = compositor.id().to_string();
        tracing::info!(id, "starting session");

        let dbus_address = get_host_session_bus()?;
        let mut app = spawn_app(
            &cfg,
            compositor.wayland_display(),
            compositor.runtime_dir(),
            &dbus_address,
        )?;
        tracing::debug!(id, app_name = %cfg.app_name, "app spawned");

        // ... rest of the function
    }
```

--------------------------------

### type_id

Source: https://docs.rs/waydriver/0.2.6/waydriver/session/struct.VisualTextTuning.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets the `TypeId` of `self`. This is part of the `Any` trait implementation.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
None

### Response
#### Success Response
- **TypeId**: The type identifier of the object.
```

--------------------------------

### Test Session Creation and Cancellation

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=

Demonstrates how to create a test session using stub backends and subsequently cancel it. It verifies that attempting to press a chord after cancellation results in a 'Cancelled' error.

```rust
let s = Session::new_for_test(
    "t".into(),
    "a".into(),
    Box::new(RejectInput),
    Box::new(StubCapture),
    Box::new(StubCompositor),
);
s.cancel();

let err = s.press_chord("Ctrl+A").await.unwrap_err();
assert!(
    matches!(err, Error::Cancelled),
    "expected Cancelled, got {err:?}"
);
```

--------------------------------

### Locator::count

Source: https://docs.rs/waydriver/0.2.6/waydriver/locator/struct.Locator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets the number of elements matched by this selector.

```APIDOC
## Locator::count

### Description
Returns the number of elements currently matched by this selector. This method does not auto-wait and returns the current count, which may be zero.

### Method
`async &self`

### Returns
- `Result<usize>`: The number of matched elements, or an error if the operation fails.
```

--------------------------------

### Any Trait Implementation

Source: https://docs.rs/waydriver/0.2.6/waydriver/session/struct.VisualTextTuning.html?search=std%3A%3Avec

Provides the `type_id` method to get the `TypeId` of the instance.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
None

### Response
- **TypeId**: The type identifier of the instance.
```

--------------------------------

### Test Session with Recording Input

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=std%3A%3Avec

Demonstrates creating a test session with a recording input backend to capture and assert input events.

```rust
struct StubCompositor;
#[async_trait]
impl CompositorRuntime for StubCompositor {
    async fn start(&mut self, _: Option<&str>) -> Result<()> {
        Ok(())
    }
    async fn stop(&mut self) -> Result<()> {
        Ok(())
    }
    fn id(&self) -> &str {
        "s"
    }
    fn wayland_display(&self) -> &str {
        "d"
    }
    fn runtime_dir(&self) -> &Path {
        Path::new("/tmp")
    }
}
struct StubCapture;
#[async_trait]
impl CaptureBackend for StubCapture {
    async fn start_stream(&self) -> Result<PipeWireStream> {
        unimplemented!()
    }
    async fn stop_stream(&self, _: PipeWireStream) -> Result<()> {
        Ok(())
    }
    fn pipewire_socket(&self) -> PathBuf {
        PathBuf::from("/tmp")
    }
}

let events = Arc::new(Mutex::new(Vec::<Event>::new()));
let s = Session::new_for_test(
    "t".into(),
    "a".into(),
    Box::new(RecordingInput(events.clone())),
    Box::new(StubCapture),
    Box::new(StubCompositor),
);

s.press_chord("Ctrl+Shift+A").await.unwrap();

let ctrl = 0xffe3_u32;
let shift = 0xffe1_u32;
let a = crate::keysym::char_to_keysym('A');
let recorded = events.lock().unwrap().iter().collect::<Vec<_>>().len();
let got: Vec<Event> = std::mem::take(&mut *events.lock().unwrap());
assert_eq!(recorded, 5);
// Expected dispatch: ctrl down, shift down, press(A), shift up, ctrl up.
assert_eq!(
    got,
    vec![
        Event::Down(ctrl),
        Event::Down(shift),
        Event::Press(a),
        Event::Up(shift),
        Event::Up(ctrl),
    ]
);
```

--------------------------------

### type_id

Source: https://docs.rs/waydriver/0.2.6/waydriver/locator/struct.Locator.html?search=std%3A%3Avec

Gets the `TypeId` of the Locator. This is useful for runtime type identification.

```APIDOC
## fn type_id(&self) -> TypeId

### Description
Gets the `TypeId` of `self`.

### Method
`type_id`

### Parameters
None

### Response
#### Success Response
- **TypeId**: The unique identifier for the type of `self`.
```

--------------------------------

### Get None-Equivalent Value

Source: https://docs.rs/waydriver/0.2.6/waydriver/session/struct.VisualClickTuning.html

Provides the default or none-equivalent value for a type.

```rust
type NoneType = T

fn null_value() -> T
```

--------------------------------

### stop_stream

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/backend.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Stops a previously started stream and releases backend-side resources.

```APIDOC
## stop_stream

### Description
Stops a previously started stream and releases backend-side resources.

### Method
`async fn stop_stream(&self, stream: PipeWireStream) -> Result<()>`

### Parameters
- **stream** (`PipeWireStream`): The stream to stop.

### Returns
- `Result<()>`: A `Result` indicating success or failure.
```

--------------------------------

### VideoRecorder::start

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/capture.rs.html

Starts a WebM recording from a specified PipeWire node to an output file. It configures the recording with a given bitrate and frame rate. The function returns a VideoRecorder handle once the pipeline is in the PLAYING state.

```APIDOC
## VideoRecorder::start

### Description
Starts a WebM recording that reads from the given PipeWire node and writes to `output_path` at the given `bitrate` (bits/sec) and `fps`. Returns once the pipeline is in PLAYING state.

### Method
`async fn start(
    node_id: u32,
    pipewire_socket: &Path,
    output_path: &Path,
    bitrate: u32,
    fps: u32,
) -> Result<VideoRecorder>

### Parameters
#### Path Parameters
- **node_id** (u32) - Required - The ID of the PipeWire node to capture from.
- **pipewire_socket** (&Path) - Required - The path to the PipeWire socket.
- **output_path** (&Path) - Required - The path where the recording will be saved.
- **bitrate** (u32) - Required - The target bitrate for the recording in bits per second.
- **fps** (u32) - Required - The desired frames per second for the recording.

### Response
#### Success Response
- **VideoRecorder** - A handle to the running recording.

#### Error Response
- **Result<VideoRecorder>** - Returns an error if the recording cannot be started.
```

--------------------------------

### Locator::role

Source: https://docs.rs/waydriver/0.2.6/waydriver/locator/struct.Locator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets the raw AT-SPI role name of the matched element.

```APIDOC
## Locator::role

### Description
Retrieves the raw AT-SPI role name (e.g., `"push button"`, `"menu item"`) of the matched element. Falls back to the PascalCase XML element tag only when the snapshot lacks a `role` attribute.

### Method
`async &self`

### Returns
- `Result<String>`: The raw AT-SPI role name, or an error if the operation fails.
```

--------------------------------

### VideoRecorder::start

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/capture.rs.html?search=std%3A%3Avec

Starts a WebM recording from a specified PipeWire node to an output file. The recording can be configured with a specific bitrate and frame rate. The method returns once the GStreamer pipeline is in the PLAYING state.

```APIDOC
## VideoRecorder::start

### Description
Starts a WebM recording that reads from the given PipeWire node and writes to `output_path` at the given `bitrate` (bits/sec) and `fps`. Returns once the pipeline is in PLAYING state.

### Method
`async fn start(
    node_id: u32,
    pipewire_socket: &Path,
    output_path: &Path,
    bitrate: u32,
    fps: u32,
) -> Result<VideoRecorder>

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Example usage (assuming necessary imports and setup)
// let recorder = VideoRecorder::start(1, Path::new("/tmp/pipewire.sock"), Path::new("/tmp/recording.webm"), 2_000_000, 15).await?;
```

### Response

#### Success Response
- `VideoRecorder`: A handle to the running recording.

#### Response Example
```rust
// On success, a VideoRecorder instance is returned.
```

### Error Handling
- Returns `Result<VideoRecorder>` which can be an `Error` if:
  - `spawn_blocking` fails.
  - `validate_pipewire_socket` fails.
```

--------------------------------

### Locator::role

Source: https://docs.rs/waydriver/0.2.6/waydriver/locator/struct.Locator.html?search=

Gets the raw AT-SPI role name of the matched element.

```APIDOC
## Locator::role

### Description
Raw AT-SPI role name (e.g. `"push button"`, `"menu item"`). Falls back to the PascalCase XML element tag only when the snapshot lacks a `role` attribute — which shouldn’t happen for live snapshots, but can in hand-crafted test XML.

### Method
`&self`

### Returns
- `Result<String>`: The raw AT-SPI role name.
```

--------------------------------

### Spawn Application Command

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=

Configures and spawns a new process for an application. It sets up environment variables, working directory, and standard input/output streams.

```rust
    let mut cmd = Command::new(&cfg.command);
    cmd.args(&cfg.args)
        .env("WAYLAND_DISPLAY", wayland_display)
        .env("DBUS_SESSION_BUS_ADDRESS", dbus_address)
        .env("XDG_RUNTIME_DIR", runtime_dir)
        .env("XDG_CONFIG_HOME", &config_dir)
        .env("GSETTINGS_BACKEND", "keyfile")
        .env("NO_AT_BRIDGE", "0")
        .env("GTK_A11Y", "atspi")
        .stdout(Stdio::piped())
        .stderr(Stdio::null());
    if let Some(dir) = &cfg.cwd {
        cmd.current_dir(dir);
    }
    cmd.spawn()
        .map_err(|e| Error::process_with(format!("app '{}'", cfg.command), e))
```

--------------------------------

### Get VideoRecorder Output Path

Source: https://docs.rs/waydriver/0.2.6/waydriver/capture/struct.VideoRecorder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the path where the WebM recording is being written.

```rust
pub fn output_path(&self) -> &Path
```

--------------------------------

### stop_stream

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/trait.CaptureBackend.html?search=u32+-%3E+bool

Stops a previously started PipeWire stream and releases backend resources.

```APIDOC
## fn stop_stream

### Description
Stop a previously started stream and release backend-side resources.

### Method
`stop_stream`

### Parameters
- **stream** (`PipeWireStream`) - The stream to stop.

### Returns
A `Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>>` representing the asynchronous operation to stop the stream.
```

--------------------------------

### stop_recording

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/backend.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Stops a previously started recording, flushing the WebM seekhead/cues before returning.

```APIDOC
## stop_recording

### Description
Stop a previously-started recording, flushing the WebM seekhead/cues before returning.

### Method
`async fn stop_recording(&self, recorder: crate::capture::VideoRecorder) -> Result<()>`

### Parameters
- **recorder** (`crate::capture::VideoRecorder`): The `VideoRecorder` handle for the recording to stop.

### Returns
- `Result<()>`: A `Result` indicating success or failure.
```

--------------------------------

### Spawn Application Command

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=std%3A%3Avec

Configures and spawns a new process for an application. It sets necessary environment variables like WAYLAND_DISPLAY, DBUS_SESSION_BUS_ADDRESS, and XDG_RUNTIME_DIR, and optionally sets the current working directory.

```rust
    // daemon ignores.
    let config_dir = runtime_dir.join("config");
    let _ = std::fs::create_dir_all(&config_dir);

    let mut cmd = Command::new(&cfg.command);
    cmd.args(&cfg.args)
        .env("WAYLAND_DISPLAY", wayland_display)
        .env("DBUS_SESSION_BUS_ADDRESS", dbus_address)
        .env("XDG_RUNTIME_DIR", runtime_dir)
        .env("XDG_CONFIG_HOME", &config_dir)
        .env("GSETTINGS_BACKEND", "keyfile")
        .env("NO_AT_BRIDGE", "0")
        .env("GTK_A11Y", "atspi")
        .stdout(Stdio::piped())
        .stderr(Stdio::null());
    if let Some(dir) = &cfg.cwd {
        cmd.current_dir(dir);
    }
    cmd.spawn()
        .map_err(|e| Error::process_with(format!("app '{}'", cfg.command), e))
```

--------------------------------

### VideoRecorder::start

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/capture.rs.html?search=

Starts a WebM recording from a specified PipeWire node to an output file. The recording is configured with a given bitrate and frame rate. The function returns a VideoRecorder handle once the pipeline is in the PLAYING state.

```APIDOC
## VideoRecorder::start

### Description
Starts a WebM recording that reads from the given PipeWire node and writes to `output_path` at the given `bitrate` (bits/sec) and `fps`. Returns once the pipeline is in PLAYING state.

### Method
`async fn start(
    node_id: u32,
    pipewire_socket: &Path,
    output_path: &Path,
    bitrate: u32,
    fps: u32,
) -> Result<VideoRecorder>

### Parameters
#### Path Parameters
- **node_id** (u32) - Required - The ID of the PipeWire node to capture from.
- **pipewire_socket** (&Path) - Required - The path to the PipeWire socket.
- **output_path** (&Path) - Required - The path where the WebM recording will be saved.
- **bitrate** (u32) - Required - The target bitrate for the recording in bits per second.
- **fps** (u32) - Required - The desired frame rate of the recording in frames per second.

### Response
#### Success Response
- **VideoRecorder** - A handle to the running recording. Must be stopped using `VideoRecorder::stop` to finalize the file.

#### Error Response
- **Result<VideoRecorder>** - Returns an error if the recording cannot be started, e.g., due to issues with the PipeWire socket or pipeline creation.
```

--------------------------------

### Root Locator

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/locator.rs.html

Get a locator for the root element of the document. This is typically represented by a wildcard.

```rust
let s = test_session();
assert_eq!(s.root().xpath(), "/*");
```

--------------------------------

### Session Initialization and Timeout Testing

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=

Demonstrates how to initialize a new Waydriver session for testing and verifies the default timeout and its persistence after modification.

```rust
let s = Session::new_for_test(
    "t".into(),
    "a".into(),
    Box::new(StubInput),
    Box::new(StubCapture),
    Box::new(StubCompositor),
);
// Default matches the fallback constant.
assert_eq!(s.default_timeout(), FALLBACK_DEFAULT_TIMEOUT);
// set_default_timeout persists.
s.set_default_timeout(Duration::from_millis(1234));
assert_eq!(s.default_timeout(), Duration::from_millis(1234));
```

--------------------------------

### default_timeout

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Gets the default timeout duration applied to auto-wait and explicit wait calls.

```APIDOC
## default_timeout

### Description
Gets the default timeout duration applied to auto-wait and explicit wait calls. This value is initialized from the `WAYDRIVER_DEFAULT_TIMEOUT_MS` environment variable.

### Method
`fn default_timeout(&self) -> Duration`

### Parameters
None

### Response
#### Success Response (200)
`Duration` representing the default timeout.
```

--------------------------------

### stop_recording

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/trait.CaptureBackend.html?search=

Stops a previously started video recording, ensuring the file is finalized cleanly.

```APIDOC
## stop_recording

### Description
Stop a previously-started recording, flushing the WebM seekhead/cues before returning.

### Method
`stop_recording`

### Parameters
- `self`: A reference to the CaptureBackend implementation.
- `recorder`: The `VideoRecorder` handle for the recording to stop.

### Return Value
A `Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>>` representing an asynchronous operation that yields `()` on success.
```

--------------------------------

### Session Initialization and Chord Validation Test

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html?search=

Demonstrates initializing a Waydriver session with stub backends and testing the error handling for invalid chord inputs.

```rust
let s = Session::new_for_test(
    "t".into(),
    "a".into(),
    Box::new(StubInput),
    Box::new(StubCapture),
    Box::new(StubCompositor),
);

let err = s.press_chord("Hyper+Nope").await.unwrap_err();
assert!(
    matches!(err, Error::Process { ref message, .. } if message.contains("invalid chord")),
    "expected process:invalid chord, got {err:?}"
);
```

--------------------------------

### stop_stream

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/trait.CaptureBackend.html?search=std%3A%3Avec

Stops a previously started PipeWire capture stream and releases backend-side resources.

```APIDOC
## stop_stream

### Description
Stop a previously started stream and release backend-side resources.

### Method
`stop_stream`

### Parameters
* `stream` (PipeWireStream) - The stream to stop.

### Returns
A `Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>>` representing the asynchronous operation to stop the stream.
```

--------------------------------

### stop_stream

Source: https://docs.rs/waydriver/0.2.6/waydriver/backend/trait.CaptureBackend.html?search=

Stops a previously started PipeWire capture stream and releases backend resources.

```APIDOC
## stop_stream

### Description
Stop a previously started stream and release backend-side resources.

### Method
`stop_stream`

### Parameters
- `self`: A reference to the CaptureBackend implementation.
- `stream`: The `PipeWireStream` to stop.

### Return Value
A `Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>>` representing an asynchronous operation that yields `()` on success.
```

--------------------------------

### Default VisualClickTuning Configuration

Source: https://docs.rs/waydriver/0.2.6/src/waydriver/session.rs.html

Provides the default settings for visual click tuning, used to configure the headless-mutter cold-start pointer-routing workaround.

```rust
impl Default for VisualClickTuning {
    fn default() -> Self {
        Self {
            cold_start_warmup_enabled: true,
            cold_start_warmup_offset_px: 4.0,
            cold_start_motion_settle: Duration::from_millis(60),
            cold_start_press_settle: Duration::from_millis(50),
        }
    }
}
```
Tokens:
Raw