hu.ibello.search.package-info Maven / Gradle / Ivy
Show all versions of ibello-api Show documentation
/*
* Ark-Sys Kft. licenses this file to you under
* the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/**
* 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 {@link hu.ibello.search.By}.
* - Search pattern: a single string. It's meaning depends on the search algorithm. For example,
* if search algorithm is {@link hu.ibello.search.By#CSS_SELECTOR}, then the search pattern
* is a valid CSS selector, and if search algorithm is {@link hu.ibello.search.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 {@link hu.ibello.elements.WebElement} instance,
* or a collection of elements: {@link hu.ibello.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 {@link hu.ibello.pages.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:
*
*
* - {@link hu.ibello.search.Find}
* - {@link hu.ibello.search.Position}
* - {@link hu.ibello.search.Relation}
*
*
* Examples:
*
*
* {@literal @}Find(selector="button")
* {@literal @}Position(type=PositionType.LEFT_FROM, selector="#ok-button")
* private WebElement cancelButton;
*
* {@literal @}Find(by=By.TAG_NAME, selector="button")
* {@literal @}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
* {@link hu.ibello.search.SearchTool} interface: it has some useful methods where the search
* conditions can be specified. Instances of this interface can be obtained by
* {@link hu.ibello.elements.WebElement#find()} and {@link hu.ibello.pages.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 {@link hu.ibello.search.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
*/
package hu.ibello.search;