Enum By 

pub enum By {
    Id(String),
    Name(String),
    Xpath(String),
    UiAutomator(String),
    AndroidDataMatcher(String),
    AndroidViewMatcher(String),
    AndroidViewTag(String),
    IosClassChain(String),
    IosNsPredicate(String),
    AccessibilityId(String),
    ClassName(String),
    Image(String),
    Custom(String),
    CustomKind(String, String),
}

Locators supported by Appium

If you wish to use your very own locator (e.g. something I didn’t implement in this enum), just use By::CustomKind.

Variants

Id(String)

Name(String)

Xpath(String)

UiAutomator(String)

AndroidDataMatcher(String)

AndroidViewMatcher(String)

AndroidViewTag(String)

IosClassChain(String)

IosNsPredicate(String)

AccessibilityId(String)

ClassName(String)

Image(String)

Custom(String)

CustomKind(String, String)

Implementations

impl By

pub fn id(id: &str) -> By

Native element identifier. resource-id for android; name for iOS.

pub fn name(name: &str) -> By

Name of element.

pub fn xpath(query: &str) -> By

Search the app XML source using xpath (not recommended, has performance issues).

pub fn uiautomator(query: &str) -> By

Use the UI Automator API, in particular the UiSelector class to locate elements. (UiAutomator2 only).

In Appium you send the Java code, as a string, to the server, which executes it in the application’s environment, returning the element or elements.

See https://developer.android.com/reference/androidx/test/uiautomator/UiSelector

Examples found in repository

examples/find_by.rs (line 39)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Capabilities describe the automation environment,
    // for example: what app are we testing
    let mut capabilities = AndroidCapabilities::new();
    capabilities.app("https://github.com/appium/android-apidemos/releases/download/v3.1.0/ApiDemos-debug.apk");

    // To add custom capability that is not supported by this library just use "insert".
    // Alternatively, there are helpful functions like "set_bool", "set_str".
    // You can read more about capabilities on Appium website - https://appium.io/docs/en/2.1/guides/caps/.
    capabilities.set_str("appium:automationName", "uiautomator2");
    capabilities.set_bool("appium:fullReset", true);

    // To start automation, you need to build a client.
    let client = ClientBuilder::native(capabilities)
        .connect("http://localhost:4723/")
        .await?;

    // The app should automatically start, let's print the DOM of current app screen.
    let value = client.source().await?;
    println!("{value}");

    // Screen orientation is another Appium perk
    let orientation = client.orientation().await?;
    println!("Screen orientation: {orientation}");

    // Now we try to locate a button using UiAutomator API.
    // Notice that the program will wait until the button appears on screen (but maximum of 30 seconds).
    let views_button = client
        .appium_wait()
        .for_element(By::uiautomator("new UiSelector().text(\"Views\");"))
        .await?;

    views_button.click().await?;

    // Search for a vec of elements, because we know that there will be more than one result.
    // Notice that this time we don't wait, just find everything that's on screen as is.
    let menu_elements = client
        .find_all_by(By::uiautomator("new UiSelector().className(\"android.widget.TextView\");"))
        .await?;

    menu_elements.get(1)
        .unwrap()
        .click()
        .await?;

    // To add a timeout for wait, use "at_most".
    // "check_every" limits how often Appium has to perform the search during wait.
    //
    // Sometimes it's better to use one or both of those methods, because:
    // 1) We know that something should appear sooner, and if it doesn't, we don't want to wait full 30 seconds.
    // 2) We don't want to slow down Appium server by checking again too often.
    let element = client
        .appium_wait()
        .at_most(Duration::from_secs(20))
        .check_every(Duration::from_millis(500))
        .for_element(By::class_name("android.widget.ListView"))
        .await?;

    // This is a simple search for one element, without waiting for it to appear. And then we click on it.
    // Notice that we are searching for an element inside "element" (which is a ListView).
    element
        .find_by(By::accessibility_id("3D Transition"))
        .await?
        .click()
        .await?;

    Ok(())
}

pub fn android_data_matcher(query: &str) -> By

