com.jauntium

Class Element

java.lang.Object

com.jauntium.Element

All Implemented Interfaces:

Iterable<Element>, org.openqa.selenium.SearchContext, org.openqa.selenium.TakesScreenshot, org.openqa.selenium.WebElement

Direct Known Subclasses:

Document

public class Element
extends Object
implements org.openqa.selenium.WebElement, Iterable<Element>

Represents an HTML Element; this class implements WebElement and providing additional convenience methods for searching using tagQuery syntax as well as accessing attributes, proximal elements, and text children. An HTML element has an element name (ie the tagname) and may contain attributes (<elementName attributename='attributeValue'>). Elements typically form a tree structure, where an element may also have one or more children (which can be other Elements, or Nodes such as text, comments, etc), and has a single parent. When two elements share the same parent, they are said to be sibling elements with respect to each other. The term "ancestor" refers to any element that rests at or above the level of the element's parent, and the term "descendant" refers to any element at or beneath the level of the element's child/children.

Author:

Tom Cervenka

Method Summary

Modifier and Type	Method and Description
void	clear()
void	click()
Elements	findEach(String query) Searches descendant elements and retrieves elements that were found to match the query, however for every matching element is found, the search does not continue into that element's descendants.
org.openqa.selenium.WebElement	findElement(org.openqa.selenium.By by)
List<org.openqa.selenium.WebElement>	findElements(org.openqa.selenium.By arg0)
Elements	findEvery(String query) Searches all descendant elements and retrieves all elements that were found to match the query.
Element	findFirst(String query) Searches all descendant elements and retrieves the first one found to match the query.
String	getAt(String attributeName) Returns the attribute value for the specified (case insensitive) attribute name and throws a NotFound Exception if no such attribute name exists or if the attribute value is null; relative URLs are expanded into absolute URLs.
String	getAtStr(String attributeName) Returns the attribute value for the specified (case insensitive) attribute name and returns an empty String no such attribute name exists or if no value exists for the specified attribute name; relative URLs are expanded into absolute URLs.
String	getAttribute(String name) Returns the value for the specified (case insensitive) attribute name OR property name, which may be a null value; all relative URLS are expanded to absolute URLS before being returned.
List<String>	getAttributeNames() Retrieves a list of the attribute names.
List<Element>	getChildElements() Returns a list of child Elements, or an empty list if no child elements exist.
List<Node>	getChildNodes() Returns a list of child nodes, or an empty list if no child nodes exist.
String	getChildText() Returns a concatenation of all immediate child text nodes (whether or not they are hidden by CSS), or returns an empty String if none exist.
String	getChildText(String separator, boolean collapseWhitespace) Returns a concatenation of all immediate child text nodes (whether or not they are hidden by CSS), or returns an empty String if none exist.
String	getCssValue(String arg0)
Elements	getEach(String query) Searches child elements (not all descendants) and retrieves those that were found to match the query.
Element	getElement(int index) Returns the child element at the position denoted by the specified index.
Element	getFirst(String query) Searches only child elements (not all descendants) and retrieves the first child element that was found to match the query.
org.openqa.selenium.Point	getLocation()
Element	getParent() Returns the parent element or null if a parent element does not exist.
org.openqa.selenium.Rectangle	getRect()
Element	getRoot() Return the ancestor Element who's parent is null (ie, the root element).
<X> X	getScreenshotAs(org.openqa.selenium.OutputType<X> arg0)
org.openqa.selenium.Dimension	getSize()
String	getTagName()
String	getText() Returns the concatentation of all visible text within this element, including all the visible text of all descendants; text that is not visible due to CSS rules is excluded.
String	getTextContent()
String	getTextContent(String separator, boolean includeComments, boolean includeScripts)
String	innerHTML() Returns a String representation of this element's children/descendant nodes as HTML.
String	innerHTML(int indent)
void	innerHTML(String html) Replaces the contents of this element (ie the descendant nodes) with the specified HTML.
boolean	isDisplayed()
boolean	isEnabled()
boolean	isSelected()
Iterator<Element>	iterator() Returns an iterator over the child elements.
Element	nextElementSibling() Returns the next element that is a sibling (shares the same parent), or null if none exists.
Node	nextNodeSibling() Returns the next node that is a sibling (shares the name parent) or returns null if no such sibling exists.
String	outerHTML() Returns an HTML representation of this element (including its children/descendant nodes).
String	outerHTML(int indent)
void	outerHTML(String html) Replaces this element and its descendants in the DOM with the specified HTML.
Element	previousElementSibling() Returns the previous element that is a sibling (shares the same parent), or null if none exists.
Node	previousNodeSibling() Returns the previous node that is a sibling (shares the name parent) or returns null if no such sibling exists.
void	remove() Removes this element (and its descendants) from the DOM.
void	removeAttribute(String attName) Removes the attribute that has the specified attribute name.
void	sendKeys(CharSequence... arg0)
void	setAttribute(String attName, String attValue) Sets the attribute of the specified name to the specified value.
void	submit()
Node	toNode() Returns this element cast to type Node.
String	toString() Returns a string representation of this element as an HTML tag, not including children or its counterpart closing tag.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

