Struct thirtyfour::extensions::query::ElementQuery

pub struct ElementQuery { /* private fields */ }

High-level interface for performing powerful element queries using a builder pattern.

Example:

// WebDriver::query() example.
let elem = driver.query(By::Css("div[data-section='section-buttons']")).first().await?;
// WebElement::query() example.
let elem_button = elem.query(By::Id("button1")).first().await?;

Implementations

impl ElementQuery

pub fn new( source: ElementQuerySource, by: By, poller: Arc<dyn IntoElementPoller + Send + Sync> ) -> Self

Create a new ElementQuery.

See WebDriver::query() or WebElement::query() rather than instantiating this directly.

pub fn options(self, options: ElementQueryOptions) -> Self

Provide the options to use with this query.

pub fn desc(self, description: &str) -> Self

Provide a name that will be included in the error message if the query was not successful. This is useful for providing more context about this particular query.

pub fn ignore_errors(self, ignore: bool) -> Self

By default a query will ignore any errors that occur while polling for the desired element(s). However, this behaviour can be modified so that the waiter will return early if an error is returned from thirtyfour.

pub fn with_poller( self, poller: Arc<dyn IntoElementPoller + Send + Sync> ) -> Self

Use the specified ElementPoller for this ElementQuery. This will not affect the default ElementPoller used for other queries.

pub fn wait(self, timeout: Duration, interval: Duration) -> Self

Force this ElementQuery to wait for the specified timeout, polling once after each interval. This will override the poller for this ElementQuery only.

pub fn nowait(self) -> Self

Force this ElementQuery to not wait for the specified condition(s). This will override the poller for this ElementQuery only.

pub fn or(self, by: By) -> Self

Add a new selector to this ElementQuery. All conditions specified after this selector (up until the next or() method) will apply to this selector.

pub async fn exists(&self) -> WebDriverResult<bool>

Return true if an element matches any selector (including filters), otherwise false.

pub async fn not_exists(&self) -> WebDriverResult<bool>

Return true if no element matches any selector (including filters), otherwise false.

pub async fn first_opt(&self) -> WebDriverResult<Option<WebElement>>

Return the first WebElement that matches any selector (including filters).

Returns None if no elements match.

pub async fn first(&self) -> WebDriverResult<WebElement>

Return only the first WebElement that matches any selector (including filters).

Returns Err(WebDriverError::NoSuchElement) if no elements match.

pub async fn single(&self) -> WebDriverResult<WebElement>

Return only a single WebElement that matches any selector (including filters).

This method requires that only one element was found, and will return Err(WebDriverError::NoSuchElement) if the number of elements found after processing all selectors was not equal to 1.

This is useful because sometimes your element query is not specific enough and might accidentally match multiple elements. This is a common source of bugs in automated tests, because the first element might not actually be the one you expect.

By requiring that only one element is matched, you can be more sure that it is the one you intended.

pub async fn any(&self) -> WebDriverResult<Vec<WebElement>>

Return all WebElements that match any selector (including filters).

This will return when at least one element is found, after processing all selectors.

Returns an empty Vec if no elements match.

pub async fn any_required(&self) -> WebDriverResult<Vec<WebElement>>

Return all WebElements that match any selector (including filters).

This will return when at least one element is found, after processing all selectors.

Returns Err(WebDriverError::NoSuchElement) if no elements match.

pub async fn all(&self) -> WebDriverResult<Vec<WebElement>>

👎Deprecated since 0.32.0: use all_from_selector() instead

Return all WebElements that match any single selector (including filters).

pub async fn all_from_selector(&self) -> WebDriverResult<Vec<WebElement>>

Return all WebElements that match a single selector (including filters).

This will return when at least one element is found from any selector, without processing other selectors afterwards.

Returns an empty Vec if no elements match.

pub async fn all_required(&self) -> WebDriverResult<Vec<WebElement>>

👎Deprecated since 0.32.0: use all_from_selector_required() instead

Return all WebElements that match any single selector (including filters).

pub async fn all_from_selector_required( &self ) -> WebDriverResult<Vec<WebElement>>

Return all WebElements that match any single selector (including filters).

This will return when at least one element is found from any selector, without processing other selectors afterwards.

Returns Err(WebDriverError::NoSuchElement) if no elements match.

pub fn with_filter(self, f: ElementPredicate) -> Self

Add the specified ElementPredicate to the last selector.

pub fn and_enabled(self) -> Self

Only match elements that are enabled.

pub fn and_not_enabled(self) -> Self

Only match elements that are NOT enabled.

pub fn and_selected(self) -> Self

