Package com.xceptance.xlt.api.util

# Class HtmlPageUtils

java.lang.Object
com.xceptance.xlt.api.util.BasicPageUtils
com.xceptance.xlt.api.util.HtmlPageUtils

public class HtmlPageUtils extends BasicPageUtils
The `HtmlPageUtils` class provides some useful helper methods to make dealing with `HtmlPage` objects easier. When using the plain HtmlUnit API, similar pieces of code have to be written again and again. Using this class, test case actions are often shorter and easier to understand.

See Also:
  - `AbstractHtmlPageAction`
  - `LightweightHtmlPageUtils`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HtmlPageUtils()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `checkRadioButton(HtmlForm form, String radioButtonName, int index)`
  Checks the HTML radio button input element with the given name and index in the specified form.
  `static void`
  `checkRadioButton(HtmlForm form, String radioButtonName, String value)`
  Checks the HTML radio button input element with the given name and value in the specified form.
  `static void`
  `checkRadioButtonRandomly(HtmlForm form, String radioButtonName)`
  Checks one of the radio buttons with the given name in the specified form.
  `static void`
  `checkRadioButtonRandomly(HtmlForm form, String radioButtonName, boolean excludeFirst, boolean excludeLast)`
  Checks one of the radio buttons with the given name in the specified form.
  `static int`
  `countElementsByXPath(HtmlPage page, String xpath)`
  Returns the number of elements that match the given XPath expression.
  `static <T extends HtmlElement>
  T`
  `createHtmlElement(String tagName, HtmlElement parent)`
  Creates a new HTML element with the specified tag name and adds it as a child to the given parent element.
  `static HtmlInput`
  `createInput(HtmlForm form, String type, String name, String value)`
  Creates a new input HTML element, initializes it with the specified type, name, and value, and inserts it to the given form.
  `static <T extends HtmlElement>
  List<T>`
  `findHtmlElements(HtmlElement element, String xpath)`
  Finds HTML elements using the given XPath expression within the specified HTML element.
  `static <T extends HtmlElement>
  List<T>`
  `findHtmlElements(HtmlPage page, String xpath)`
  Finds HTML elements using the given XPath expression on the specified page.
  `static <T extends HtmlElement>
  T`
  `findHtmlElementsAndPickOne(HtmlElement element, String xpath)`
  Finds HTML elements using the given XPath expression within the specified HTML element, selects one of them randomly and returns it.
  `static <T extends HtmlElement>
  T`
  `findHtmlElementsAndPickOne(HtmlElement element, String xpath, boolean excludeFirst)`
  Finds HTML elements using the given XPath expression within the specified HTML element, selects one of them randomly and returns it.
  `static <T extends HtmlElement>
  T`
  `findHtmlElementsAndPickOne(HtmlElement element, String xpath, boolean excludeFirst, boolean excludeLast)`
  Finds HTML elements using the given XPath expression within the specified HTML element, selects one of them randomly and returns it.
  `static <T> T`
  `findHtmlElementsAndPickOne(HtmlPage page, String xpath)`
  Finds HTML elements using the given XPath expression on the specified page, selects one of them randomly and returns it.
  `static <T> T`
  `findHtmlElementsAndPickOne(HtmlPage page, String xpath, boolean excludeFirst)`
  Finds HTML elements using the given XPath expression on the specified page, selects one of them randomly and returns it.
  `static <T extends HtmlElement>
  T`
  `findHtmlElementsAndPickOne(HtmlPage page, String xpath, boolean excludeFirst, boolean excludeLast)`
  Finds HTML elements using the given XPath expression on the specified page, selects one of them randomly and returns it.
  `static <T extends HtmlElement>
  T`
  `findSingleHtmlElementByID(HtmlPage page, String id)`
  Finds the HTML element with the given ID on the specified page.
  `static <T extends HtmlElement>
  T`
  `findSingleHtmlElementByXPath(HtmlElement element, String xpath)`
  Finds a single HTML elements using the given XPath expression within the specified HTML element.
  `static <T extends HtmlElement>
  T`
  `findSingleHtmlElementByXPath(HtmlPage page, String xpath)`
  Finds a single HTML elements using the given XPath expression on the specified page.
  `static HtmlAnchor`
  `getAnchorWithText(HtmlPage page, String anchorText)`
  Returns the HTML anchor element with the passed anchor text.
  `static List<HtmlForm>`
  `getFormsByIDRegExp(HtmlPage page, Pattern pattern)`
  Returns a list of forms the ID of which matches the given regular expression.
  `static List<HtmlForm>`
  `getFormsByNameRegExp(HtmlPage page, Pattern pattern)`
  Returns a list of forms the name of which matches the given regular expression.
  `static HtmlPage`
  `getFramePage(HtmlPage page, String... frameNames)`
  Returns the HTML page contained in a nested frame window.
  `static <T extends HtmlInput>
  T`
  `getInputEndingWith(HtmlForm form, String suffix)`
  Returns the first input element that ends with this suffix.
  `static <T extends HtmlInput>
  T`
  `getInputStartingWith(HtmlForm form, String prefix)`
  Returns the first input element that starts with this prefix.
  `static HtmlSelect`
  `getSelectEndingWith(HtmlForm form, String suffix)`
  Returns the first select element that ends with this suffix.
  `static HtmlSelect`
  `getSelectStartingWith(HtmlForm form, String prefix)`
  Returns the first select element that starts with this prefix.
  `static boolean`
  `isElementPresent(HtmlElement element, String xpath)`
  Returns whether or not a HTML element exists for the given XPath expression.
  `static boolean`
  `isElementPresent(HtmlPage page, String xpath)`
  Returns whether or not a HTML element exists for the given XPath expression.
  `static void`
  `select(HtmlForm form, String selectName, String optionValue)`
  Finds the HTML select element with the given name in the specified form and selects the option with the passed value.
  `static void`
  `selectRandomly(HtmlForm form, String selectName)`
  Finds the HTML select element with the given name in the specified form and selects one of the options randomly.
  `static void`
  `selectRandomly(HtmlForm form, String selectName, boolean excludeFirst)`
  Finds the HTML select element with the given name in the specified form and selects one of the options randomly.
  `static void`
  `selectRandomly(HtmlForm form, String selectName, boolean excludeFirst, boolean excludeLast)`
  Finds the HTML select element with the given name in the specified form and set one of the options selected randomly.
  `static void`
  `setCheckBoxValue(HtmlForm form, String checkBoxName, boolean isChecked)`
  Finds the HTML check box input element with the given name in the specified form and sets its value.
  `static void`
  `setInputValue(HtmlForm form, String inputName, String value)`
  Finds the HTML input element with the given name in the specified form and sets its value.
  `static <T extends HtmlElement>
  List<T>`
  `waitForHtmlElements(HtmlPage page, String xpath, long timeout)`
  Waits until at least one HTML element can be located on the given page using the specified XPath expression and returns the list of matching elements.

  ### Methods inherited from class com.xceptance.xlt.api.util.BasicPageUtils

  `getAbsoluteUrl, getAbsoluteUrl, pickOneRandomly, pickOneRandomly, pickOneRandomly`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### HtmlPageUtils

    public HtmlPageUtils()