findEvery

public Elements findEvery(String query)

Searches all descendant elements and retrieves all elements that were found to match the query.

Parameters:

query - a query that has the general form <tagnameRegex attributeName="attributeValueRegex">childTextRegex where multiple attributes are allowed. In order for the query to match against an element, the tagnameRegex, attribute name, attributeValueRegex and immediateTextRegex must match if they are specified.
tagnameRegex: If tagnameRegex is a whitespace character, it will match any tagname. Otherwise, the tagnameRegex will be treated as case-insensitive and be evaluated against entire tagnames (ie will not match substrings). The tagnameRegex must begin with either an alphabetical character or a round opening bracket, and may not contain whitespace (though it may contain \\s, which matches whitespace)
attributeName: If no attributes are included in the query, the query will match any attributes in a candidate element (including one without attributes). Otherwise, the attributeName in the query is matched as a case-insensitive string, not as a regular expression.
attributeValueRegex: If attributeValueRegex is not present, the attributeName in the query will be matched against candidate attributeNames irrespective of their attributeValues. If attributeValueRegex is present, it will be treated as case-insensitive and be evaluated against the entire corresponding attribute value (ie will not match substrings).
childTextRegex: If childTextRegex is not present, the query will match any child text (including lack of text). Otherwise, childTextRegex will be evaluated against the concatenation of Text children of the Element (ie, not the concatenation of all Text descendants, just children). It's important to note that childTextRegex is case sensitive and by default does match against substrings since it uses Matcher.find().

Returns:

a container of type Elements who's children are the elements that were found by the search.

findEach

public Elements findEach(String query)

Searches descendant elements and retrieves elements that were found to match the query, however for every matching element is found, the search does not continue into that element's descendants.

Parameters:

query - a query that has the general form <tagnameRegex attributeName="attributeValueRegex">childTextRegex where multiple attributes are allowed. In order for the query to match against an element, the tagnameRegex, attribute name, attributeValueRegex and immediateTextRegex must match if they are specified.
tagnameRegex: If tagnameRegex is a whitespace character, it will match any tagname. Otherwise, the tagnameRegex will be treated as case-insensitive and be evaluated against entire tagnames (ie will not match substrings). The tagnameRegex must begin with either an alphabetical character or a round opening bracket, and may not contain whitespace (though it may contain \\s, which matches whitespace)
attributeName: If no attributes are included in the query, the query will match any attributes in a candidate element (including one without attributes). Otherwise, the attributeName in the query is matched as a case-insensitive string, not as a regular expression.
attributeValueRegex: If attributeValueRegex is not present, the attributeName in the query will be matched against candidate attributeNames irrespective of their attributeValues. If attributeValueRegex is present, it will be treated as case-insensitive and be evaluated against the entire corresponding attribute value (ie will not match substrings).
childTextRegex: If childTextRegex is not present, the query will match any child text (including lack of text). Otherwise, childTextRegex will be evaluated against the concatenation of Text children of the Element (ie, not the concatenation of all Text descendants, just children). It's important to note that childTextRegex is case sensitive and by default does match against substrings since it uses Matcher.find().