Only match elements that are selected.

pub fn and_not_selected(self) -> Self

Only match elements that are NOT selected.

pub fn and_displayed(self) -> Self

Only match elements that are displayed.

pub fn and_not_displayed(self) -> Self

Only match elements that are NOT displayed.

pub fn and_clickable(self) -> Self

Only match elements that are clickable.

pub fn and_not_clickable(self) -> Self

Only match elements that are NOT clickable.

pub fn with_text<N>(self, text: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that have the specified text. See the Needle documentation for more details on text matching rules.

pub fn without_text<N>(self, text: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have the specified text. See the Needle documentation for more details on text matching rules.

pub fn with_id<N>(self, id: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that have the specified id. See the Needle documentation for more details on text matching rules.

pub fn without_id<N>(self, id: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have the specified id. See the Needle documentation for more details on text matching rules.

pub fn with_class<N>(self, class_name: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that contain the specified class name. See the Needle documentation for more details on text matching rules.

pub fn without_class<N>(self, class_name: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not contain the specified class name. See the Needle documentation for more details on text matching rules.

pub fn with_tag<N>(self, tag_name: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that have the specified tag. See the Needle documentation for more details on text matching rules.

pub fn without_tag<N>(self, tag_name: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have the specified tag. See the Needle documentation for more details on text matching rules.

pub fn with_value<N>(self, value: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that have the specified value. See the Needle documentation for more details on text matching rules.

pub fn without_value<N>(self, value: N) -> Self

where N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have the specified value. See the Needle documentation for more details on text matching rules.

pub fn with_attribute<S, N>(self, attribute_name: S, value: N) -> Self

where S: Into<String>, N: Needle + Clone + Send + Sync + 'static,

Only match elements that have the specified attribute with the specified value. See the Needle documentation for more details on text matching rules.

pub fn without_attribute<S, N>(self, attribute_name: S, value: N) -> Self

where S: Into<String>, N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have the specified attribute with the specified value. See the Needle documentation for more details on text matching rules.

pub fn with_attributes<S, N>(self, desired_attributes: &[(S, N)]) -> Self

where S: Into<String> + Clone, N: Needle + Clone + Send + Sync + 'static,

Only match elements that have all of the specified attributes with the specified values. See the Needle documentation for more details on text matching rules.

pub fn without_attributes<S, N>(self, desired_attributes: &[(S, N)]) -> Self

where S: Into<String> + Clone, N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have any of the specified attributes with the specified values. See the Needle documentation for more details on text matching rules.

pub fn with_property<S, N>(self, property_name: S, value: N) -> Self

where S: Into<String>, N: Needle + Clone + Send + Sync + 'static,

Only match elements that have the specified property with the specified value. See the Needle documentation for more details on text matching rules.

pub fn without_property<S, N>(self, property_name: S, value: N) -> Self

where S: Into<String>, N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have the specified property with the specified value. See the Needle documentation for more details on text matching rules.

pub fn with_properties<S, N>(self, desired_properties: &[(S, N)]) -> Self

where S: Into<String> + Clone, N: Needle + Clone + Send + Sync + 'static,

Only match elements that have all of the specified properties with the specified value. See the Needle documentation for more details on text matching rules.

pub fn without_properties<S, N>(self, desired_properties: &[(S, N)]) -> Self

where S: Into<String> + Clone, N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have any of the specified properties with the specified value. See the Needle documentation for more details on text matching rules.

pub fn with_css_property<S, N>(self, css_property_name: S, value: N) -> Self

where S: Into<String>, N: Needle + Clone + Send + Sync + 'static,

Only match elements that have the specified CSS property with the specified value. See the Needle documentation for more details on text matching rules.

pub fn without_css_property<S, N>(self, css_property_name: S, value: N) -> Self

where S: Into<String>, N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have the specified CSS property with the specified value. See the Needle documentation for more details on text matching rules.

pub fn with_css_properties<S, N>( self, desired_css_properties: &[(S, N)] ) -> Self

where S: Into<String> + Clone, N: Needle + Clone + Send + Sync + 'static,

Only match elements that have all of the specified CSS properties with the specified values. See the Needle documentation for more details on text matching rules.

pub fn without_css_properties<S, N>( self, desired_css_properties: &[(S, N)] ) -> Self

where S: Into<String> + Clone, N: Needle + Clone + Send + Sync + 'static,

Only match elements that do not have any of the specified CSS properties with the specified values. See the Needle documentation for more details on text matching rules.

Trait Implementations

impl Debug for ElementQuery

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

Formats the value using the given formatter.