thirtyfour::extensions

Module query

Source
Expand description

Advanced query interface featuring powerful filtering and polling options.

See examples for more details.

§Usage

§ElementQuery

The WebDriver::query() and WebElement::query() methods work out-of-the-box with no additional setup required. However, you can customize some of the behaviour if needed.

Now, using the query interface you can do things like this:

// This will only poll once and then return a bool immediately.
let is_found = driver
    .query(By::Id("button1"))
    .nowait()
    .exists()
    .await?;

// This will poll until either branch matches at least one element.
// Only the first matched element will be returned.
let elem = driver
    .query(By::Css("thiswont.match"))
    .or(By::Id("button1"))
    .first()
    .await?;

This will execute both queries once per poll iteration and return the first one that matches.

You can also filter on one or both query branches like this:

use thirtyfour::stringmatch::StringMatch;
let elem = driver
    .query(By::Css("thiswont.match"))
    .with_text("testing")
    .or(By::Id("button1"))
    .with_class(StringMatch::new("pure-button").word())
    .and_enabled()
    .first()
    .await?;

Note the use of StringMatch to provide a partial (whole-word) match on the class name. See the documentation for StringMatch for more info.

NOTE: Each filter will trigger an additional request to the WebDriver server for every poll iteration. It is therefore strongly recommended to use By::* selectors to perform filtering, if possible. The By::Css and By::XPath selectors may be required for more complex filters.

To fetch all matching elements instead of just the first one, simply change first() to all() and you’ll get a Vec instead. Note that all() will return only the elements from the query branch that first matched something. In the above example, if the (By::Css("branch.one")).with_text("testing") branch returned at least one element, then only those elements will be returned from an all() call even if the other branch would have matched something. If you want to fetch all elements matched by all branches, it’s probably best to execute multiple queries.

All timeout, interval and ElementPoller details can be overridden on a per-call basis if desired. See the ElementQuery documentation for more details.

§ElementWaiter

With ElementWaiter you can do things like this:

ⓘ
elem.wait_until().displayed().await?;
// You can optionally provide a nicer error message like this.
elem.wait_until().error("Timed out waiting for element to disappear").not_displayed().await?;

elem.wait_until().enabled().await?;
elem.wait_until().clickable().await?;

And so on. See the ElementWaiter docs for the full list of predicates available.

ElementWaiter also allows the user of custom predicates that take a &WebElement argument and return a WebDriverResult<bool>.

A range of pre-defined predicates are also supplied for convenience in the thirtyfour::extensions::query::conditions module.

ⓘ
use thirtyfour_query::conditions;

elem.wait_until().conditions(vec![
    conditions::element_is_displayed(true),
    conditions::element_is_clickable(true)
]).await?;

Take a look at the conditions module for the full list of predicates available. NOTE: Predicates require you to specify whether or not errors should be ignored.

These predicates (or your own) can also be supplied as filters to ElementQuery.

§ElementPoller

The polling strategy can be customized by implementing both ElementPoller and IntoElementPoller.

See ElementPollerWithTimeout for more details about the default polling behaviour.

Modules§

Structs§

  • ElementPollerNoWait
    No polling, single attempt.
  • ElementPollerWithTimeout
    Poll up to the specified timeout, with the specified interval being the minimum time elapsed between the start of each poll attempt. If the previous poll attempt took longer than the interval, the next will start immediately. Once the timeout is reached, a Timeout error will be returned regardless of the actual number of polling attempts completed.
  • ElementQuery
    High-level interface for performing powerful element queries using a builder pattern.
  • ElementQueryOptions
    All options applicable to an ElementQuery.
  • ElementSelector
    An ElementSelector contains a selector method (By) as well as zero or more filters. The filters will be applied to any elements matched by the selector. Selectors and filters all run in full on every poll iteration.
  • ElementWaiter
    High-level interface for performing explicit waits using the builder pattern.

Enums§

  • ElementQuerySource
    Elements can be queried from either a WebDriver or from a WebElement. The command issued to the webdriver will differ depending on the source, i.e. FindElement vs FindElementFromElement etc. but the ElementQuery interface is the same for both.
  • ElementQueryWaitOptions
    Options for wait characteristics for an element query.

Traits§

Functions§