com.atlassian.jira.webtest.framework.core.locator
Interface Locator

All Superinterfaces:
LocatorData
All Known Subinterfaces:
SeleniumLocator
All Known Implementing Classes:
AbstractSeleniumLocator

public interface Locator
extends LocatorData

Locator is used to locate page object in the current test context. Locator is uniquely identified by its type (one of default types defined in Locators, or a custom one) and value.

Clients may examine and act upon page elements located by locators by means of the element() method.

Two distinct locator instances may, or may not be compatible with each other, which is not necessarily a matter of their type. This may be examined by means of the supports(com.atlassian.jira.webtest.framework.core.locator.Locator) method. Compatibility is used to determined if a, whether one locator may be nested within another, which is done by means of the combine(com.atlassian.jira.webtest.framework.core.locator.Locator) method.

Note that so defined compatibility is not a symmetric relation, e.g. a jQuery locator may be able to nest an ID locator within it, but a non-sophisticated ID locator might not accept a jQuery locator to nest within itself (even though it is possible and trivial to implement). It follows that a.supports(b) == true does not imply b.support(a) == true.

Since:
v4.2

Method Summary
 Locator combine(Locator toNest)
           Given toNest, return a new locator that represents an element located by toNest and nested within the element represented by this locator.
 Element element()
           Retrieve element corresponding to this locator.
 boolean supports(Locator other)
           Verify if the other locator is supported by this locator.
 
Methods inherited from interface com.atlassian.jira.webtest.framework.core.locator.LocatorData
type, value
 

Method Detail

element

Element element()

Retrieve element corresponding to this locator.

In case the locator locates more then one element, implementations are allowed to:

In most cases locating more than one element is a either a mistake on the side of test developer, or a result of an invalid page (e.g. two elements with the same ID).

Returns:
element this locator on a page in the current test context
Throws:
IllegalStateException - implementations are allowed to throw it if this locator locates more than one element

supports

boolean supports(Locator other)

Verify if the other locator is supported by this locator. This means that other may be used in the combine(com.atlassian.jira.webtest.framework.core.locator.Locator) method of this locator.

This usually involves type compatibility between the locators and optionally compatibility of the particular locator instances in the current test context.

Example: a jQuery locator would possibly return true for another jQuery locator, as well as an id and a class locator, but might return false for an xpath locator, unless it is a very sophisticated implementation capable of translating xpath into jQuery/css.

Parameters:
other - the other locator checked for compatibility
Returns:
true, if this locator instance is compatible with the other in the current context

combine

Locator combine(Locator toNest)

Given toNest, return a new locator that represents an element located by toNest and nested within the element represented by this locator.

toNest must be compatible with this locator, which may be examined by means of the supports(com.atlassian.jira.webtest.framework.core.locator.Locator) method.

Parameters:
toNest - locator to nest within this locator
Returns:
new locator representing the nested locator. Most likely (but not necessarily) it will have the same type as this locator
Throws:
LocatorIncompatibleException - if toNest is incompatible with this locator (i.e. supports(com.atlassian.jira.webtest.framework.core.locator.Locator) returns false for toNest.


Copyright © 2002-2013 Atlassian. All Rights Reserved.