Returns:

a container of type Elements holding the elements that were found by the search.

getEach

public Elements getEach(String query)

Searches child elements (not all descendants) and retrieves those that were found to match the query.

Parameters:

query - a query that has the general form <tagnameRegex attributeName="attributeValueRegex">childTextRegex where multiple attributes are allowed. In order for the query to match against an element, the tagnameRegex, attribute name, attributeValueRegex and immediateTextRegex must match if they are specified.
tagnameRegex: If tagnameRegex is a whitespace character, it will match any tagname. Otherwise, the tagnameRegex will be treated as case-insensitive and be evaluated against entire tagnames (ie will not match substrings). The tagnameRegex must begin with either an alphabetical character or a round opening bracket, and may not contain whitespace (though it may contain \\s, which matches whitespace)
attributeName: If no attributes are included in the query, the query will match any attributes in a candidate element (including one without attributes). Otherwise, the attributeName in the query is matched as a case-insensitive string, not as a regular expression.
attributeValueRegex: If attributeValueRegex is not present, the attributeName in the query will be matched against candidate attributeNames irrespective of their attributeValues. If attributeValueRegex is present, it will be treated as case-insensitive and be evaluated against the entire corresponding attribute value (ie will not match substrings).
childTextRegex: If childTextRegex is not present, the query will match any child text (including lack of text). Otherwise, childTextRegex will be evaluated against the concatenation of Text children of the Element (ie, not the concatenation of all Text descendants, just children). It's important to note that childTextRegex is case sensitive and by default does match against substrings since it uses Matcher.find().

Returns:

a container of type Elements holding the elements that were found by the search.

findFirst

public Element findFirst(String query)
                  throws NotFound

Searches all descendant elements and retrieves the first one found to match the query.

Parameters:

query - a query that has the general form <tagnameRegex attributeName="attributeValueRegex">childTextRegex where multiple attributes are allowed. In order for the query to match against an element, the tagnameRegex, attribute name, attributeValueRegex and immediateTextRegex must match if they are specified.
tagnameRegex: If tagnameRegex is a whitespace character, it will match any tagname. Otherwise, the tagnameRegex will be treated as case-insensitive and be evaluated against entire tagnames (ie will not match substrings). The tagnameRegex must begin with either an alphabetical character or a round opening bracket, and may not contain whitespace (though it may contain \\s, which matches whitespace)
attributeName: If no attributes are included in the query, the query will match any attributes in a candidate element (including one without attributes). Otherwise, the attributeName in the query is matched as a case-insensitive string, not as a regular expression.
attributeValueRegex: If attributeValueRegex is not present, the attributeName in the query will be matched against candidate attributeNames irrespective of their attributeValues. If attributeValueRegex is present, it will be treated as case-insensitive and be evaluated against the entire corresponding attribute value (ie will not match substrings).
childTextRegex: If childTextRegex is not present, the query will match any child text (including lack of text). Otherwise, childTextRegex will be evaluated against the concatenation of Text children of the Element (ie, not the concatenation of all Text descendants, just children). It's important to note that childTextRegex is case sensitive and by default does match against substrings since it uses Matcher.find().

Returns:

first child that matches the specified parameters, or throws a NotFound Exception if one is not found.

Throws:

NotFound

getFirst

public Element getFirst(String query)
                 throws NotFound

Searches only child elements (not all descendants) and retrieves the first child element that was found to match the query.

Parameters:

