@PublicApi
public interface PageElementSearch
DOM element. The search query object provided by this method
allows for issuing a sophisticated, multi-level search across the DOM and returning the result in a desired form.
The following paragraphs discuss the search query API.
SearchQuery object is essentially a sequence of search/transform/filter steps that are applied
sequentially, starting with the root context (either the entire page, or a specific DOM element, depending on what
this PageElementSearch refers to). Each single step will be applied to all parents that were found
by the previous steps, resulting in a new list of elements that will be roots for the next step, and so on until the
result is requested.
Each search query starts off as an instance of PageElementQuery - with element type
PageElement, however they may be converted into a more generic
AnyQuery by transforming/mapping the results, which limits the applicable operations to only those
applicable to any object (see AnyQuery and SearchQuery).
by locator, using one of the
by() methods on PageElementQuery. The search steps are only applicable if the element type of the
query is PageElement.
filters to further narrow down the results. Filters can be specified by
Guava predicates - the
PageElements class contains a collection of common predicates to use.
Clients can also use MatcherPredicate to convert Hamcrest
matchers into Guava predicates. The filter steps are applicable to any object, however filter steps preserve
the element type of the query.
mappers to map or flat map query results into some other objects (or collections of
thereof). Map steps are applicable to any object, however they do not preserve element type, and therefore can turn
PageElementQuery into a more generic AnyQuery. Some specialized page-element specific mapping steps
preserve the element type (see PageElementQuery).
Supplier.get() - get the list of resulting objects now. Note that search query thus implements a
specific Guava supplier, which makes it usable in all contexts where supplier can be usedSearchQuery.now()} - synonym to Supplier.get()SearchQuery.first() - obtain the first element of the result, or null if the results is empty
SearchQuery.hasResult() - obtain a TimedCondition
that will periodically execute the search and allow the client to wait until there is any result/there is no
result matching the query, with a desired timeout - using
PollerSearchQuery.timed() - obtain a TimedQuery that will
periodically execute the search and allow the client to wait until the result matches its expectations, with a
desired timeout - using Poller. This is the most recommended
way of obtaining the search query resultsspan elements in a drop-down that
represent users, and subsequently retrieves the username value from those elements, returning them as a
TimedQuery. The subsequent call to Poller (presumably in a
test) executes timed assertion that validates that the list contains 3 usernames ("alice", "bob" and "charlie")
within the timeout of an AJAX load (expecting the hypothetical drop-down to issue an AJAX call to populate its
contents).
public TimedQuery<String> getUsernames() {
return mySearch.search()
.by(By.id("user-dropdown"))
.by(By.tagName("li")) // can also use Elements.TAG_LI here
.filter(isVisible()) // from PageElements
.filter(hasClass("user-element")) // from PageElements
.by(By.tagName("span"), hasDataAttribute("username")) // from PageElements, check for "data-username" attribute
.withTimeout(TimeoutType.AJAX_ACTION)
.transform(getDataAttribute("username")) // from PageElements
.timed()
}
// ...
Poller.waitUntil(myDropdown.getUsernames(), Matchers.contains("alice", "bob", "charlie"));
SearchQuery,
AnyQuery,
PageElementQuery,
DefaultQuery| Modifier and Type | Method and Description |
|---|---|
DefaultQuery |
search() |
@Nonnull DefaultQuery search()
Copyright © 2015 Atlassian. All rights reserved.