geb.navigator.Locator.groovy Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of geb-core Show documentation
Geb (pronounced "jeb") is a browser automation solution. It brings together the power of WebDriver, the elegance of jQuery content selection, the robustness of Page Object modelling and the expressiveness of the Groovy language.
There is a newer version: 7.0
Show newest version
/*
 * Copyright 2014 the original author or authors.
 *
 * Licensed 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.
 */
package geb.navigator

import org.openqa.selenium.By

/**
 * Allows to create {@link geb.navigator.Navigator}s by selecting {@link org.openqa.selenium.WebElement}s
 * using different criteria (CSS selectors, attribute maps, indexes, ranges and {@link org.openqa.selenium.By} selectors).
 */
interface Locator extends BasicLocator {

    public static final String MATCH_ALL_SELECTOR = "*"

    /**
     * Shorthand for find(null, selector, null)
     *
     * @param selector
     * @return new Navigator
     */
    Navigator find(String selector)

    /**
     * Shorthand for find(selector)
     *
     * @param selector
     * @return new Navigator
     * @see #find(java.lang.String)
     */
    Navigator $(String selector)

    /**
     * Creates a new Navigator instance containing the elements whose attributes match the specified values or patterns.
     * The key 'text' can be used to match the text contained in elements. Regular expression Pattern objects may be
     * used as values.
     * Examples:
     * 
     * find(name: "firstName")
     * selects all elements with the name "firstName"
     * find(name: "firstName", readonly: "readonly")
     * selects all elements with the name "firstName" that are read-only
     * find(text: "I can has cheezburger")
     * selects all elements containing the exact text
     * find(text: ~/I can has.+/)
     * selects all elements whose text matches a regular expression
     * 
     * @param predicates a Map with keys representing attributes and values representing required values or patterns
     * @return a new Navigator instance containing the matched elements
     */
    Navigator find(Map attributes)

    /**
     * Shorthand for find(selector)[indexOfElement].
     * @param selector a CSS selector
     * @param index index of the required element in the selection
     * @return new Navigator instance containing a single element
     */
    Navigator find(String selector, int index)

    /**
     * Shorthand for find(null, selector, range)
     *
     * @param selector The css selector
     * @return new Navigator
     */
    Navigator find(String selector, Range range)

    /**
     * Shorthand for find(selector, index).
     *
     * @param selector a CSS selector
     * @param index index of the required element in the selection
     * @return new Navigator instance containing a single element
     * @see #find(java.lang.String, int)
     */
    Navigator $(String selector, int index)

    /**
     * Shorthand for find(selector, range)
     *
     * @param selector The css selector
     * @return new Navigator
     */
    Navigator $(String selector, Range range)

    /**
     * Shorthand for find(predicates, bySelector)
     *
     * @param bySelector a WebDriver By selector
     * @param predicates a Map with keys representing attributes and values representing required values or patterns
     * @return a new Navigator instance containing the matched elements
     */
    Navigator $(Map attributes, By bySelector)

    /**
     * Selects elements by both By selector and attributes. For example find(By.tagName("input"), name: "firstName") will select
     * all input elements with the name "firstName".
     * @param bySelector a WebDriver By selector
     * @param predicates a Map with keys representing attributes and values representing required values or patterns
     * @return a new Navigator instance containing the matched elements
     */
    Navigator find(Map attributes, By bySelector)

    /**
     * Shorthand for find(predicates, bySelector, index)
     *
     * @param bySelector a WebDriver By selector
     * @return new Navigator
     */
    Navigator $(Map attributes, By bySelector, int index)

    /**
     * Shorthand for find(predicates, bySelector, index..index)
     *
     * @param bySelector a WebDriver By selector
     * @return new Navigator
     */
    Navigator find(Map attributes, By bySelector, int index)

    /**
     * Shorthand for find(predicates, bySelector, range)
     *
     * @param bySelector a WebDriver By selector
     * @return new Navigator instance containing the matched elements
     */
    Navigator $(Map attributes, By bySelector, Range range)