Locate an element using Espresso DataMatcher. (Espresso only)

pub fn android_view_matcher(query: &str) -> By

Locate an element using Espresso ViewMatcher. (Espresso only)

pub fn android_view_tag(query: &str) -> By

Locate an element by its view tag. (Espresso only)

pub fn ios_class_chain(query: &str) -> By

Locate an element by a class chain - a faster, but less powerful alternative to XPath on iOS.

pub fn ios_ns_predicate(query: &str) -> By

A string corresponding to a recursive element search using the iOS Predicate. (iOS 10.0 and above)

pub fn accessibility_id(id: &str) -> By

Read a unique identifier for a UI element.

For XCUITest it is the element’s accessibility-id attribute. For Android it is the element’s content-desc attribute.

Examples found in repository

examples/scroll.rs (line 18)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut capabilities = AndroidCapabilities::new_uiautomator();
    capabilities.app("https://github.com/appium/android-apidemos/releases/download/v3.1.0/ApiDemos-debug.apk");

    let client = ClientBuilder::native(capabilities)
        .connect("http://localhost:4723/")
        .await?;

    // Go to a screen with a long list
    client.find_by(By::accessibility_id("Views"))
        .await?
        .click()
        .await?;

    // Let's calculate some things first
    let (width, height) = client.get_window_size().await?;

    // This is the horizontal center, it will be our x for swipe.
    let horizontal_center = (width / 2) as i64;

    // The swipe will start at 80% of screen height, and end at 20% of screen height.
    // So we will swipe UP through most of the screen.
    let almost_top = (height as f64 * 0.2) as i64;
    let almost_bottom = (height as f64 * 0.8) as i64;

    let swipe_down = TouchActions::new("finger".to_string())
        // position the finger first
        .then(PointerAction::MoveTo {
            duration: Some(Duration::from_millis(0)),
            x: horizontal_center,
            y: almost_bottom,
        })
        // THEN touch the screen
        .then(PointerAction::Down {
            button: MOUSE_BUTTON_LEFT // believe me, it is not a mouse, but a simple touch
        })
        // THEN move the finger through the screen
        .then(PointerAction::MoveTo {
            duration: Some(Duration::from_millis(500)),
            x: horizontal_center,
            y: almost_top,
        });

    client.perform_actions(swipe_down)
        .await?;

    Ok(())
}

examples/find_by.rs (line 71)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Capabilities describe the automation environment,
    // for example: what app are we testing
    let mut capabilities = AndroidCapabilities::new();
    capabilities.app("https://github.com/appium/android-apidemos/releases/download/v3.1.0/ApiDemos-debug.apk");

    // To add custom capability that is not supported by this library just use "insert".
    // Alternatively, there are helpful functions like "set_bool", "set_str".
    // You can read more about capabilities on Appium website - https://appium.io/docs/en/2.1/guides/caps/.
    capabilities.set_str("appium:automationName", "uiautomator2");
    capabilities.set_bool("appium:fullReset", true);

    // To start automation, you need to build a client.
    let client = ClientBuilder::native(capabilities)
        .connect("http://localhost:4723/")
        .await?;

    // The app should automatically start, let's print the DOM of current app screen.
    let value = client.source().await?;
    println!("{value}");

    // Screen orientation is another Appium perk
    let orientation = client.orientation().await?;
    println!("Screen orientation: {orientation}");

    // Now we try to locate a button using UiAutomator API.
    // Notice that the program will wait until the button appears on screen (but maximum of 30 seconds).
    let views_button = client
        .appium_wait()
        .for_element(By::uiautomator("new UiSelector().text(\"Views\");"))
        .await?;

    views_button.click().await?;

    // Search for a vec of elements, because we know that there will be more than one result.
    // Notice that this time we don't wait, just find everything that's on screen as is.
    let menu_elements = client
        .find_all_by(By::uiautomator("new UiSelector().className(\"android.widget.TextView\");"))
        .await?;

    menu_elements.get(1)
        .unwrap()
        .click()
        .await?;

    // To add a timeout for wait, use "at_most".
    // "check_every" limits how often Appium has to perform the search during wait.
    //
    // Sometimes it's better to use one or both of those methods, because:
    // 1) We know that something should appear sooner, and if it doesn't, we don't want to wait full 30 seconds.
    // 2) We don't want to slow down Appium server by checking again too often.
    let element = client
        .appium_wait()
        .at_most(Duration::from_secs(20))
        .check_every(Duration::from_millis(500))
        .for_element(By::class_name("android.widget.ListView"))
        .await?;

    // This is a simple search for one element, without waiting for it to appear. And then we click on it.
    // Notice that we are searching for an element inside "element" (which is a ListView).
    element
        .find_by(By::accessibility_id("3D Transition"))
        .await?
        .click()
        .await?;

    Ok(())
}

