com.atlassian.pageobjects.elements.search

Interface PageElementSearch

All Known Subinterfaces:

CheckboxElement, MultiSelectElement, PageElement, SelectElement

All Known Implementing Classes:

GlobalPageElementSearch, WebDriverCheckboxElement, WebDriverElement, WebDriverMultiSelectElement, WebDriverSelectElement

@PublicApi
public interface PageElementSearch

Search Overview

Access point to advanced search within the context of the whole page, or a particular 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.

Search query

The 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).

Search Steps

Each search step must be specified using a 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.

Filter Steps

Each query supports 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.

Mapping Steps

Each query supports 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).

Query results

The search query object offers multiple methods to obtain the results, depending on what the client wants to achieve:

• 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 used
• SearchQuery.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 Poller
• SearchQuery.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 results

Example

The following method (presumably in a page object) searches for all the span 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"));
 
 

Since:

2.3

See Also:

SearchQuery, AnyQuery, PageElementQuery, DefaultQuery

Method Summary

Modifier and Type	Method and Description
DefaultQuery	search()

Method Detail

search

@Nonnull
DefaultQuery search()

Returns:

a new search query object that allows execute the search in the current context