com.atlassian.jira.functest.framework.locator
Interface Locator

All Known Implementing Classes:

AbstractLocator, AggregateLocator, CssLocator, IdLocator, NodeLocator, TableCellLocator, TableLocator, WebPageLocator, XPathLocator

public interface Locator

A Locator is responsible for "locating" DOM Node's on a web page and also getting the text of those Node's.

You use a Locator to "narrow" down the areas of a web page you want to make assertions on. So it may be a specified element with an id or a set of elements with specific class. Locator's also abstract how the text is returned for page elements. So it may include markup text or it may not, that is up to the specialised type of Locator

Locator's should implement toString() in a way that is meaning full when test cases fail and you want to know in what context.

NOTE : Locator's are one shot objects. A call to getNodes() should return the same Nodes every time it is called. Even if the underlying data source has changed (for example the WebTester page has changed) the Locator MUST return the same data.

Since:

v3.13

Method Summary

Iterable<LocatorEntry>	allMatches() Get all matches of this locator as an iterable collection of locator entries
boolean	exists() Return true at least one element will be matches by this locator.
String	getHTML() Returns the HTML that a called to getNodes() represent, including the top level nodes themselves.
String	getHTML(Node node) Returns the HTML of the specified node.
Node	getNode() This convenience methods is the the equivalent of getNodes()[0] except when the number of nodes found is zero, in which case it should return null.
Node[]	getNodes() A Locator may return 0 nodes, 1 node or multiple nodes.
String	getRawText() Returns the combined raw text of the Nodes that getNodes() would return or empty string.
String	getRawText(Node node) Returns the raw text of the specified Node.
String	getText() Returns the combined collapsed text of the Nodes that getNodes() would return or empty string.
String	getText(Node node) Returns the collapsed text of the specified Node.
boolean	hasNodes() This will return true if the Locator found some Node's.
Iterator<LocatorEntry>	iterator() This will return a Iterator that returns LocatorEntry objects
String	toString() A meaningful "debugging" representation of this Locator to help when test fail.

Method Detail

exists

boolean exists()

Return true at least one element will be matches by this locator.

Returns:

true if the locator will match one element or false otherwise.

getNodes

Node[] getNodes()

A Locator may return 0 nodes, 1 node or multiple nodes.

Returns:

a non null array of Nodes that match, or a zero sized array of no matches are made

getNode

Node getNode()

This convenience methods is the the equivalent of getNodes()[0] except when the number of nodes found is zero, in which case it should return null.

Returns:

null if not nodes found or the getNodes()[0]

getText

String getText()

Returns the combined collapsed text of the Nodes that getNodes() would return or empty string.

NOTE : This text is the "COLLAPSED" text of the nodes, that is all the child Text nodes smooshed together to removed repeating whitespace.

Returns:

the text of the Nodes that the locator is designed to locate.

Throws:

RuntimeException - if something goes wrong

getText

String getText(Node node)

Returns the collapsed text of the specified Node. The node MUST be one of the nodes that a call to getNodes() would return.

NOTE : This text is the "COLLAPSED" text of the node, that is all the child Text nodes smooshed together to removed repeating whitespace.

Parameters:

node - the node that we previously returned by a call to getNodes()

Returns:

the text f the Node according to this Locator

Throws:

IllegalArgumentException - if the node is not one that would be returned by a call to getNodes()

getRawText

String getRawText()

Returns the combined raw text of the Nodes that getNodes() would return or empty string.

NOTE : This text is the "RAW" text of the nodes, that is all the child Text nodes appended together with not whitespace removal at all.

Returns:

the text of the Nodes that the locator is designed to locate.

Throws:

RuntimeException - if something goes wrong

getRawText

String getRawText(Node node)

Returns the raw text of the specified Node. The node MUST be one of the nodes that a call to getNodes() would return.

NOTE : This text is the "RAW" text of the node, that is all the child Text nodes appended together with not whitespace removal at all.

Parameters:

node - the node that we previously returned by a call to getNodes()

Returns:

the text of the Node according to this Locator

Throws:

IllegalArgumentException - if the node is not one that would be returned by a call to getNodes()

getHTML

String getHTML()

Returns the HTML that a called to getNodes() represent, including the top level nodes themselves.

Returns:

the HTML of the nodes

getHTML

String getHTML(Node node)

Returns the HTML of the specified node. The node MUST be one of the nodes that a call to getNodes() would return.

Parameters:

node - the node that we previously returned by a call to getNodes()

Returns:

the HTML of the node

iterator

Iterator<LocatorEntry> iterator()

This will return a Iterator that returns LocatorEntry objects

Returns:

a Iterator that returns LocatorEntry objects

allMatches

Iterable<LocatorEntry> allMatches()

Get all matches of this locator as an iterable collection of locator entries

Returns:

iterable collection of locator entries representing matches of this locator

hasNodes

boolean hasNodes()

This will return true if the Locator found some Node's. This is really a convenience method for getNodes().length > 0

Returns:

true if the Locator found some nodes

toString

String toString()

A meaningful "debugging" representation of this Locator to help when test fail.

Overrides:

toString in class Object

Returns:

A meaningful "debugging" representation of this Locator to help when test fail.