Interface Summary
Interface	Description
SearchModifier	All instances of this interface are search modifiers used by ibello element search engine.
SearchTool	Interface for searching elements on a page.

Enum Summary
Enum	Description
By	This enum symbolizes an element search algorithm.
PositionType	Constants of this enum specifies the relative position of an element from an anchor element.
RelationType	Constants of this enum specifies the relation of an element and an anchor element.

Annotation Types Summary
Annotation Type	Description
Find	Basic search annotation.
Frame	This annotation is used on `PageObject` implementations to specify the `iframe` parent of all elements described by the page.
Frames
Position	This annotation modifies the element search in a page object (see `PageObject`).
Positions	Internal helper annotation for `Position`.
Relation	This annotation modifies the element search in a page object (see `PageObject`).
Relations	Internal helper annotation for `Relation`.
Window	This annotation is used to specify the browser window of a page object or step library instance.

Package hu.ibello.search Description

This package contains interfaces, annotations and enums used in element search.

Ibello Element Search Engine

During element search we are trying to find some elements on the current page by specifying search conditions. These conditions are:

Search algorithm: the algorithm how the search is processed. The available search algorithms are available as enum constants in By.
Search pattern: a single string. It's meaning depends on the search algorithm. For example, if search algorithm is By.CSS_SELECTOR, then the search pattern is a valid CSS selector, and if search algorithm is By.TAG_NAME, the the pattern is a valid HTML tag name.
Search parameters: the search pattern may contain parameter substitution markers. A parameter substitution marker is a 0-based index surrounded by ${ and }. Parameters are transformed to string and substituted into those markers by index. For example, if pattern is "${0}-${1}", then the method will replace ${0} with the first parameter, and ${1} with the second parameter. If the parameters are "a" and 1, then the result will be "a-1".
Search modifiers: each search may have one or more modifiers. These are just another conditions for the search. Some are conditions about the position of the desired elements, another ones specify the relation of the desired elements to another elements on the page.

The result of an element search is a single WebElement instance, or a collection of elements: WebElements.

An elements search can be static or dynamic.

During a static element search the search conditions are specified with annotations added to fields of a page object (see PageObject). The search is performed automatically when the page object is initialized, and the results are stored in the field's value. These annotations are:

Examples:

  @Find(selector="button")
  @Position(type=PositionType.LEFT_FROM, selector="#ok-button")
 private WebElement cancelButton;
 
  @Find(by=By.TAG_NAME, selector="button")
  @Relation(type=RelationType.DESCENDANT_OF, selector="#modal-window")
 private WebElement modalButton;

During a dynamic element search java methods are called directly. This is possible with the use of SearchTool interface: it has some useful methods where the search conditions can be specified. Instances of this interface can be obtained by WebElement.find() and PageObject.find(). Examples (in a page object):

 WebElement okButton = find().using("#ok-button").first();
 WebElement cancelButton = find().using("button").leftFrom(okButton).first();
 WebElement modalButton = find().using("#modal-window").first().find().using(By.TAG_NAME, "button").first();

In some cases the desired elements are in a HTML iframe element. To find these elements, the page object, which contains those element references, should have a Frame annotation with the search properties of the iframe. In this case every element searches performed by that page object will be executed inside of that specific iframe.

Author:: Kornél Simon