====== GUI HTML Adaptor ======



===== Initialization Parameters =====

  * **Url:** First url to locate when the Adaptor is created.
  * **Browser (optional):** The browser you will use in the test (e.g. IE, Chrome). Internet explorer is used by default.
  * **Validate Insert Values:** It’s indicates if the Adaptor should validate or not the values which receive the Adaptor during the execution. By default, is unchecked. The recommendation is to maintain unchecked for performance reasons. This field is very useful in special test cases, but in general it’s not necessary to use it.
  * **Full Screenshot:** If this “checkbox” is checked it will take a screenshot of all the page (not just the visible part), if its not checked, the screenshots will be just the visible part of the page.
  * **Create Selenium JSON**: clicking on this checkbox generates a .side file after the execution of the navigation.\\ \\ \\ **Mobile view parameters**\\ \\ The following parameters will only be used if you want to emulate mobile view on the browser.\\ \\ 
       *  **Device emulator**: It is used to be able to have mobile view on the execution. It allows choosing the device. If no device is chosen, there won’t be emulation, the execution will be done with the standard format. When a device is chose, the default resolution of that device will be shown on the next three fields, and the execution format will be with that resolution. This resolution can be changed manually, and are the following:\\ \\ 
             * ** Device width**
             * ** Device height**
             * ** Device zoom**\\ \\ 
       * **Horizontal mode**: Clicking on this checkbox, the execution will be done in horizontal mode (as if the phone was turned horizontal).\\ \\ 

===== Functions =====

  * **allOptionsAreSelected(Element):** Checks if all options are selected. Applies to select multiple html. Element is the input parameter here, (Element is an html element which the user can interact with, like links, inputs, checks, etc. Also there is a SearchBy input that is used to search the type of value or tag the element can have. Those tags are: ClassName, CssSelector, Id, LinkText, Name, PartialLinkText, TagName and xPath).

  * **checkbox(Element):** Ticks the checkbox in the element. The input parameter is Element, in this function, the user indicates the checkbox element that is going to be ticked, and then the function ticks it.

  * **checkRadio(Element):** Does click on the radio button option. The input parameter is Element, in this function, the user indicates the radio element that is going to be clicked, and then the function click it. 

  * **clear(Element):** Clears the value of the element. The user indicates the html element to be cleared with the input parameter (“Element”).

  * **clearAndType(Element):** Clears the value of the element and type on the value. The user indicates the html element to be cleared with the input parameter (“Element”).

  * **click(Element):** Does a mouse click on the html element. The user indicates the html element to be clicked with the input parameter (“Element”).

  * **clickAction(Element):** This PF has a similar behavior to the click() PF. However, in this case, before clicks on the control, it simulates the movement of the mouse. This behavior is mandatory in several applications.

  * **clickandHold(Element,Time):** Function that does a click and hold the element. This function collects an input parameter (element) in which you indicate where to click and another parameter to indicate the time the element will be hold (optional value). By default, the hold event will last 1 second. Also, this function takes a screenshot in the middle of time parameter. 

  * **clickByJavaScript(Element):** Click in the html element through a JavaScript execution.

  * **clickLink(Element):** Does a mouse click on the html element. Use when a new window is opened. When the application opens a new html page, we have to use clickLink because the application does not have the focus of the second html page.
 
  * **clickprint(Element):** Does click on the 'print' button of the page, with the input parameter element and the SearchBy input the function looks for the print button and then clicks it (just in case the page has one). 

  * **closeAllWindows():** Closes all the instanced adaptor windows. Do not need input parameters.  

  * **closeOthersWindows():** Close all extra open windows, leaving the main one active. Do not need input parameters.

  * **closeWindow():** Closes the test browser. //We can not use the closeWindow function if we will later use the openUrl function, because we will lose the HTML GUI Adaptor instance.// It needs an input parameter element, to select any element on the page we want to close. 

  * **cookiesManage:** Click on the button to accept cookies.

  * **countElements():** Counts found elements html and saves value to integer variable. The parameter is Element, with this we can indicate which part of the html the user wants to count.

  * **deleteAllCookies():** Deletes all browser cookies. Do not require parameters.  

  * **deselectAllOptions(Element):** Deselects all options of html select. Applies when multiple html are selected. As input parameter this function have an Element to indicate which part of the page the user wants to apply this function.

  * **doubleClick(Element):** Does double click on the element. With the input parameter Element the user indicates which element will be double clicked.

  * **dragAndDrop():** Function to move an element to another one. The “ElementFrom” parameter is to choose the element that the user wants to drag, and the “ElementTo” to choose where the user wants to drop the first element. The result is the movement of the first element.

  * **dragAndDropClickAndHold():** Fills the same function as the dragAndDrop, but moves the element in a different way. Should be used if dragAndDrop does not work. Has an extra optional parameter to wait before releasing the selected element.
 
  * **fileDownload(Element):** Downloads a file. The path parameter (path to download the file) is optional. If not specified, by default the file will be downloaded to the logs folder.
      * In the diagram is not necessary previously to use a click or any other action.
      * Currently, there are two allowed types of elements to be downloaded: 
            * **//files//:** in this case, when inspecting the page from where the file will be downloaded, the <href> tag must appear, which will include the URL from where the file is downloaded:\\ \\ {{:fileDownload.png}}\\ \\             
            * **//images//:** in this case, when inspecting the page from where the image will be downloaded, the element 'src' must appear:\\ \\ {{:fileDownload_1.png}}\\ \\            

  * **fileDownloadDialog(Element):** Downloads a file. 
      * It is used when in the page from which you want to download the file there is a button, link or other element that when you click on it, a file is downloaded.
      * To consider that when you use //fileDownloadDialog// you do not have to open any Explorer window, since otherwise, in the execution of the test the focus will be lost and the test may be failed.\\ \\ Example of a page where you can use filedownload:

