Introduction

This page shows how to use the ATS UI Engine in order to automate the functional testing of a web application working on top of HTML and javascript

The current implementation uses internally Selenium. Because of that Web UI tests require JavaSE 8 as a minimum JRE.

If this gets changed in the future, the UI Engine needs to make the change as transparent as possible.

Quick example

Please have a look at the Quick example provided in the beginning of this page

Supported browsers and settings

Here you can see the list of supported browsers. In order to use some of them, you need to take some preparation steps

Using different browsers

Let's say we want to change the used browser in the quick example . In order to achieve that, we have to change only the first code line, e.g.

// 1. initialize the browser
InternetExplorerDriver driver = UiDriver.getInternetExplorerDriver( "SOME URL" );
...

But if want to run same tests with different browsers, you can use code like the following:

import com.axway.ats.uiengine.AbstractHtmlDriver;

AbstractHtmlDriver driver;

String browserType = "CHROME";
if( browserType.equals( "FF" ) ) {
     driver = UiDriver.getFirefoxDriver( "SOME URL" );
} else if( browserType.equals( "CHROME" ) ) {
     driver = UiDriver.getChromeDriver( "SOME URL" );
} else if( browserType.equals( "IE" ) ) {
     driver = UiDriver.getInternetExplorerDriver( "SOME URL" );
} if( browserType.equals( "EDGE" ) ) {
     driver = UiDriver.getEdgeDriver( "SOME URL" );
} else if( browserType.equals( "SAFARI" ) ) {
     driver = UiDriver.getSafariDriver( "SOME URL" );
} else if( browserType.equals( "HIDDEN" ) ) {
     driver = UiDriver.getHiddenBrowserDriver( "SOME URL" );
}
...

We are using here the common for all browsers AbstractHtmlDriver class

Hidden driver operates over the headless HtmlUnit

Configuration

Here you can see some useful configuration options when the UI Engine is used for testing HTML/Javascript applications

Finding UI elements

There are many ways to find a UI element. This is the order we use to find the UI element.

_css

we will search by CSS

xpath

we will search by XPATH

other attributes

We will search for UI element matching all provided attributes. For example, if provided name and value, we will search for an element having these name and value

You can search for a UI element by its HTML element in the HTML page. For example, some elements are <input> or <a> or <div> or <span> etc.

For such cases, you can specify a _inputType . For example, if we have:
<Element mapID="usernameTB" _inputType ="input" name="betterUser" />
we will search for <input> HTML element with name "betterUser"

You can search for a UI element by its text as returned by javascript as each UI element supports the text javascript attribute.
In order to do that you need to specify a _text or _partText . The latter one matches a part of the text.

For example, if we have:
<Element mapID="usernameTB" _inputType ="input" _partText ="User" />
we will search for <input> HTML element with text containing "User"

In case you want to exclude some attributes in the map file from being used in the search, you can do that by using double underscore ( __ ) in front of the attribute name.

For example, you can have a __description attribute in the map file which you can use as some important hint, but this must not be used when searching that element.

Supported UI elements

Following is the current list with all supported UI elements.
You can see the java classes per UI element, the list of actions you can run on each UI element, and the list of attributes needed to find the UI element.

Button

A button

class	instantiation	searched by
RealHtmlButton HiddenHtmlButton	engine.getButton()	1. _css
		2. xpath
		3. id
		4. name + value
		5. name
		6. value

methods	description
click	click it (if the element is invisible, check the Configuration section how to allow such action)
clickAndDownloadFile	click and download file (check the Configuration section)

Text Box

A box which value can be changed

class	instantiation	searched by
RealHtmlTextBox HiddenHtmlTextBox	engine.getTextBox()	1. _css
		2. xpath
		3. id
		4. name

methods	description
getValue	get its value
setValue	set its value
verifyValue	verify its value is as specified
verifyNotValue	verify its value is not as specified

Text Area

A multi-line box which value can be changed.

Note: All values provided by the user or coming from the browser are normalized by replacing all "\r\n" with "\n" and trimming leading and trailing white spaces.

class	instantiation	searched by
RealHtmlTextArea HiddenHtmlTextArea	engine.getTextArea()	1. _css
		2. xpath
		3. id
		4. name

methods	description
getValue	get its value
setValue	set its value
verifyValue	verify its value is as specified
verifyNotValue	verify its value is not as specified

Check Box

A check box

class	instantiation	searched by
RealHtmlCheckBox HiddenHtmlCheckBox	engine.getCheckBox()	1. _css
		2. xpath
		3. id
		4. name + value
		5. name

methods	description
check	check it
unCheck	un-check it
isChecked	tell if it is checked
verifyChecked	verify it is checked
verifyNotChecked	verify it is not checked

Link

A link

class	instantiation	searched by
RealHtmlLink HiddenHtmlLink	engine.getLink()	1. _css
		2. xpath
		3. id
		4. name
		5. href
		6. title (the text of the "a" node)

