Package 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

    Modifier and Type
    Method
    Description
    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 Details

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