- ## Method Details

  - ### checkRadioButton

    public static void checkRadioButton(HtmlForm form, String radioButtonName, int index)
    Checks the HTML radio button input element with the given name and index in the specified form. All other radio buttons with the same name are left unchecked.
    Parameters:
      `form` - the form with the radio buttons
      `radioButtonName` - the name of the radio button group
      `index` - the index of the radio button to check (starts with 0)

  - ### checkRadioButton

    public static void checkRadioButton(HtmlForm form, String radioButtonName, String value)
    Checks the HTML radio button input element with the given name and value in the specified form. All other radio buttons with the same name are left unchecked.
    Parameters:
      `form` - the form with the radio buttons
      `radioButtonName` - the name of the radio button group
      `value` - the value of the radio button to check

  - ### checkRadioButtonRandomly

    public static void checkRadioButtonRandomly(HtmlForm form, String radioButtonName)
    Checks one of the radio buttons with the given name in the specified form. All other radio buttons with the same name are left unchecked.
    Parameters:
      `form` - the form with the radio buttons
      `radioButtonName` - the name of the radio button group

  - ### checkRadioButtonRandomly

    public static void checkRadioButtonRandomly(HtmlForm form, String radioButtonName, boolean excludeFirst, boolean excludeLast)
    Checks one of the radio buttons with the given name in the specified form. All other radio buttons with the same name are unchecked.
    Parameters:
      `form` - the form with the radio buttons
      `radioButtonName` - the name of the radio button group
      `excludeFirst` - whether to exclude the first radio button in the group
      `excludeLast` - whether to exclude the last radio button in the group

  - ### createHtmlElement

    public static <T extends HtmlElement> T createHtmlElement(String tagName, HtmlElement parent)
    Creates a new HTML element with the specified tag name and adds it as a child to the given parent element.

    Note that input elements should be created using `createInput(HtmlForm, String, String, String)`.

    Parameters:
      `tagName` - the tag name
      `parent` - the parent
    Returns:
      the HTML element just created

  - ### createInput

    public static HtmlInput createInput(HtmlForm form, String type, String name, String value)
    Creates a new input HTML element, initializes it with the specified type, name, and value, and inserts it to the given form.
    Parameters:
      `form` - the form
      `type` - the type
      `name` - the name
      `value` - the value
    Returns:
      the input element just created

  - ### findHtmlElements

    public static <T extends HtmlElement> List<T> findHtmlElements(HtmlPage page, String xpath)
    Finds HTML elements using the given XPath expression on the specified page.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `page` - the page to search
      `xpath` - the XPath expression specifying the elements
    Returns:
      the list of elements found
    Throws:
      `AssertionError` - if no elements were found

  - ### findHtmlElementsAndPickOne

    public static <T> T findHtmlElementsAndPickOne(HtmlPage page, String xpath)
    Finds HTML elements using the given XPath expression on the specified page, selects one of them randomly and returns it.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `page` - the page to search
      `xpath` - the XPath expression specifying the elements
    Returns:
      the list of elements found
    Throws:
      `AssertionError` - if no elements were found

  - ### findHtmlElementsAndPickOne

    public static <T> T findHtmlElementsAndPickOne(HtmlPage page, String xpath, boolean excludeFirst)
    Finds HTML elements using the given XPath expression on the specified page, selects one of them randomly and returns it.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `page` - the page to search
      `xpath` - the XPath expression specifying the elements
      `excludeFirst` - whether to exclude the first element found
    Returns:
      the list of elements found
    Throws:
      `AssertionError` - if no elements were found

  - ### findHtmlElementsAndPickOne

    public static <T extends HtmlElement> T findHtmlElementsAndPickOne(HtmlPage page, String xpath, boolean excludeFirst, boolean excludeLast)
    Finds HTML elements using the given XPath expression on the specified page, selects one of them randomly and returns it.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `page` - the page to search
      `xpath` - the XPath expression specifying the elements
      `excludeFirst` - whether to exclude the first element found
      `excludeLast` - whether to exclude the last element found
    Returns:
      the list of elements found
    Throws:
      `AssertionError` - if no elements were found

  - ### findSingleHtmlElementByID

    public static <T extends HtmlElement> T findSingleHtmlElementByID(HtmlPage page, String id)
    Finds the HTML element with the given ID on the specified page.
    Type Parameters:
      `T` - the expected type of the element found
    Parameters:
      `page` - the page to search
      `id` - the ID of the element
    Returns:
      the element found
    Throws:
      `AssertionError` - if no or more than one element with this ID was found

  - ### findSingleHtmlElementByXPath

    public static <T extends HtmlElement> T findSingleHtmlElementByXPath(HtmlPage page, String xpath)
    Finds a single HTML elements using the given XPath expression on the specified page.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `page` - the page to search
      `xpath` - the XPath expression specifying the elements
    Returns:
      the element found
    Throws:
      `AssertionError` - if no or more than one element was found

  - ### findHtmlElements

    public static <T extends HtmlElement> List<T> findHtmlElements(HtmlElement element, String xpath)
    Finds HTML elements using the given XPath expression within the specified HTML element.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `element` - the HTML element to search
      `xpath` - the XPath expression specifying the elements (must not contain leading slash)
    Returns:
      the list of elements found
    Throws:
      `AssertionError` - if no elements were found

  - ### findHtmlElementsAndPickOne

    public static <T extends HtmlElement> T findHtmlElementsAndPickOne(HtmlElement element, String xpath)
    Finds HTML elements using the given XPath expression within the specified HTML element, selects one of them randomly and returns it.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `element` - the HTML element to search
      `xpath` - the XPath expression specifying the elements
    Returns:
      the list of elements found
    Throws:
      `AssertionError` - if no elements were found

  - ### findHtmlElementsAndPickOne

    public static <T extends HtmlElement> T findHtmlElementsAndPickOne(HtmlElement element, String xpath, boolean excludeFirst)
    Finds HTML elements using the given XPath expression within the specified HTML element, selects one of them randomly and returns it.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `element` - the HTML element to search
      `xpath` - the XPath expression specifying the elements
      `excludeFirst` - whether to exclude the first element found
    Returns:
      the list of elements found
    Throws:
      `AssertionError` - if no elements were found

  - ### findHtmlElementsAndPickOne

    public static <T extends HtmlElement> T findHtmlElementsAndPickOne(HtmlElement element, String xpath, boolean excludeFirst, boolean excludeLast)
    Finds HTML elements using the given XPath expression within the specified HTML element, selects one of them randomly and returns it.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `element` - the HTML element to search
      `xpath` - the XPath expression specifying the elements
      `excludeFirst` - whether to exclude the first element found
      `excludeLast` - whether to exclude the last element found
    Returns:
      the list of elements found
    Throws:
      `AssertionError` - if no elements were found

  - ### findSingleHtmlElementByXPath

    public static <T extends HtmlElement> T findSingleHtmlElementByXPath(HtmlElement element, String xpath)
    Finds a single HTML elements using the given XPath expression within the specified HTML element.
    Type Parameters:
      `T` - the expected type of the elements found
    Parameters:
      `element` - the HTML element to search
      `xpath` - the XPath expression specifying the elements
    Returns:
      the element found
    Throws:
      `AssertionError` - if no or more than one element was found

  - ### getAnchorWithText

    public static HtmlAnchor getAnchorWithText(HtmlPage page, String anchorText)
    Returns the HTML anchor element with the passed anchor text.
    Parameters:
      `page` - the page to search
      `anchorText` - the anchor text
    Returns:
      the anchor found
    Throws:
      `AssertionError` - if no or more than one anchor was found

  - ### getFramePage

    public static HtmlPage getFramePage(HtmlPage page, String... frameNames)
    Returns the HTML page contained in a nested frame window. The path to the respective frame is given as an array of frame names, starting with the name of the outermost frame.
    Parameters:
      `page` - the page to search
      `frameNames` - the list of frame names
    Returns:
      the frame page found
    Throws:
      `ElementNotFoundException` - if there is no frame with the given name at the respective nesting level

  - ### getInputEndingWith

    public static <T extends HtmlInput> T getInputEndingWith(HtmlForm form, String suffix)
    Returns the first input element that ends with this suffix.
    Parameters:
      `form` - the form to use
      `suffix` - the suffix of the input elements to search
    Returns:
      the first found input element or null otherwise

  - ### getInputStartingWith

    public static <T extends HtmlInput> T getInputStartingWith(HtmlForm form, String prefix)
    Returns the first input element that starts with this prefix.
    Parameters:
      `form` - the form to use
      `prefix` - the prefix of the input elements to search
    Returns:
      the first found input element or null otherwise

  - ### getSelectEndingWith

    public static HtmlSelect getSelectEndingWith(HtmlForm form, String suffix)
    Returns the first select element that ends with this suffix.
    Parameters:
      `form` - the form to use
      `suffix` - the suffix of the select elements to search
    Returns:
      the first found select element or null otherwise

  - ### getSelectStartingWith

    public static HtmlSelect getSelectStartingWith(HtmlForm form, String prefix)
    Returns the first select element that starts with this prefix.
    Parameters:
      `form` - the form to use
      `prefix` - the prefix of the select elements to search
    Returns:
      the first found select element or null otherwise

  - ### select

    public static void select(HtmlForm form, String selectName, String optionValue)
    Finds the HTML select element with the given name in the specified form and selects the option with the passed value.
    Parameters:
      `form` - the form to search
      `selectName` - the name of the select element
      `optionValue` - the value of the option element to select

  - ### selectRandomly

    public static void selectRandomly(HtmlForm form, String selectName)
    Finds the HTML select element with the given name in the specified form and selects one of the options randomly.
    Parameters:
      `form` - the form to search
      `selectName` - the name of the select element

  - ### selectRandomly

    public static void selectRandomly(HtmlForm form, String selectName, boolean excludeFirst)
    Finds the HTML select element with the given name in the specified form and selects one of the options randomly.
    Parameters:
      `form` - the form to search
      `selectName` - the name of the select element
      `excludeFirst` - whether to exclude the first option element

  - ### selectRandomly

    public static void selectRandomly(HtmlForm form, String selectName, boolean excludeFirst, boolean excludeLast)
    Finds the HTML select element with the given name in the specified form and set one of the options selected randomly. Disabled option will be ignored.
    Parameters:
      `form` - the form to search
      `selectName` - the name of the select element
      `excludeFirst` - whether to exclude the first option element
      `excludeLast` - whether to exclude the last option element

  - ### setCheckBoxValue

    public static void setCheckBoxValue(HtmlForm form, String checkBoxName, boolean isChecked)
    Finds the HTML check box input element with the given name in the specified form and sets its value.
    Parameters:
      `form` - the form to search
      `checkBoxName` - the name of the check box
      `isChecked` - the new check box value

  - ### setInputValue

    public static void setInputValue(HtmlForm form, String inputName, String value)
    Finds the HTML input element with the given name in the specified form and sets its value.
    Parameters:
      `form` - the form to search
      `inputName` - the name of the input element
      `value` - the new value

  - ### getFormsByIDRegExp

    public static List<HtmlForm> getFormsByIDRegExp(HtmlPage page, Pattern pattern)
    Returns a list of forms the ID of which matches the given regular expression.
    Parameters:
      `page` - the page to search
      `pattern` - the regex pattern to match the form ID
    Returns:
      the list of forms found

  - ### getFormsByNameRegExp

    public static List<HtmlForm> getFormsByNameRegExp(HtmlPage page, Pattern pattern)
    Returns a list of forms the name of which matches the given regular expression.
    Parameters:
      `page` - the page to search
      `pattern` - the regex pattern to match the form name
    Returns:
      the list of forms found

  - ### isElementPresent

    public static boolean isElementPresent(HtmlPage page, String xpath)
    Returns whether or not a HTML element exists for the given XPath expression.
    Parameters:
      `page` - the HTML page
      `xpath` - the XPath expression
    Returns:
      `true` if at least one HTML element matches the given XPath expression, `false` otherwise

  - ### isElementPresent

    public static boolean isElementPresent(HtmlElement element, String xpath)
    Returns whether or not a HTML element exists for the given XPath expression.
    Parameters:
      `element` - the HTML element
      `xpath` - the XPath expression
    Returns:
      `true` if at least one HTML element matches the given XPath expression, `false` otherwise

  - ### countElementsByXPath

    public static int countElementsByXPath(HtmlPage page, String xpath)
    Returns the number of elements that match the given XPath expression.
    Parameters:
      `page` - the HTML page
      `xpath` - the XPath expression
    Returns:
      number of matching elements

  - ### waitForHtmlElements

    public static <T extends HtmlElement> List<T> waitForHtmlElements(HtmlPage page, String xpath, long timeout) throws InterruptedException
    Waits until at least one HTML element can be located on the given page using the specified XPath expression and returns the list of matching elements. If the waiting time exceeds the given timeout value, an `AssertionError` is thrown. This method can be used to wait for HTML elements that appear on the page only after some JavaScript code has finished to run.
    Parameters:
      `page` - the HTML page
      `xpath` - the XPath expression
      `timeout` - the timeout value [ms]
    Returns:
      the list of matching elements
    Throws:
      `InterruptedException` - if the current thread is interrupted while sleeping
      `AssertionError` - if no elements were found in the given time period