Summary: Methods | [Expand All]
public interface

Locator

com.atlassian.jira.functest.framework.locator.Locator
Known Indirect Subclasses

Class Overview

A Locator is responsible for "locating" DOM org.w3c.dom.Node's on a web page and also getting the text of those org.w3c.dom.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.

Summary

Public Methods
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(Node node)
Returns the raw text of the specified Node.
String getRawText()
Returns the combined raw text of the Nodes that getNodes() would return or empty string.
String getText(Node node)
Returns the collapsed text of the specified Node.
String getText()
Returns the combined collapsed text of the Nodes that getNodes() would return or empty string.
boolean hasNodes()
This will return true if the Locator found some org.w3c.dom.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.

Public Methods

public 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

public 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.

public String getHTML ()

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

Returns
  • the HTML of the nodes

public 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

public 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]

public 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

public 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 org.w3c.dom.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()

public 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 org.w3c.dom.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

public 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 org.w3c.dom.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()

public 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 org.w3c.dom.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

public boolean hasNodes ()

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

Returns
  • true if the Locator found some nodes

public Iterator<LocatorEntry> iterator ()

This will return a Iterator that returns LocatorEntry objects

Returns

public String toString ()

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

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