    /**
     * Creates a new Navigator instance containing the elements matching the given
     * By type selector. Any By type capabilities supported by the underlying WebDriver instance are supported.
     * @param bySelector a WebDriver By selector
     * @return new Navigator instance containing the matched elements
     */
    Navigator find(Map attributes, By bySelector, Range range)

    /**
     * Shorthand for find(bySelector)
     *
     * @param bySelector a WebDriver By selector
     * @return new Navigator
     * @see BasciLocator#find(org.openqa.selenium.By)
     */
    Navigator $(By bySelector)

    /**
     * Shorthand for find(bySelector, index).
     *
     * @param bySelector a WebDriver By selector
     * @param index index of the required element in the selection
     * @return new Navigator instance containing a single element
     * @see #find(org.openqa.selenium.By, int)
     */
    Navigator $(By bySelector, int index)

    /**
     * Shorthand for find(bySelector)[indexOfElement].
     * @param bySelector a WebDriver By selector
     * @param index index of the required element in the selection
     * @return new Navigator instance containing a single element
     */
    Navigator find(By bySelector, int index)

    /**
     * Shorthand for find(bySelector, range)
     *
     * @param bySelector a WebDriver By selector
     * @return new Navigator
     */
    Navigator $(By bySelector, Range range)

    /**
     * Shorthand for find(null, bySelector, range)
     *
     * @param bySelector a WebDriver By selector
     * @return new Navigator
     */
    Navigator find(By bySelector, Range range)

    /**
     * Shorthand for find(predicates)
     *
     * @param predicates a Map with keys representing attributes and values representing required values or patterns
     * @return a new Navigator instance containing the matched elements
     */
    Navigator $(Map attributes)

    /**
     * Shorthand for find(predicates, null, index..index)
     *
     * @param selector
     * @return new Navigator
     */
    Navigator find(Map attributes, int index)

    /**
     * Shorthand for find(predicates, null, range)
     *
     * @param predicates attribute predicates
     * @param predicates range the range of matches to select
     * @return new Navigator
     */
    Navigator find(Map attributes, Range range)

    /**
     * Shorthand for find(predicates, index)
     *
     * @param selector
     * @return new Navigator
     */
    Navigator $(Map attributes, int index)

    /**
     * Shorthand for find(predicates, range)
     *
     * @param predicates attribute predicates
     * @param predicates range the range of matches to select
     * @return new Navigator
     */
    Navigator $(Map attributes, Range range)

    /**
     * Shorthand for find(predicates, selector)
     *
     * @param selector a CSS selector
     * @param predicates a Map with keys representing attributes and values representing required values or patterns
     * @return a new Navigator instance containing the matched elements
     */
    Navigator $(Map attributes, String selector)

    /**
     * Shorthand for find(predicates, selector, index..index)
     *
     * @param selector
     * @return new Navigator
     */
    Navigator find(Map attributes, String selector, int index)

    /**
     * Creates a new Navigator instance containing the elements matching the given
     * CSS selector. Any CSS capabilities supported by the underlying WebDriver instance are supported.
     * If the underlying WebDriver instance does not natively support finding elements by CSS selectors then tag, id
     * and class name selectors may be applied (in any combination).
     * Examples:
     * 
     * h1
     * selects all 'h1' elements
     * .article
     * selects all elements with the class 'article'
     * #header
     * selects the element with the id 'header'
     * div.article p
     * selects all p elements that are descendants of a div with class 'article'
     * h1, h2
     * selects all h1 and h2 elements
     * li:odd
     * selects odd-numbered li elements (CSS3 selectors like this are only supported when supported by the
     * underlying WebDriver instance)
     * 
     * @param selector a CSS selector
     * @return new Navigator instance containing the matched elements
     */
    Navigator find(Map attributes, String selector, Range range)

    /**
     * Shorthand for find(predicates, selector, index)
     *
     * @param selector
     * @return new Navigator
     */
    Navigator $(Map attributes, String selector, int index)

    /**
     * Shorthand for find(predicates, selector, range)
     *
     * @param selector a CSS selector
     * @return new Navigator instance containing the matched elements
     */
    Navigator $(Map attributes, String selector, Range range)
}