query - a query that has the general form <tagnameRegex attributeName="attributeValueRegex">childTextRegex where multiple attributes are allowed. In order for the query to match against an element, the tagnameRegex, attribute name, attributeValueRegex and immediateTextRegex must match if they are specified.
tagnameRegex: If tagnameRegex is a whitespace character, it will match any tagname. Otherwise, the tagnameRegex will be treated as case-insensitive and be evaluated against entire tagnames (ie will not match substrings). The tagnameRegex must begin with either an alphabetical character or a round opening bracket, and may not contain whitespace (though it may contain \\s, which matches whitespace)
attributeName: If no attributes are included in the query, the query will match any attributes in a candidate element (including one without attributes). Otherwise, the attributeName in the query is matched as a case-insensitive string, not as a regular expression.
attributeValueRegex: If attributeValueRegex is not present, the attributeName in the query will be matched against candidate attributeNames irrespective of their attributeValues. If attributeValueRegex is present, it will be treated as case-insensitive and be evaluated against the entire corresponding attribute value (ie will not match substrings).
childTextRegex: If childTextRegex is not present, the query will match any child text (including lack of text). Otherwise, childTextRegex will be evaluated against the concatenation of Text children of the Element (ie, not the concatenation of all Text descendants, just children). It's important to note that childTextRegex is case sensitive and by default does match against substrings since it uses Matcher.find().

Returns:

first child that matches the query, or throws a NotFound Exception if one is not found.

Throws:

NotFound

clear

public void clear()

Specified by:

clear in interface org.openqa.selenium.WebElement

See Also:

WebElement.clear()

click

public void click()

Specified by:

click in interface org.openqa.selenium.WebElement

See Also:

WebElement.click()

findElement

public org.openqa.selenium.WebElement findElement(org.openqa.selenium.By by)

Specified by:

findElement in interface org.openqa.selenium.SearchContext

Specified by:

findElement in interface org.openqa.selenium.WebElement

See Also:

WebElement.findElement(By)

getAttributeNames

public List<String> getAttributeNames()

Retrieves a list of the attribute names.

Returns:

a list containing the attribute names in lowercase.

getAttribute

public String getAttribute(String name)

Returns the value for the specified (case insensitive) attribute name OR property name, which may be a null value; all relative URLS are expanded to absolute URLS before being returned.

Specified by:

getAttribute in interface org.openqa.selenium.WebElement

See Also:

WebElement.getAttribute(String)

getAt

public String getAt(String attributeName)
             throws NotFound

Returns the attribute value for the specified (case insensitive) attribute name and throws a NotFound Exception if no such attribute name exists or if the attribute value is null; relative URLs are expanded into absolute URLs.

Parameters:

attributeName - case insensitive attribute name.

Throws:

NotFound

getAtStr

public String getAtStr(String attributeName)

Returns the attribute value for the specified (case insensitive) attribute name and returns an empty String no such attribute name exists or if no value exists for the specified attribute name; relative URLs are expanded into absolute URLs.

Parameters:

attributeName - case insensitive attribute name.

getScreenshotAs

public <X> X getScreenshotAs(org.openqa.selenium.OutputType<X> arg0)
                      throws org.openqa.selenium.WebDriverException

Specified by:

getScreenshotAs in interface org.openqa.selenium.TakesScreenshot

Throws:

org.openqa.selenium.WebDriverException

See Also:

TakesScreenshot.getScreenshotAs(OutputType)

findElements

public List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By arg0)

Specified by:

findElements in interface org.openqa.selenium.SearchContext

Specified by:

findElements in interface org.openqa.selenium.WebElement

See Also:

WebElement.findElements(By)

getCssValue

public String getCssValue(String arg0)

Specified by:

getCssValue in interface org.openqa.selenium.WebElement

See Also:

WebElement.getCssValue(String)

getLocation

public org.openqa.selenium.Point getLocation()

Specified by:

getLocation in interface org.openqa.selenium.WebElement

See Also:

WebElement.getLocation()

getRect

public org.openqa.selenium.Rectangle getRect()

Specified by:

getRect in interface org.openqa.selenium.WebElement

See Also:

WebElement.getRect()

getSize

public org.openqa.selenium.Dimension getSize()

Specified by:

getSize in interface org.openqa.selenium.WebElement

See Also:

WebElement.getSize()

getTagName

public String getTagName()

Specified by:

getTagName in interface org.openqa.selenium.WebElement

See Also:

WebElement.getTagName()

getText

public String getText()

Returns the concatentation of all visible text within this element, including all the visible text of all descendants; text that is not visible due to CSS rules is excluded.

Specified by:

getText in interface org.openqa.selenium.WebElement

See Also:

WebElement.getText()