methods	description
click	click it
clickAndDownloadFile	click and download file (check uiengine.properties file)

Table

A table

class	instantiation	searched by
RealHtmlTable HiddenHtmlTable	engine.getTable()	1. _css
		2. xpath
		3. id
		4. title
		5. name

methods	description
getFieldValue	get its value
verifyFieldValue	verify its value is as specified
verifyFieldValueRegex	verify its value matches the specified regular expression
verifyNotFieldValue	verify its value is as specified
getRowCount	get the number of rows in a table
getColumnCount	get the number of columns in a table

Single selection list

A select element that can have only one selected item

class	instantiation	searched by
RealHtmlSingleSelectList HiddenHtmlSingleSelectList	engine.getSingleSelectList()	1. _css
		2. xpath
		3. id
		4. name

methods	description
getValue	get its value
setValue	set its value
verifyValue	verify its value is as specified
verifyNotValue	verify its value is not as specified

Multiple selection list

A select element that can have one or more selected items

class	instantiation	searched by
RealHtmlMultiSelectList HiddenHtmlMultiSelectList	engine.getMultiSelectList()	1. _css
		2. xpath
		3. id
		4. name

methods	description
getValues	get its selected values
setValue	select a value
unsetValue	unselect a value
verifyValue	verify the specified value is selected
verifyNotValue	verify the specified value is not selected

Radio list

A group of radio buttons with the same name. Only one can be selected at a time

class	instantiation	searched by
RealHtmlRadioList HiddenHtmlRadioList	engine.getRadioList()	1. _css
		2. xpath
		3. id
		4. name

methods	description
isValue	tells if this is the selected radio button
setValue	select a radio button
verifyValue	verify the specified radio button is selected
verifyNotValue	verify the specified radio button is not selected

File browse

An element used to select a file from the local file system

class	instantiation	searched by
RealHtmlFileBrowse HiddenHtmlFileBrowse	engine.getFileBrowse()	1. _css
		2. xpath
		3. id
		4. name

Directly setting the file path value

Using the following methods, we directly work with the text value without opening the native OS file browse window. This is the preferred way of choosing a file.

methods	description
getValue	get its value
setValue	set its value, when you set file path use '\' for Windows and '/' for UNIX OSes
verifyValue	verify its value is as specified
verifyNotValue	verify its value is not as specified

Setting the file path value by manipulating the native OS file browse window

A real user opens a native dialog used to browse the file system and choose the file of interest. You can do the same by using the following method:

methods	description
setValueUsingNativeDialog	full path to the file of interest

Currently, this method works on only through Firefox and Chrome browsers on Windows OS

Generic element

Any HTML element

class	instantiation	searched by
RealHtmlElement HiddenHtmlElement	engine.getElement()	1. _css
		2. xpath
		3. id
		4. name

methods	description
click	click the element (if the element is invisible, check the Configuration section how to allow such action)
doubleClick	double click mouse action on the element
rightClick	right-click mouse action on the element
mouseOver	mouse over the element
getTextContent	get element text content (the innerText of the element)
getAttributeValue	get element attribute value (style,class,...)
getCssPropertyValue	get element CSS property value
pressEnterKey	simulate Enter key
pressTabKey	simulate Tab key
pressEscapeKey	simulate Escape key
dragAndDropTo	drag and drop an element on top of another element
scrollTo	scroll to element so it is viewable

Popups - Alerts, Prompts and Confirms

Elements like Alert, Prompt, and Confirm are handled differently than the other UI elements.

First, you can have only one of them at a time, which means you do not need to provide attributes for finding them.

Second, these elements must be expected before they are triggered. For example, if we know that clicking some button will generate an Alert popup, we have to expect this Alert before clicking it in the following way:

// expect the Alert element before the action which triggers it
engine.expectAlert().clickOk();
engine.getButton( "openAlertButton" ).click();

Here is how these elements look like
	The Alert popup is just letting you know about some event
	The Confirm dialog is asking you a questions with predefined answers
	The Prompt dialog requests you to provide some info

Here is the list of supported actions on these elements:

class	instantiation	methods
RealHtmlAlert HiddenHtmlAlert	engine.expectAlert()
		clickOk
		clickOk( expectedAlertText )
		verifyProcessed
RealHtmlPrompt HiddenHtmlPrompt	engine.expectPrompt()
		clickOk( promptValue )
		clickOk( expectedPromptText, promptValue )
		clickCancel
		clickCancel( expectedPromptText )
		verifyProcessed
RealHtmlConfirm HiddenHtmlConfirm	engine.expectConfirm()
		clickOk
		clickOk( expectedConfirmText )
		clickCancel
		clickCancel( expectedConfirmText )
		verifyProcessed

Frames and forms