{{:filedownloaddialog.png}}


  * **fileDownloadURL(URL To Download a File. Path To Store The File):** Downloads a file from a given URL to an specified path where the downloaded file will be stored. 
      * **URL To Download a File:** You should provide a URL from which you will directly download a file.
      * **Path To Store The File:** This is an optional file. In case this field is empty you will store the file in the current default folder for downloading files, otherwise, the file will be stored in the folder given by user.
 
  * **fileUpload(Element):** It uploads a file from a Html page. For using this PF you should access to a page which has an input element for uploading file (e.g. https://www.sendspace.com/), that is which is prepared to upload files. The fileUpload PF has three parameters: two for the information about the input element in a page (Search by and Element), and another one for the information about the file you want to upload to (Value). 

  * **fileUploadDialog(Element,fileUrl, WaitinSeconds):** This function uploads a file through the modal window of Windows. With the Element input parameter, the user chooses where to click to call the upload dialogue. The fileUrl parameter picks up the file path and the wait in seconds parameter indicate the seconds before paste the fileUrl, it will be 1 second by default. Also, this function takes a screenshot once the “upload” file dialogue shows up. 

  * **focus():** Function to put the focus on a element. With the Element parameter the user indicate where the focus will be.

  * **generateFileAsEvidence:** Generate a text file as evidence for the test.

  * **getAttribute(Attribute):** Gets text, value, attribute of the element and saves to variable.\\ If the attribute is present and the field disabled, true is returned. If the attribute doesn’t exist and you can edit the field, an empty string is returned with a message in the log saying that the attribute doesn’t exist. The function returns an empty string “ ” for any attribute value that doesn’t exist.

  * **hasOptionWithValue(Element):** Checks if exist an option with a determined value. Applies to select html element. It is localized with a SearchBy input and the input parameter is value.

  * **isCurrentUrlContains(String):** Checks if current URL contains string. With the input parameter the user introduces the string to check, and the function execute the comparison.

  * **isCurrentUrlEquals(String):** Checks if current URL equals exact string. With the input parameter the user introduces the string to check, and the function execute the comparison.  

  * **isCurrentUrlMatches(RegularExpresion):** Checks current URL with a regular expression. As input parameter the user enter the URL, if this URL matches with the page URL the function will return true, if not will return false.

  * **isDisplayed(Element):** Checks if this element is displayed or not. The user previously indicates with an input parameter Element the “element” that the function has to check.  

  * **isExist(Element):** Checks if the element exists and prints result on user log file. The input parameter Element will be the element the function has to check.   

  * **isExistWithoutScroll():** Checks if the element exist without scrolling to it and write the result in the log. The input parameter element is used to write the element we want to check.

  * **isSelected(Element):** Determines whether or not the element is selected. This operation only applies to input elements such as checkboxes, options in a select and radio buttons.

  * **isTitleEquals(String):** Checks if the page title is exactly like indicated string. The input parameter is the string that will be used in the comparison.    

  * **isTitleMatches(RegularExpression):** Checks if the page title matches with the string indicated in the regular expression.  

  * **javascriptAlertAccept(String):** Clicks on Accept Javascipt alert button. It contains a string parameter just in case the user has to use it in a JavaScript prompt (where the user needs to write something).

  * **javascriptAlertCancel(String):** Clicks on Cancel javascipt alert button. It contains a string parameter just in case the user has to use it in a JavaScript prompt (where the user needs to write something).

  * **javascriptExecute(String):** "Allows to execute custom javascript during testing. Some examples of using the //javascriptExecute function//:\\ \\ 
       *Search for element by ID and set the value:\\  document.getElementById(""Element ID if exists"").value = ""50"";
       *Search by name and set value:\\  document.getElementsByName(""savingRatePerMonth"")[0].value=""50"";
       *Navigate to another page with javascript:\\  document.location.href = 'http://www.mozilla.org/en-UK';
       *Get the attribute of an element:\\  var attribute = document.getElementById(""elementId"").getAttribute(""href"");\\ \\ This function does not pick up the data type selected in the diagram for the output, instead it returns the data type given by the function. 

  * **javascriptExecuteWithParameters(code, arguments):** Allows execute custom Javascript during the test with the values passed as parameters. To use them, you should use arguments[i] where i is the position of the parameter. The index of the first parameter is 0 (i=0). An example of use of the //javascriptExecuteWithParameters// function:
    * Search item by Name and put the value passed as first argument: document.getElementsByName(“savingRatePerMonth”)[0].value=arguments[0];\\ \\ TIP: To obtain the URL from the actual website in a variable to use it, we have to use in the “code” parameter: return window.location.href; and create an output variable to keep the URL.\\     

  * **login():** Allows to the user to login in only one step. To do this the input parameters user, password and the access button are needed. (The fields that are going to be filled with the parameters has to be pointed (out).  

  * **mouseOver(Element):** Place the mouse over the HTML element of the page indicated in the Mapping tab. The element is indicated with the input parameter.     

  * **openUrl(String):** Opens new browser URL. //We can not use the closeWindow function if we will later use the openUrl function, because we will lose the HTML GUI Adaptor instance.//

  * **optionWithValueIsEnabled(Element):** Checks if the option with a determined value is enabled. Applies to select html element selected in the input parameter. 

  * **optionWithValueIsSelected(Element):** Checks if the option with a determined value is selected. Applies to select html element selected in the input parameter. 

  * **pressEnter(Element):** Makes simulate the "Enter" key press in the keyboard about an html element predefined in the input parameter.    

  * **resetToDefaultContent:**  This function is used to leave the frames, it should be used once the user is done using the frame or if the user wants to change the frame.
   
  * **rightClick(Element):** Makes click on the right mouse button over the given element.

  * **scrollToElement:** Scrolls the page to the specified HTML element. 

  * **searchTextOnPage**: Searches for text on the current page and strips the text from the found element. Use the Exact text parameter to find an exact text, default is false. Use the Count number parameter to get the element from the array of found elements with this text. 

  * **searchTextOnPageCount**: Searches for the text on the current page and returns the number of elements found with this text. Use Exact text parameter to find an exact text, default is false. 

  * **searchTextOnPageXPath**:Searches for text on the current page and returns the Xpath to the element containing this text. Use the Exact text parameter to find an exact text, default is false. Use the Count number parameter to get the element from the array of found elements with this text.

  * **select(Element):** Selects an option from the list of options of the select html element.

  * **selectAllOptions(Element):** Selects all options of html select. Applies to select multiple html.

  * **selectOption(Element):** Use this when visible value isn´t found. It's necessary to use the value of option: <option value="****">.

  * **selectRadioButton:** Function to select the radio button by group name and value.

  * **sendKeys:** Send a key combination to execute.

  * **submit(Element):** Clicks on the element and sends the form. The element to be clicked is pointed out with the input parameter.   

  * **switchToFrame:** This function point to the frame the user wants. It can be selected with xpath, id, name or index. If there were frames nested they should be separated by “;”.\\ 1.- index\\ 2.- name or id\\ 3.- Locate the frame using xpath or by any other locator.\\ \\ For example:\\ If you have this case, and you would like to select frame with name "a2"\\ <frame name= "a">\\ <frame name= "a1"/>\\ <frame name="a2"/>\\ </frame>.\\ In this example frame "a" is a frame with 2 nested frames "a1" and "a2"\\ \\ switchToFrame can be used like this to get the frame you want:\\ if you want to get to the first frame you should put switchToFrame(0); (the 0 is because the first frame starts to count from “0”) or switchToFrame(a), switchToFrame(*\\[name="a"]).\\ \\ To get to the nested frame a2 **you can do it like this**:\\ 1.- index:  switchToFrame(0); switchToFrame(1)\\ 2.- name or id: switchToFrame(a); switchToFrame(a2)\\ 3.- xpath: switchToFrame(*\\[name="a"]); switchToFrame(*\\[name="a2"])\\ **or it could be with only one message using ";" to separate the identifier**:\\ 1.- index:  switchToFrame(0;1)\\ 2.- name or id: switchToFrame(a;a2);\\ 3.- xpath: switchToFrame(*\\[name="a"];*\\[name="a2"]);\\ This way is the expected to be used.

  * **tableCellValue():** Function gets value from the cell. It’s necessary HtmlTable variable and the position of the value from the cell. The format of the position is: row;column. The rows always start in 1.

  * **tableCellXPathByPosition():** Function gets XPath from the cell. It’s necessary HtmlTable variable and the position of the xpath from the cell. The format of the position is: row;column. The rows always start in 1. 

  * **tableColumnsNum():** Function count number of columns. As input parameter the user must indicate the tableHtml that previously should have been made.  

  * **tableHLookUpValue():** Function allows you to obtain values from the cells in the RetrieveRow row by doing a search by SearchValue value in the cells of the SearchRow row.

  * **tableHLookUpXPath():** Function allows you to obtain XPath from the cells in the RetrieveRow row by doing a search by SearchValue value in the cells of the SearchRow row.

  * **tableHtml():** Function converts the html table to tast table. It’s necessary indicate Xpath of table and If it has header by a boolean variable (true or false).** For all function of type tableHtml, you need use this previously.**
  
  * **tableRowsNum():** Function count number of rows. As input parameter the user must indicate the tableHtml that previously should have been made.
  
  * **tableVLookUpValue():** Function allows you to obtain values from the cells in the RetrieveColumn column by doing a search by SearchValue value in the cells of the SearchColumn column.

  * **tableVLookUpXPath():** Function allows you to obtain XPath from the cells in the RetrieveColumn column by doing a search by SearchValue value in the cells of the SearchColumn column.

  * **takeScreenshot():** Takes a screenshot of the page.   

  * **takeScreenshotFullPage(Searchby, XPathElements):** It takes a complete HTML page screenshot. The function has optional parameters to search by elements and hide for taking the screenshots. Once the screenshot is taken the elements are visible again. Several elements can be hidden by providing the XPath (CSS, etc) separated by a “;”. This allows the user to hide, for example, the fix header which is published by each scroll of the page.

  * **type(Element):** Adds new value to existing value of the element.  

  * **typeaction():** Adds new value to existing value of the element using special action.

  * **typekeys():** Adds new value to existing value of the element sending keys.

  * **unCheckbox(Element):** Unticks the checkbox in the element.

  * **validateAttribute(Element):** Validates element attributes like: id, class, href, size, width, value, text … etc. Print result on user log file.

  * **waitFor(TimeInSeconds):** Waits time in seconds received by the parameter.

  * **waitForElement(Element, TimeInSeconds):** Waits for the element to appear. Until it’s available in the HTML code, even if it is not visible. By default webdriver will wait 30 seconds (We can decrease or increase this time in the code). Visibility means that the element is not only displayed but also has a height and width that is greater than 0.

  * **waitForElementTime():** This function waits for the element until it “appears”, that is until the HTML code is available even though the element is not visible yet (the visibility of the element mean that it is not shown but it already has height and weight higher than 0) . The webdriver waits for 30 seconds by default and returns the time with a double. The input parameter TimeInSeconds is to change the default time, and the Element parameter is to indicate which element we want to use.