getChildText

public String getChildText()

Returns a concatenation of all immediate child text nodes (whether or not they are hidden by CSS), or returns an empty String if none exist.

Returns:

immediate child text nodes as a String.

getChildText

public String getChildText(String separator,
                           boolean collapseWhitespace)

Returns a concatenation of all immediate child text nodes (whether or not they are hidden by CSS), or returns an empty String if none exist.

Parameters:

separator - the separator to use between each text node when they are joined.

collapseWhitespace - whether multiple adjacent whitespace characters should be collapsed into a single whitespace

Returns:

immediate child text nodes joined together as a single string.

getTextContent

public String getTextContent()

getTextContent

public String getTextContent(String separator,
                             boolean includeComments,
                             boolean includeScripts)

isDisplayed

public boolean isDisplayed()

Specified by:

isDisplayed in interface org.openqa.selenium.WebElement

See Also:

WebElement.isDisplayed()

isEnabled

public boolean isEnabled()

Specified by:

isEnabled in interface org.openqa.selenium.WebElement

See Also:

WebElement.isEnabled()

isSelected

public boolean isSelected()

Specified by:

isSelected in interface org.openqa.selenium.WebElement

See Also:

WebElement.isSelected()

sendKeys

public void sendKeys(CharSequence... arg0)

Specified by:

sendKeys in interface org.openqa.selenium.WebElement

See Also:

WebElement.sendKeys(CharSequence...)

submit

public void submit()

Specified by:

submit in interface org.openqa.selenium.WebElement

See Also:

WebElement.submit()

toString

public String toString()

Returns a string representation of this element as an HTML tag, not including children or its counterpart closing tag.

Overrides:

toString in class Object

innerHTML

public void innerHTML(String html)

Replaces the contents of this element (ie the descendant nodes) with the specified HTML.

Parameters:

html - html content to be inserted as a child or children to this element.

innerHTML

public String innerHTML()

Returns a String representation of this element's children/descendant nodes as HTML.

innerHTML

public String innerHTML(int indent)

outerHTML

public String outerHTML()

Returns an HTML representation of this element (including its children/descendant nodes).

outerHTML

public String outerHTML(int indent)

outerHTML

public void outerHTML(String html)

Replaces this element and its descendants in the DOM with the specified HTML.

Parameters:

html - html content to be inserted in place of this element.

getElement

public Element getElement(int index)
                   throws ArrayIndexOutOfBoundsException

Returns the child element at the position denoted by the specified index.

Parameters:

index - the index of the child element, where the first child has index 0.

Throws:

ArrayIndexOutOfBoundsException

getParent

public Element getParent()

Returns the parent element or null if a parent element does not exist.

nextElementSibling

public Element nextElementSibling()

Returns the next element that is a sibling (shares the same parent), or null if none exists.

previousElementSibling

public Element previousElementSibling()

Returns the previous element that is a sibling (shares the same parent), or null if none exists.

remove

public void remove()

Removes this element (and its descendants) from the DOM.

getRoot

public Element getRoot()

Return the ancestor Element who's parent is null (ie, the root element).

getChildElements

public List<Element> getChildElements()

Returns a list of child Elements, or an empty list if no child elements exist.

iterator

public Iterator<Element> iterator()

Returns an iterator over the child elements.

Specified by:

iterator in interface Iterable<Element>

setAttribute

public void setAttribute(String attName,
                         String attValue)

Sets the attribute of the specified name to the specified value.

Parameters:

attName - the name of the target attribute.

attValue - the value to set for the attribute.

removeAttribute

public void removeAttribute(String attName)

Removes the attribute that has the specified attribute name.

toNode

public Node toNode()

Returns this element cast to type Node.

nextNodeSibling

public Node nextNodeSibling()

Returns the next node that is a sibling (shares the name parent) or returns null if no such sibling exists.

previousNodeSibling

public Node previousNodeSibling()

Returns the previous node that is a sibling (shares the name parent) or returns null if no such sibling exists.

getChildNodes

public List<Node> getChildNodes()

Returns a list of child nodes, or an empty list if no child nodes exist.