In order to find an element in a frame or from or both, all you need to do is to specify the respective attribute. Here are some complex examples:

<Map>
     <Section name="login">
          <Element mapID="usernameTB" type="TextBox" id="_a_user_name_" frame="MyBottomFrame -> MyBottomLeftFrame" formid="theLoginFormId"/>
          <Element mapID="userpasswordTB" type="TextBox" name="password"  formname="theLoginFormName"/>
          <Element mapID="loginButton" type="Button" xpath="//html/body/form[2]/input[@id='loginB']" />
     </Section>
</Map>

In this case, when need to work with the "usernameTB" element, the UI Engine will navigate to a frame called "MyBottomLeftFrame" which is nested into the "MyBottomFrame" top frame and additionally the element will be searched into a form with id "theLoginFormId".
The "userpasswordTB" element will be searched into a form with the name "theLoginFormName".

If an element belongs to a form and this is not specified, it will be searched across all present forms and the first matching one will be chosen.

It is also possible to use XPATH locators for frames/iframes. For example: frame="//frame[contains(@name, '_test_frame')]"

Windows

There are some methods to work with browser windows (no matter if the window is new or it's a new browser tab).

methods	description
engine.goToWindow( windowTitle )	Switch to window by its Title
engine.goToWindow( windowJavascriptPropertyKey, windowJavascriptPropertyValue )	Switch to window which has a javascript property set. Usually this is the "name" variable
engine.goToMainWindow( )	Switch to the main window
engine.goToFirstWindowWithoutTitle( )	Go to first window/tab without title, skipping the main window
engine.getWindowTitles( )	Returns the titles of all windows that the browser knows about
engine.closeActiveWindow()	Close the active window/tab

Utilities

Some utility classes and methods for the Html Engine

Element state

This can be used to check the state of an HTML element.

class	instantiation
RealHtmlElementState HiddenHtmlElementState	engine.getUtilsElementState()

methods	description
verifyExist	verify an element exists on the current page
verifyNotExist	verify an element does not exist on the current page
waitToBecomeExisting	wait for an element to appear on the current page
waitToBecomeNotExisting	wait for an element to disappear from the current page
waitToBecomeDisplayed	wait for an element to become displayed on the current page
waitToBecomeHidden	wait for an element to become hidden on the current page
waitToBecomeEnabled	wait for an element to become enabled on the current page
waitToBecomeDisabled	wait for an element to become disabled on the current page
highlightElement	tries to highlight an element
focus	moves the focus to the specified element
isElementPresent	if an element presents
isElementEnabled	if an element is enabled
isElementDisplayed	if an element is displayed

Fire JavaScript event

Explicitly simulate an event, to trigger the corresponding "onevent" handler of some HTML element.

methods	description
engine.fireEvent()	Fires event like click, blur, focus, change, submit, keydown, keyup, keypress etc.

Execute JavaScript command

Gets the result of evaluating the specified JavaScript command. The command/snippet may have multiple lines, but only the result of the last line will be returned.

methods	description
engine.executeJavaScript()	execute JavaScript command

Count elements

Returns the number of HTML elements that match the specified xpath eg. "//table" would give the number of tables

methods	description
engine.countElements()	count elements located by xpath

Get page source

This method is helpful when using hidden browser driver and we don't see the loaded page or the changes on it.

methods	description
engine.getPageSource()	Returns the current page source as a String

Get current page URL

Get the URL of the page currently loaded in the browser.

methods	description
engine.getCurrentUrl()	The URL of the page currently loaded in the browser

Create page Screenshot

You can save a screenshot into a PNG file:

UiEngineUtilities.createScreenshot( filePath, browserDriver );

Browser control

methods	description
engine.clickBrowserBackButton()	simulate click on a browser Back button (move back a single "item" in the browser's history)
engine.clickBrowserForwardButton()	simulate click on a browser Forward button (move forward a single "item" in the browser's history)
engine.clickBrowserRefreshButton()	simulate click on a browser Refresh button
engine.retrieveBrowserFocus()	retrieve the browser's focus

Configure a proxy

If you want to use a proxy (e.g. Fiddler), you can use java system properties to set the proxy host and port. Here is how:

// 1. configure proxy host and port
System.setProperty( "http.proxyHost", "127.0.0.1" );
System.setProperty( "http.proxyPort", "8200" );

// 2. initialize the browser
AbstractHtmlDriver driver = UiDriver.getFirefoxDriver( "SOME URL" );

// 3. start the browser
driver.start();

Hints

For easy getting and testing XPaths on the HTML page, you can use some Firefox add-ons.

If there is a problem with finding elements by XPath (using 'xpath' property) make sure you are using two slashes // in the beginning of the xpath, not just one /

Troubleshooting

Here you can see some problems we have hit with some browsers.

Back to parent page

Go to Table of Contents

ATS : Automated testing of HTML and Javascript application