pub fn class_name(class_name: &str) -> By

Locate element by its class name.

For IOS it is the full name of the XCUI element and begins with XCUIElementType. For Android it is the full name of the UIAutomator2 class (e.g.: android.widget.TextView)

Examples found in repository

examples/find_by.rs (line 65)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Capabilities describe the automation environment,
    // for example: what app are we testing
    let mut capabilities = AndroidCapabilities::new();
    capabilities.app("https://github.com/appium/android-apidemos/releases/download/v3.1.0/ApiDemos-debug.apk");

    // To add custom capability that is not supported by this library just use "insert".
    // Alternatively, there are helpful functions like "set_bool", "set_str".
    // You can read more about capabilities on Appium website - https://appium.io/docs/en/2.1/guides/caps/.
    capabilities.set_str("appium:automationName", "uiautomator2");
    capabilities.set_bool("appium:fullReset", true);

    // To start automation, you need to build a client.
    let client = ClientBuilder::native(capabilities)
        .connect("http://localhost:4723/")
        .await?;

    // The app should automatically start, let's print the DOM of current app screen.
    let value = client.source().await?;
    println!("{value}");

    // Screen orientation is another Appium perk
    let orientation = client.orientation().await?;
    println!("Screen orientation: {orientation}");

    // Now we try to locate a button using UiAutomator API.
    // Notice that the program will wait until the button appears on screen (but maximum of 30 seconds).
    let views_button = client
        .appium_wait()
        .for_element(By::uiautomator("new UiSelector().text(\"Views\");"))
        .await?;

    views_button.click().await?;

    // Search for a vec of elements, because we know that there will be more than one result.
    // Notice that this time we don't wait, just find everything that's on screen as is.
    let menu_elements = client
        .find_all_by(By::uiautomator("new UiSelector().className(\"android.widget.TextView\");"))
        .await?;

    menu_elements.get(1)
        .unwrap()
        .click()
        .await?;

    // To add a timeout for wait, use "at_most".
    // "check_every" limits how often Appium has to perform the search during wait.
    //
    // Sometimes it's better to use one or both of those methods, because:
    // 1) We know that something should appear sooner, and if it doesn't, we don't want to wait full 30 seconds.
    // 2) We don't want to slow down Appium server by checking again too often.
    let element = client
        .appium_wait()
        .at_most(Duration::from_secs(20))
        .check_every(Duration::from_millis(500))
        .for_element(By::class_name("android.widget.ListView"))
        .await?;

    // This is a simple search for one element, without waiting for it to appear. And then we click on it.
    // Notice that we are searching for an element inside "element" (which is a ListView).
    element
        .find_by(By::accessibility_id("3D Transition"))
        .await?
        .click()
        .await?;

    Ok(())
}

pub fn image(base64_template: &str) -> By

Locate an element by matching it with a base 64 encoded image file

pub fn custom(query: &str) -> By

Custom locator for use with plugins registered via the customFindModules capability.

pub fn custom_kind(using: &str, value: &str) -> By

A locator for non-standard locators

You can define what type of locator to use, so you’re free to use anything here.

Trait Implementations

impl Clone for By

fn clone(&self) -> By

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for By

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<By> for LocatorParameters

fn from(val: By) -> Self

Converts to this type from the input type.

impl PartialEq for By

fn eq(&self, other: &By) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for By

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for By