Test Designer JS Commands Reference

Parameters enclosed within brackets are optional, for example [options]

These commands are not valid in the Actions Tab of the SmartTag Workbench. You must use JQuery or JavaScript methods there. These commands can be used in the Validations tab of the SmartTag Workbench.

General functions

If you cannot find the function in the Test Designer IDE, then use custom JS actions.

_addNetworkLibrary = addNetworkLibrary

Parameters: filepath
Description: adds a network library with HTTP extractions and validaations to the script execution
Example:

addNetworkLibrary("{ds}/Favorites.stags");

_addSmartTagsLibrary = addSmartTagsLibrary

Parameters: filepath
Description: adds a smarttags library enabling the usage of the defined smartags within the test designer script.
Example:

addSmartTagsLibrary("{ds}/demositeSmartTags.netx");
navigateTo("https://demosite.appvance.com");

_alert = alert

Parameters: message
Description: Alerts the message on the browser. This allows a very handy, interactive way of debugging scripts.
Example:

_setCompatibility(true)
_navigateTo("http://sahitest.com/");
_click(_link("demo"));
_navigateTo("http://sahitest.com/demo/formTest.htm");
_wait(1000);
assertEqual("object",_lastAlert())
_wait(1000)
_clearLastAlert()
assertEqual("",_lastAlert())

_clearLastAlert = clearLastAlert

Description: contents of the last pop up is cleared
Example:

clearLastAlert()

_click = click

Parameters: target, [options]
Description: Executes a click the target element. Options parameter can be "CTRL", "SHIFT", "ALT" or "META", or combinations like "CTRL|SHIFT"
Examples:

navigateTo("https://demosite.appvance.com")
click(link("Mugs"))
click(link("Bags"), "CTRL")

_clickXY = clickXY

Parameters: target, xy, [options]
Description:
Example: Simulates a click event at the point (x,y).

navigateTo("https://www.apple.com")
click(link("ac-gn-link ac-gn-link-iphone"))
clickXY(link("ac-gn-link ac-gn-link-tv"),"30,10")

Parameters: cookieName
Description: returns the value of a browser cookie.
Example:

_navigateTo("http://sahitest.com/")
_createCookie("DS3Cookie","Ready")
_click(_link("demo"))
var myCookie = _cookie("DS3Cookie")
_assertEqual(myCookie,"Ready")

_createCookie = createCookie

Parameters: cookieName, cookieValue
Description: creates a cookie in the current browser session.
See Also: deleteCookie, cookie.
Example:

_navigateTo("http://sahitest.com/")
_createCookie("DS3Cookie","Ready")
_click(_link("demo"))
var myCookie = _cookie("DS3Cookie")
_assertEqual(myCookie,"Ready")

_deleteCookie = deleteCookie

Parameters: cookieName
Description: deletes a cookie from the current browser session.
Example:

_deleteCookie("DS3Cookie")

_doubleClick = doubleClick

Parameters: target, [options]
Description: simulates the double clicks on the given target element.

Example:

navigateTo("http://sahitest.com/")
click(link("/demo"))
click(link("clicks.htm"))
click(button("dbl click me"))
doubleClick(button("dbl click me"))
click(button("click me"))

_doubleClickXY = doubleClickXY

Parameters: target, xy, [options]
Description: Simulates a double click event at the point (x,y).
Example:

navigateTo("https://www.apple.com")
click(link("ac-gn-link ac-gn-link-iphone"))
doubleclickXY(link("ac-gn-link ac-gn-link-tv"),"30,10")

_drag = drag

Parameters: target, options
Description: Simulates a mouse drag action
Example:
See example for _drop below.

_drop = drop

Parameters: target, xy
Description: Simulates the drop action in a drag and drop operation
Example:

navigateTo("http://jqueryui.com/draggable/");
click(link("/resources/demos/draggable/snap-to.html"));
click(div("snaptarget"));
click(div("draggable2"));
drag(div("draggable2"),);
drop(div("snaptarget"),"40,20");
click(byXPath('//*[text()="I only snap to the outer edges of the big box"]'));
click(paragraph("I snap to a 80 x 80 grid"));
click(paragraph("I snap to a 20 x 20 grid"));

_eval

Parameters: data (expects native array)
Description: Evaluates the provided javascript code in the browser. The function can provide return data as well as execute some action.

_eval example 1:

function name() {
var anchor = _eval("ds$('a')");
log(typeof anchor);
log("lngth:" + anchor.length);
for(var i =0;i<10;i++) {
var href = getAttribute(anchor[i],"href");
log("href:" + href);
}
}
navigateTo("https://www.w3schools.com");
name();

_eval example 2:

_navigateTo("https://www.apple.com");
_log("typeof "+typeof _eval("(function(){})();"));
_log( _eval("(function(){return null;})();"));
_eval("ds$('html, body').scrollTop(ds$(document).height())");

_eval example 3:

var collection = _eval("ds$('.space-program-detail').not('.hideProgram').find('.program-name')");
log(collection.length);
var data = _getLength('.space-program-detail');
log(data);

_eval example 4:

_eval("ds$('html, body').scrollTop(ds$(document).height())");
_wait(4000);
var data1 = _eval("Math.round(ds$(window).scrollTop())");
log(data1);
var data2 = _eval("ds$(window).height()");
_log(data2);
var data4 = data1 + data2;
_log(data4);
var data3 = _eval("ds$(document).height()");
_log(data3);
var end = _eval("Math.round(ds$(window).scrollTop())+ ds$(window).height() == ds$(document).height()");
_log(end);
if(end == true) {
_log("scroll bottom is reached");
}

_formSubmit = formSubmit

Parameters: target
Description:
FormSubmit API is used to Simulate the ENTER key action by the user by Submitting the form of the application. We can also use Native key actions however the drawback of this is that we cannot use this for Performance test and also the browser needs to be in focus all the time
To overcome the drawback of Native key Events we can use this API as this works fine even if the browser is not in focus and also can be used in Performance tests

Example:

_navigateTo("website URL");
_formSubmit(_form("partlookupform"));
_wait(3000);
_assertContainsText("Invalid Query",_div("custdialog"));
_click(_span("OK"));

_focus = focus

Parameters: value
Description: Brings focus to a given element.
Example:

navigateTo("http://demosite.appvance.com/");
focus(span("Products[1]"));
click(span("Products[1]"));
click(link("Clothing"));

_focusWindow = focusWindow

Parameters:
Description: Brings the window above all other windows. It is generally needed before using other native events or before taking screen shots Works only on Windows Operating Systems currently. On Mac and Linux, does nothing. For popup windows, use _selectWindow first.
See also: selectWindow
Example:

_focusWindow(); // bring window into focus.

_getAllLinks = getAllLinks

Description: used to retrieve all anchor elements/links in an HTML page.
Example:

getAllLinks();

_getAttribute = getAttribute

Parameters: element, attrName
Description: used to retrieve the attribute value by specifying the name for a given element
Example:

var href = getAttribute(link("id"),"href");
log("href:" + href);

_getBrowserURL = getBrowserURL

Description: returns the Browser URL.
Example:

navigateTo("http://sahitest.com/demo");
assertEqual("http://sahitest.com/demo/",getBrowserURL());

_getChildElementCount = getChildElementCount

Paramters:elem

Description: Used to find the count of child elements considering given the element as parent.

Example:

navigateTo("https://www.apple.com/");
click(link("Apple[1]"));
click(link("iPad"));
var dyn1 = childElementCount(div('ac-gn-content'));
assertEquals(4,dyn1);
//log(childElementCount('.ac-gn-content'));//class name selector
assertEquals(14,childElementCount(div('main'))); //id selector

_getClipboardText = _getClipboardText

Parameters: variable
See Also: grantPermissions

Description: Used to retrieve the contents of the clipboard to a variable. Needs to grant the clipboard permission first. Only works with custom profile in IDE. Not works in scenario editor executions as browser opening in the test node are in incognito mode.
Version: 4.8.5 +

Example:

grantPermission("https://mydomain.com", "clipboardReadWrite");
getClibboardText($theClipboard);

_getComputedStyle = getComputedStyle

Parameters: elem, param
Description:

The getComputedStyle() method gets all the actual (computed) CSS property and values of the specified element.

The computed style is the style actually used in displaying the element, after "stylings" from multiple sources have been applied.

Style sources can include: internal style sheets, external style sheets, inherited styles and browser default styles.

Example:

navigateTo("http://demosite.appvance.com/");
var color=getComputedStyle(header("header"),"background-color");
log(color);
assertEqual("rgba(34, 34, 34, 0.4)",color);

_getHtml = getHtml

Description: retrieves the HTML of the current page.
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("containTest.htm"));
var myHTML = getHtml();
log(myHTML);
var index = myHTML.indexOf("abc")+"";
log(index);
assertEquals(index,"896");

_getLength = getLength

Parameters: value
Description: this is generally used to get the length of rows or columns from a table.
Example:

var $length =_getLength('.v-table-table tr')
// .v-table-table is the class name
// and tr will be rows

_getProp = getProp

Parameters: value
Description: to get the element property value (similar to jquery .prop())
Example:

var optionIndex =_getProp(option('Dashboard'),"selectedIndex")

_getScrollTop = getScrollTop

Parameters: target
Example: Get the current vertical position of the scroll bar for the first element in the matched elements. See also setScrollTop.

_navigateTo("https://api.jquery.com/scrollTop/");
_selectMainFrame();
_setScrollTop(_byXPath("//html"),300); //Firefox Only
_assertEqual(300,_getScrollTop(_byXPath("//html"))); //Firefox Only

_getText = getText

Parameters: element
Description: The returned string is normalized for different browsers. Multiple continuous spaces are replaced with a single space. Multiple continuous newlines are replaced with a single newline. Newlines are always returned as \n even on Mac and Linux so that scripts can work across browsers and OSes.
This API uses the textContent or innerText attributes of elements.
Example:

navigateTo("https://www.apple.com/");
click(_link("Music"));
click(_link("Mac"));
var val1=getText(link("iPad"));
log(val1);
click(link("/ipad/"));

_getTextSelenium = getTextSelenium

Parameters: element
Description: This is similar to getText, but this will return the trimmed text of the HTML.
Example:

navigateTo("https://www.apple.com/");
click(_link("Music"));
click(_link("Mac"));
var val1=getTextSelenium(link("iPad"));
log(val1);
click(link("/ipad/"));

_title = _getTitle = getTitle

Description: returns the window's title.
Example:

log("title: "+ getTitle());

_getValue = getValue

Parameters: elem
Description: This API only works on elements that take user text input. To get text out of a div or a span like elements, use _getText bettr
Example:

assertEqual("Appvance", getValue(_textbox("company")));

_getSmartTags = getSmartTags

Parameters: type, [config]
Description: Used to retrieve the SmartTags data once the SmartTags library is loaded.
See also: addSmartTagsLibrary
Example:

addSmartTagsLibrary("{ds}/test.stags");
navigateTo("https://www.appvance.com/");
var radioWidgets = getSmarTags("name"); //can also give as getSmartTags() without any paramters to fetch everything

_getSmartTagsLibrary = getSmartTagsLibrary

Parameters: type, [config]
Description: Returns the SmartTags library as a json string
See also: addSmartTagsLibrary
Example:

addSmartTagsLibrary("{ds}/test.stags");
navigateTo("https://www.appvance.com/");
var json = getSmarTagsLibrary();

_grantPermission = grantPermission

Parameters: domain, permission
The permission parameter allowed values can be seen here.
Description: Use this command to grant browser permissions to mic, or clipboard.
See also: getClipboardText
Usage: This will only work in IDE using a custom profile set for NON-Incognito mode.

Version: 4.8.5 +
Example:

grantPermission("https://mydomain.com", "clipboardReadWrite");
grantPermission("https://mydomain.com", "audioCapture");

_highlight = highlight

Parameters: target, value
Description: Adds a color border around the provided target element. Use for debugging purposes.
Example: The following code highlights a smarttag element with a red border.

addWidgetLibrary("{ds}/ServiceNowWidgets.json");
navigateTo("https://demosite.appvance.com");
highlight(ForgotPasswordLink(),"red");

_include = include

Parameters: script
Description:
Includes the script at script Path in the current script.
To reuse a function from one script in another, we include the relevant script using the Include Action API from DS3.
This will be helpful in shortening your designer scripts and mainly with the re-usability of certain scripts.
Call other scripts as functions. This will let users to Include other DS3 scripts at any given step
Test Designer supports relative paths ("{ds} means the folder where the current script is saved"), the scripts can be run from both Designer and as well as from the Scenario Builder.

Example:

include("{ds}/loginWithDPL.js");
setValue(textbox("q"),$MOBILENO);
setValue(textbox("q[1]"),$PASSWORD);
setValue(textbox("q[2]"),$DATE);
click(button("Add"));
include("{ds}/logout.js");

_isChecked = isChecked

Parameters: target
Description: Returns true if element is checked, else false
Example:

navigateTo("http://localhost:8080/UI/index.html");
setValue(textbox("username"),"appvance");
setValue(password("password"),"appvance");
click(button("login"));
click(link("ResultsTab"));
if (_isChecked(checkbox("resultsEnabled"))){
click(link("resultsAccept"));
assertExists(paragraph("Saved successfully"));
}
else {
click(checkbox(1));
}

_isVisible = isVisible

Parameters: value
Description:
isVisible returns true if the element is visible, else false. This can be used in combination with conditional statements (example shown below) or with Assertions.
Example:

navigateTo("http://sahitest.com/demo/");
click(link("a x"));
var var1= isVisible(link("linkById"));
log(var1);
if (var1==true){
click(link("linkById"));
}
click(link("linkTest.htm"));
click(bold("linkByHtml"));

_lastAlert = lastAlert

Description:contents of the last pop up
See also: _checkLastAlert
Example:

var $ch2=eval(_lastAlert())

_locker = locker

Parameters: key, value
Description: Stores the data into The Locker with a given key name.
See also: _retrieve
Example:
A simple example in JS:

var $msg=_getText(_div("custdialog"));
locker("message",$msg);

in DS (IDE):

Store in Locker | "message" | _getText(_div("custdialog"))

_log = log = _println;

Description: Logs messages
Example:

_log("Current user is " + $user); // Will log as plain text

_mouseDown = mouseDown

Parameters: target, options
Description:
Example: Simulates a mouse Down event on the element.

navigateTo("https://www.demosite.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseDown(link("ac-gn-link ac-gn-link-tv"));

_mouseDownXY = mouseDownXY

Parameters: target, xy, options
Description:
Example: Simulates a mouse down event at the point (x,y).

navigateTo("https://www.demosite.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseDownXY(link("ac-gn-link ac-gn-link-tv"),"30,10");

_mouseOver = mouseOver

Parameters: target, options
Description: mouseOver simulates a mouse hovering on the given element.

Example:

navigateTo("https://www.ted.com/about/programs-initiatives/tedx-program");
mouseOver(link("Watch"));
click(div("TED Talks"));
setSelected(select("topics"),"Technology");
setSelected(select("languages"),"en");
setSelected(select("duration"),"0-6");

_mouseOverXY = mouseOverXY

Parameters: target, xy, options
Description:
Example: Simulates a mouse hover event at the point (x,y).

navigateTo("https://www.demostie.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseOverXY(link("ac-gn-link ac-gn-link-tv"),"30,10");

_mouseOutAll = mouseOutAll

Parameters: nothing
Description: Triggers the mouse out handler for the entire body of HTML
Example:

mouseOutAll();

_mouseUp = mouseUp

Parameters: target, options
Description: the mouse up event is sent to an element when the mouse pointer is over the element, and the mouse button is released. Any HTML element can receive this event.
Example: Simulates a mouse release event.

navigateTo("https://www.demostie.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseUp(link("ac-gn-link ac-gn-link-tv"));

_mouseUpXY = mouseUpXY

Parameters: target, xy, options
Description:
Example: Simulates a mouse release event at the point (x,y).

navigateTo("https://www.demostie.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
mouseUpXY(link("ac-gn-link ac-gn-link-tv"),"30,10");

_readCSV = readCSV

Parameters: filename
Description: reads a CSV file and stores it into a two-dimensional array variable.
Example:

var $csvtxt = "username,password"+"\n"+"oscar,passw"+"\n"+"oscar2,passw2";
// $csvtxt could be variable with contents captured by network workbench extractor
writeText("{ds}/mycsv.csv", $csvtxt );
var data = readCSV("{ds}/mycsv.csv");
log(data.length); // includes first header row
for (var i = 1; i < data.length; i++) {
   var $username = data[i][0];
   var $password = data[i][1];
   log("$username: "+$username+" $password: "+$password);
}

_resetUserAgent = resetUserAgent

Parameters: domain

Description: Restore the default browser user agent for the indicated domain requests

IMPORTANT: this command has a global effect over the DSServer, so all test designer tests running using the referenced domain, will have its request to that domain reset to use the real browser the test is being run on. This command should most likely never be called unless you know for certain no one is using the affected domain at the same time. Resetting the DS3Server domain will effectively reset all domains set by setUserAgent.

Example:

navigateTo("https://cecristest.crm9.dynamics.com");
setUserAgent("sts.dss.ca.gov", "chrome");
setUserAgent("cecristest.crm9.dynamics.com", "firefox");
setValue(emailbox("i0116"),"myusername@appvance.com");
resetUserAgent("sts.dss.ca.gov");
resetUserAgent("cecristest.crm9.dynamics.com");

_retrieve

Parameters: key
Description: Retrieves the value from the locker given a key name
Example:

Javascript (.js)

retrieve(myVariable, "message");

IDE (.ds)

_rightClick = rightClick

Parameters: target
Description: simulates the double clicks on the given target element.
Example:

_navigateTo("http://swisnl.github.io/jQuery-contextMenu/demo.html");
_rightClick(_span("right click me"));

_rightClickXY = rightClickXY

Parameters: target, x, y, options
Description: Simulates a right click event at the point (x,y).
Example:

navigateTo("https://www.demosite.appvance.com/");
click(link("ac-gn-link ac-gn-link-iphone"));
rightClickXY(link("ac-gn-link ac-gn-link-tv"),"30,10");

_rteHTML = rteHTML

Parameters: target
Description: Gets the innerHTML contents of the Rich Text Editor object.

Example:

navigateTo("http://aplicationURL");
click(link("ClickToLogin"));
setValue(textbox("userId"),"Tracy");
setValue(password("password"),"pass");
click(button("Login"));
rteWrite(iframe("k-content"),"Text data");
var dyn2=rteHTML(iframe("k-content"));
log(dyn2);
click(link("Logout"));

_rteText = rteText

Parameters: target
Description: Gets the text contents of the Rich Text Editor object.
Example:

navigateTo("http://ApplicationURL");
click(link("ClickToLogin"));
setValue(textbox("userId"),"Tracy");
setValue(password("password"),"pass");
click(button("Login"));
var dyn1=rteText(iframe("k-content"));
log(dyn1);
click(link("Logout"));

_rteWrite = rteWrite

Parameters: target, value
Description:

Rich Text Editors (RTEs) are iframes/divs whose design mode or content Editable property is set to true. Such components allow input of text and formatting them (making text bold, inserting images, etc.).
Rich Text Editors do not respond to regular events and need to be handled specifically. For now, the Recording of such events is not possible in DS3, Only replay can be done.

Example:

navigateTo("http://ApplicationURL");
click(link("ClickToLogin"));
setValue(textbox("userId"),"Tracy");
setValue(password("password"),"pass");
click(button("Login"));
var dyn1=rteText(iframe("k-content"));
log(dyn1);
rteWrite(iframe("k-content"),"Text data");
click(link("Logout"));

_setActionDesc | setActionDesc

Parameter: description
Description: Sets a string to be displayed when action is reported
Example:

_navigateTo("http://sahitest.com/");
_click(_link("demo"));
_click(_link("Link Test"));
_setActionDesc("Type T1");
_setValue(_textbox("t1"),"asdf");

_sendKeys = sendKeys

Parameters: target, value
Description: Send Keys is very similar to Set Value and the syntax and usage follows exactly the same as Set Value, Send Keys is required to use for some applications where using Set Value, it causes duplicate entries that get inserted since Set Value inputs the entire sting as a whole but Send Keys inserts the value letter by letter like type command provided by Selenium IDE.
Example:

sendKeys(textbox("username"),"username");
sendKeys(password("password"),"password");

_setAttribute = _setAttribute

Parameters: target, attrName, attrValue
Description: Used to set the attribute value to a given element
Example:

navigateTo("http://sahitest.com/");
click(link("demo"));
click(link("Link Test"));
_setAttribute(textbox("t1"),"value","20/08/2018");

_setChecked = setChecked

Parameters: target, boolean
Description: This will check/uncheck the element based on the boolean value given as input.
Example:

navigateTo("http://sahitest.com/");
click(link("demo"));
click(link("Form Test"));
setChecked(checkbox("c1"),false);
setChecked(checkbox("c1"),true);

_setEnabled = _setEnabled

Parameters: target, boolean
Description: Used to make the given target in enabled/disabled state according to boolean value provided
Example:

navigateTo("http://sahitest.com/");
click(link("demo"));
click(link("Form Test"));
_setEnabled(textbox("textdisabled"),true);
_setEnabled(textbox("textdisabled"),false);

_setFile | setFile

Parameters: element, filepath
Description: File upload. See also setFile2, setFile3, setFile4 and setFile5.
Example:

_navigateTo("http://sahitest.com/");
_click(_link("demo"));
_click(_link("File Upload Test"));
_setFile(_byXPath('//*[@id="file"]'),"{ds}/test.txt");
_click(_submit("submit"));

_setFile2 | setFile2

Parameters: element, filepath
Description: File upload.This can be used in situations where there are some UI validations to browse box/file input box.This will simply mimic the normal user handling in the sense . browsing the file from location and clicking on Upload.Please remember this can be used only in recent chrome and FF.Not supported with IE/headless FF.Supports all text file formats(txt,doc,csv)
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("/demo/php/fileUpload.htm"));
log(getHtml());
setFile2(byXPath('//*[@id="file"]'),"3521.txt");
click(submit("submit"));

_setFile3 | setFile3

Parameters: element, filepath
Description: File upload.Same as that of setFile2 .The difference is most of the modern apps do upload automatically once the file is selected without needing to click the upload button or a change mouse event. So this will come handy in these cases.
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("/demo/php/fileUpload.htm"));
log(getHtml());
setFile3(byXPath('//*[@id="file"]'),"3521.doc");
click(submit("submit"));

_setFile4 | setFile4

Parameters: element, filepath
Description: File upload. All image files can be uploaded using this as image file needs some processing such as hexa to binary of its contents in order to retain the size of images.
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("/demo/php/fileUpload.htm"));
log(getHtml());
setFile4(byXPath('//*[@id="file"]'),"3521.png");
click(submit("submit"));

_setFile5 | setFile5

Parameters: element, filepath
Description: File upload. - Video/Audio/Zip files can be uploaded using this.
Example:

navigateTo("http://sahitest.com/");
click(link("/demo"));
click(link("/demo/php/fileUpload.htm"));
log(getHtml());
setFile5(byXPath('//*[@id="file"]'),"3521.mp4");
click(submit("submit"));

_setFindOnlyEnabled = setFindOnlyEnabled

Parameters: boolean
Description: Find the element only if it is enabled on the page.

Example:

_navigateTo("https://www.apple.com");
var elems = links();
assertEqual(91,elems.size());
_setFindOnlyEnabled(true);
var elems = links();
assertEqual(91,elems.size());
_setFindOnlyEnabled(false);
var elems = links();
assertEqual(91,elems.size());

_setFindOnlyVisible = setFindOnlyVisible

Parameters: boolean
Description: Finds only if the element is visible on the page.
Example:

_navigateTo("https://www.apple.com");
var elems = links();
assertEqual(91,elems.size());
_setFindOnlyVisible(true);
var elems = links();
assertEqual(91,elems.size());
_setFindOnlyVisible(false);
var elems = links();
assertEqual(91,elems.size());

_setHTML = setHTML

Parameters: target, value
Description: sets the HTML content (innerText/textContent) to iframe element. This automatically gets recorded when setting the data inside an iframe.
Example:

setHTML(frame("id"),"setting iframe content")

_setScrollTop = setScrollTop

Parameters: target, scrollTop
Description:
Example:

_navigateTo("https://api.jquery.com/scrollTop/");
_selectMainFrame();
_setScrollTop(_byXPath("//html"),300);//FirefoxOnly
_assertEqual(300,_getScrollTop(_byXPath("//html")));//FirefoxOnly
_setEnabled(_button(0),false);
_assertEqual("http://jquery.com/download/",_getAttribute(_link("Download"),"href"));
_setAttribute(_link("Download"),"href","http://jquery.com/local/");
_assertEqual("http://jquery.com/local/",_getAttribute(_link("Download"),"href"));

_setSearchRetries = setSearchRetries

Parameters: value
Description: Controls the maximum number of retries spent trying to find an element. The default search process will retry 12 times (~ 90 seconds). This value can be used to reduce the time spent finding an element by reducing the number of retries.
Example:

setSearchRetries(6);

_setSelected = setSelected

Parameters: target, boolean
Description: Selects one or more elements in a select dropdown.
Example:

navigateTo("http://sahitest.com/demo/");
click(link("selectTest.htm"));
setSelected(select("s1Id"),"o1");
setSelected(select("s2Id"),"o2");

_setUserAgent = setUserAgent

Parameters: domain, browser

Description: Overwrites the user agent of the current browser for the requests on the indicated domain (domain parameter), for the user agent established as a parameter (chrome, firefox)
IMPORTANT: this command has a global effect over the DSServer, so all DS3 test running using the referenced domain, will have its request to that domain set to use the provided browser as its user-agent (Meaning if the target browser is IE and we set the userAgent to be chrome browser, the server of the request (say "appvance.ca.gov", etc) will respond as if it were using "chrome", but the browser will remain IE)

This call can be done several times without issue by concurrent users as long as setting the same browser per domain, otherwise, they will be changing browsers for all executing tests. So the best practice is to use the same browser per domain along with all the scripts. But values set by this command will not persist a restart of the DS3Server service.

Example:

navigateTo("https://test.crm9.dynamics.com");
setUserAgent("app.dss.ca.gov", "chrome");
setUserAgent("test.crm9.dynamics.com", "firefox");
setValue(emailbox("i0116"),"myusername@appvance.com");

_setValue = setValue

Parameters: target, value
Description: Simulates text entry into html form elements (text-box like elements and text-areas) The sequence of events performed are Focus Enter Text Remove focus. Can use this sequence of characters:

{{ENTER}}

to insert the result of hitting the Enter key.

Example:

setValue(textbox("username"),"username");
setValue(password("password"),"password");

Parameters: windowName
Description:
Example:

_writeText = writeText

Parameters: writes a text file to disk.
Description:
Example:

var $csvtxt = "username,password"+"\n"+"oscar,passw"+"\n"+"oscar2,passw2";
// $csvtxt could be variable with contents captured by network workbench extractor
writeText("{ds}/mycsv.csv", $csvtxt );
var data = readCSV("{ds}/mycsv.csv");
log(data.length); // includes first header row
for (var i = 1; i < data.length; i++) {
   var $username = data[i][0];
   var $password = data[i][1];
   log("$username: "+$username+" $password: "+$password);
}

_wait = wait (Fixed duration)

Parameters: milliseconds
Description: pauses the execution for the specified number of milliseconds
Example:

wait(30000);   // pauses for 30 seconds

_wait = wait (Conditional wait)

Parameters: value, condition
Description: Forces script to wait for a given time in millisecond or given condition to be true, whichever comes first.
Conditional testing uses constant pooling, which means TestDesigner tests the function during the wait time, If the function output becomes true, then it stops the wait.

There are two ways to use conditional waiting:

To use a function as the condition so that will be tested over and over

wait(60000, (function(){ checkSomething () }));
wait(Number.MAX_SAFE_INTEGER, ()=> checkSomething () );

2. Define a String as the condition that will be evaluated to see if it returns true
Notice: value should be inside quotes so the string gets evaluated several times during the wait period of time.

wait(90000, "isVisible(textbox('username'))" );

Conditional Wait Common Issues

The condition is not a function, but a value

wait(Number.MAX_SAFE_INTEGER, isVisible(Element()) );

IF the element is invisible, then the script will not finish, it will get stuck forever because the second parameter is already evaluated, this is exactly the same as

let isVisibleResut =  isVisible(Element()) ;
wait(Number.MAX_SAFE_INTEGER,isVisibleResut);

if isVisibleResut is false, it will never change its value.

2) The condition function fails/breaks

wait(Number.MAX_SAFE_INTEGER, ()=>{throw Exception()} );

This is will get stuck for ever because the second parameter function will always fail

System dialog functions

setConfirmMessage

Parameters: message
Description: Fills in message section of a confirm dialog
Example:

setConfirmMessage("This is a message")

setConfirmResponse

Parameters: boolean
Description: Provide true if want system to automatically click the positive (OK, Yes) button of the confirm dialog
Example:

setConfirmResponse(true)

getConfirmMessage

Description: Returns the confirm message set previously or "DS3_NOT_SET" if it has not been set.
Example:

var mess = getConfirmMessage();

setPromptResponse

Parameter: string with prompt response
Description: Sets an automatic behavior with the default response for a system prompt dialog and closes it.
Example:

var mess = getConfirmMessage();

getPromptResponse

Description: Returns the previously set default response string or "DS3_NOT_SET" if it has not been set.
Example:

var mess = getPromptResponse();

Navigation Functions

_disableMainFrame = disableMainFrame

Parameters:value
Description: disables main /parent page and selects the subframe inside the main frame
Example:

disableMainFrame();

_navigateTo = navigateTo

Parameters: URL
Description: loads the given URL in the top frame of the window. To load in a popup window, use _selectWindow to select that window first.
Example:

navigateTo("http://localhost:8080/UI/index.html");

_navigateToOrGet = navigateToOrGet

Parameters: URL
Description: loads the given host in the URL and then executes a GET HTTP call to the provided URL.
Example:

navigateToOrGet("https://www.synopsys.com/content/dam/synopsys/optical/pdf/RSoft-Choosing-Right-Photonic-System-Design-Software.pdf");

_prepareDomain = prepareDomain = _setDomain = _prepareDomain

Parameters: value
Description: DS3 prepares itself with any other external domain apart from the application domain to carry out actions in that.
Example:

prepareDomain("www.externaldomain.com"); //You can give any domain name thats external to current application whcih is under test.
prepareDomain("https://www.southwest.com"); // main site
prepareDomain("https://www.southwesthotels.com") // external domain.

_processScript = processScript

Parameters: script, method
Description: executes a given javascript file.
Example:

processScript("test/com/appvance/ds/api/Imported.js","js");

_setDomain = setDomain;

Parameters: value
Description: DS3 prepares itself with any other external domain apart from the application domain to carry out actions in that.

Both prepareDomain and setDomain are the same.

_selectFrame = selectFrame

Description: Used to restrict proxy commands to only iFrames that match the parameter. The string parameters check if the iframe id, href, class or text contains the provided parameter. See also selectMainFrame.
Example:

selectFrame("secondFrame"); //can select the frame by id,class,title,href,etc..

_selectMainFrame = selectMainFrame

Parameters:value
Description: Selects the Main DS3 Frame:
Example:

navigateTo("http://sahitest.com/demo/iframesTest.htm");
log(getIframesInfo());
selectFrame("[1]");
click(link("linkTest.htm"));
selectMainFrame();
click("Click me");

_selectWindow = selectWindow

Parameters: value
Description: Selects a window with title given to be current one.
Example:

navigateTo("http://sahitest.com/demo/iframesTest.htm");
log(getIframesInfo());
selectFrame("[1]");
click(link("linkTest.htm"));
selectMainFrame();
click("Click me");

_setSilenceAction = setSilenceAction

Parameters: boolean
Description: This causes the logging of the actions to stop or start. Does not affect the log action. Used together with startAction.
Example:

setSilenceAction(true);
navigateTo("http://www.sahitest.com");
startStep("My custom step name");
click(link("/demo"));
setSilenceAction(false);
click(link("a x[1]"));

_startStep = startStep

Parameters: step name
Description: This causes the log of a step with the given custom name. Used together with setSilenceAction.
See Also: setSilenceAction
Example:

setSilenceAction(true);
navigateTo("http://facebook.com");
startStep("Starting login")
setValue(texbox("email"),"abc@example.com");
setValue(textbox("password"),"acb12341!");
submit(button("login"));
setSilenceAction(false);

Verify Functions

You can use verify functions to check if certain conditions are met. The negative outcome of this verification can be user configured to just issue a warning, mark the execution as a failure once whole script is completed or fail the script at the moment of the verification. This configuration is done using the setAssertType functions that receives as parameter the following options: FailtAtEnd, Fail,

Accessor Functions

Assert functions will always trigger a failure if they do not succeed. Verify Functions described above, unlike Assert functions, can be configure not to fail the script execution using the setAssertType function.

_byClassName = byClassName

Parameters: value
Description: Finds an element by class name with given tag name and constrained by given relations
Example:

<div class="bigfont">Some text</div>

_byClassName("bigfont", "DIV")

_byCss = byCss

Parameters: value
Description: This returns the element matching with the specified css
Example:

_navigateTo("http://sahitest.com/");
_click(_link("demo"));
_click(_byCss("a.a.x"));
_click(_link("Back"));

_byId = byId

Parameters: value
Description: This returns the element matching with the specified id
Example 1:

<div id="s2id_autogen2">Add Member</div>

_byId("s2id_autogen2") // points to the above tag. Note that the tagName "div" is not used here.

Example 2:

_navigateTo("http://sahitest.com/demo/linkTest.htm");
_click(_byCss("myLink"));

_byName = byName

Parameters: value
Description: Finds the element with the name of the element. If more than one match, this returns the first matching element.
Example:

navigateTo("http://sahitest.com/");
click(link("demo"));
click(link("Form Test"));
var t1 = byName("t1");

_byJQuery = byJQuery

Parameters: value
Description: Returns the first match based on the input string. Input can be any of jQuery selectors
Example:

byJQuery("#s1Id"); // id selector since u can see # in it
byJQuery("input"); // returns the first match input element
byJQuery(".ac-content"); // returns the first match of element class selector

_bySelenium = bySelenium

Parameters: value
Description: uses selenium locator to get the element
Example:

_navigateTo("http://sahitest.com/demo/");
_click(_bySelenium("css=a.a.x"));
_click(_link("Back"));

_byTagName = byTagName

Parameters: value
Description: Finds the element with the tag name of the element. If more than one match, this returns the first matching element.
Example:

navigateTo("http://sahitest.com/");
click(link("demo"));
click(link("Form Test"));
var text = byTagName("input");

_byXPath = byXPath

Parameters: value
Description: This returns the element matching with the specified XPath
Example:

navigateTo("http://demosite.appvance.com/");
click(byXPath('//*[@class="list-group-item"]'));
click(byXPath('//*[@class="list-group-item"]'));

Test Designer HTTP history functions

_setHistory

Parameters: value
Description: sets the history file which is a zip containing all requests.

Example:

FileClient fs = new FileClient();
fs.setHistory("test/com/appvance/ds/js/cecris/DSLog_NewPRF.zip");

_replayHistory

Description: playback the history file

Example:

_replayHistory();
_wait(2000);
_navigateTo("https://g-mmember-qa1.example.in/");

_clearHistory

Description: clears the history data

Example:

_clearHistory();
_stopHistory();

_stopHistory

Description: stops playing the history
Example:

FileClient fs = new FileClient();
try{
fs.setHistory("test/com/appvance/ds/js/ppd/DSLog.zip");
fs.replayHistory();
fs.processJSFile("test/com/appvance/ds/js/ppd/getAttr.js");
} finally {
fs.clearHistory();
fs.stopHistory();
}

_dontCheckForWS

Parameters: DNS, port
Description: adds the domain and host to the list of domains that should not be checked for HTTPS connection.
Example:

_dontCheckForWS("g-mmember-qa1.copart.in",443);
_dontCheckForWS("cdn.polyfill.io",443);
_dontCheckForWS("smetrics.copart.com",443);
_wait(10000);
_navigateTo("https://g-mmember-qa1.copart.in/");
_wait(1000);
_click(_div("AUCTIONS"));

_printAssertions

Parameters: boolean
Description: enables logging of assertions executed. Mainly used for debugging purposes.
Example:

_printAssertions(true);

Assert Functions

_assertExists = assertExists

Description:
Asset Exists will log the step in the playback logs when the element exists, it will log as a failure if the element does not exist.
Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");
wait(1000);
focus(span("Products[1]"));
assertExists(span("Products[1]"));

_assertNotExists

Parameters: value
Description:
Assert Not Exists will log failures in the logs if the element does exist on the page. This assertion is to check if certain elements that we are looking for does not exist on the page.
Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");
wait(1000);
assertNotExists(span("Products[1]"));
click(link("Clothing"));

_assertTrue = assertTrue

Parameters: value
Description: Assert True will log failures in the logs if the condition evaluates to false.
Example:

navigateTo("http://sahitest.com/demo/training/login.htm");
var val2=_isVisible(_bold("Sahi Training Site"));
assertTrue(val2);

_assertFalse = assertFalse

Parameters: value
Description:
Assert False will log failures in the logs if the condition evaluates to true.
Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://sahitest.com/demo/training/login.htm");
var val1=_getText(_bold("Sahi Training Site"));
assertDoesNotContainText(log(val1);
assertEqual(val1,"Sahi Training Site");
assertNotEqual(val1,"abc");
assertFalse("abc");
var val2=_isVisible(_bold("Sahi Training Site"));
assertTrue(val2);

_assertNull = assertNull

Parameters: value
Description:
Assert Null will log failures to the logs if the value is not null and will continue to playback if the value is null.
Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://sahitest.com/demo/training/login.htm");
assertExists(bold("Sahi Training Site"));
assertNull(null);

_assertNotNull = assertNotNull

Parameters: value
Description:
Assert Not Null will log failure in the logs if the value is null.
Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://sahitest.com/demo/training/login.htm");
assertExists(bold("Sahi Training Site"));
assertNotNull("Sahi Training Site");

_assertEqual = assertEqual = _assertEquals = assertEquals

Parameters: value1, value2
Description:
Assert Equal checks if the expected value is equal to the Actual value.
AssertEqual will log failures to the playback logs if the expected and actual values are not equal. It logs the step when the assertion passes in the logs section.
Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");
click(span("Products[1]"));
assertEqual(span("Home[1]"),"Home");
click(link("Clothing"));

_assertNotEqual = assertNotEqual

Parameters: value1, value2
Description:
As the name suggests, Assert not equal expects the string to be not equal and logs failures in the playback logs when the Expected string matches with the actual string.
Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");
click(span("Products[1]"));
assertNotEqual(span("Home[1]"),"Home");
click(link("Clothing"));

_assertContainsText = assertContainsText

Parameters: fullText, element
Description:
As the name suggests, assert contains text checks for a string in the target element and logs success or failure.
It will log the step details if the assertion passes else it logs as a failure if the expected string or reg-ex is not part of the text content of a given element with a proper explanation and stops the script playback.
Note: Do not use this in an if condition as it does not return any value, and throws an exception if the assertion fails.

Example:

navigateTo("http://demosite.appvance.com/");
click(span("Products[1]"));
assertContainsText("Home",span("Home[1]"));
click(link("Clothing"));

_assertDoesNotContainText = assertDoesNotContainText

Parameters: fullText, element
Description: assertContainsText will do nothing if the expected string/regex is not part of the text content of given element _assertContainsText will log failures to the playback logs if the expected string/regex is part of the text content of given element
Example:

navigateTo("http://demosite.appvance.com/");
click(span("Products[1]"));
assertDoesNotContainText(click(link("Clothing"));

Relational accessor functions

_in

Parameters: accessor
Description:
Example:

link("delete", in(_cell("del2")))

_near | near

Parameters: element
Description: the element should be searched near another element.
Example:

_navigateTo("https://www.apple.com/");
_click(_link("ac-gn-link ac-gn-link-mac"));
_click(_link("ac-gn-link ac-gn-link-iphone",_near(_link("/ipad/"))));
_click(_link("/ipad/"));
_click(_span("chapternav-label[1]",_near(_link("/ipad/"))));

HTTP Level API functions

_get = get

Parameters: url
Description: Executes a GET HTTP call, and returns the HTTP response.
Example:

_prepareDomain("https://www.wikipedia.org");
var response = _get("/");
assertEqual(response.status,200);
assertEqual(response.headers.contentType.first,"text/html");
log("response.getDataString()"+response.getDataString());
assertContains(response.getDataString(),"wikipedia");

_createGet = createGet

Parameters: url
Description: creates an HTTP GET request object. The object can be used to add headers, and to execute it just need to execute an eval.
Example:

_setDomain("http://localhost:9090");
var myGet = _createGet("http://localhost:9090/ds/dyn/basic/echo");
myGet.addUpdateQueryAction("echo","?echo=4&data=7",false);
assertEqual("?echo=4&data=7", myGet.eval().toStringContent());

_createPost = createPost

Parameters: url
Description: creates an HTTP POST request object. The object can be used to add headers, and to execute it just need to execute an eval.
Example:

var myPost = createPost("https://appvancetest.service-now.com:443/api/now/ui/page_timing/7d9bd42f13e71b00ae43721a6144b0b5");
myPost.addHeader("Content-Type", "application/json");
myPost.addHeader("X-Requested-With", "XMLHttpRequest");
myPost.setContentType("application/json");
var resp = myPost.eval().getContentString();

_createPatch = createPatch

Parameters: url

Description: creates an HTTP POST request object. The object can be used to add headers, and to execute it just need to execute an eval.
Example:

var call = createPost("https://appvancetest.service-now.com:443/api/now/ui/page_timing/7d9bd42f13e71b00ae43721a6144b0b5");
call.addHeader("Content-Type", "application/json");
call.addHeader("X-Requested-With", "XMLHttpRequest");
call.setContentType("application/json");
var call = call.eval().getContentString();

_createPut = createPut

Parameters: url
Description: creates an HTTP PUT request object. The object can be used to add headers, and to execute it just need to execute an eval.
Example:

_setDomain("http://localhost:9090");
var call = _createPut("http://localhost:9090/ds/dyn/basic/echo?echo=4&data=7");
log(call.eval().toStringContent());

_createHead = createHead

Parameters: url
Description: creates an HTTP PUT request object. The object can be used to add headers, and to execute it just need to execute an eval.
Example:

_setDomain("http://localhost:9090");
var call = _createHead("http://localhost:9090/ds/dyn/basic/echo?echo=4&data=7");
log(call.eval().toStringContent());

_createOptions = createOptions

Parameters: url
Description: creates an HTTP PUT request object. The object can be used to add headers, and to execute it just need to execute an eval.
Example:

_setDomain("http://localhost:9090");
var call = _createHead("http://localhost:9090/ds/dyn/basic/echo?echo=4&data=7");
log(call.eval().toStringContent());

Functions used by AI processes

_pageStructure= pageStructure(validDomains, type)

Parameters:

validDomains a list of valid domains with its protocol for main windows we want to get the structure. It accepts JSONArray, ArrayList and String[]
type: The type of elements the pageStructure wil provide. Currently, Smarttags, Inputs, Tags, SmarttagsInputs and SmarttagsTags are the valid values to pass.

Description: gets the current page Structure based on DS3 Page Structure.

Example:

addSmartTagsLibrary("demosite.stags");
var pageStructure = pageStructure("https://demosite.appvance.com","Smarttags");

_setCompatibility = setCompatibility

Parameters: boolean
Description: Enables the compatibility mode for sites that run in legacy Internet Explorer versions.

Internet Explorer is no longer supported browser in AIQ.
Example:

_setCompatibility(true);
_navigateTo("http://sahitest.com/");
_click(_link("demo"));

_getCompatibility = getCompatibility

Description:
Example:

_setCompatibility(true);
assertTrue(_getCompatibility());
_navigateTo("https://ApplicationURL");
_setValue(_textbox("user"), $UserName);
_setValue(_password("password"), $Password);
_click(_submit("Login"));
_click(_cell($PatientNumber));

if (var1 == "No data entered \nClick to view CRF") {
_click(_link("Logout"));
} else {
_click(_button(19));
_click(_link("Logout"));
}
_setCompatibility(false);
_assertFalse(_getCompatibility());

Test Designer JS Commands Reference

General functions

_addNetworkLibrary = addNetworkLibrary

_addSmartTagsLibrary = addSmartTagsLibrary

_alert = alert

_clearLastAlert = clearLastAlert

_click = click

_clickXY = clickXY

_cookie = cookie

_createCookie = createCookie

_deleteCookie = deleteCookie

_doubleClick = doubleClick

_doubleClickXY = doubleClickXY

_drag = drag

_drop = drop

_eval

_formSubmit = formSubmit

_focus = focus

_focusWindow = focusWindow

_getAllLinks = getAllLinks

_getAttribute = getAttribute

_getBrowserURL = getBrowserURL

_getChildElementCount = getChildElementCount

_getClipboardText = _getClipboardText

_getComputedStyle = getComputedStyle

_getHtml = getHtml

_getLength = getLength

_getProp = getProp

_getScrollTop = getScrollTop

_getText = getText

_getTextSelenium = getTextSelenium

_title = _getTitle = getTitle

_getValue = getValue

_getSmartTags = getSmartTags

_getSmartTagsLibrary = getSmartTagsLibrary

_grantPermission = grantPermission

_highlight = highlight

_include = include

_isChecked = isChecked

_isVisible = isVisible

_lastAlert = lastAlert

_locker = locker

_log = log = _println;

_mouseDown = mouseDown

_mouseDownXY = mouseDownXY

_mouseOver = mouseOver

_mouseOverXY = mouseOverXY

_mouseOutAll = mouseOutAll

_mouseUp = mouseUp

_mouseUpXY = mouseUpXY

_readCSV = readCSV

_resetUserAgent = resetUserAgent

_retrieve

_rightClick = rightClick

_rightClickXY = rightClickXY

_rteHTML = rteHTML

_rteText = rteText

_rteWrite = rteWrite

_setActionDesc | setActionDesc

_sendKeys = sendKeys

_setAttribute = _setAttribute

_setChecked = setChecked

_setEnabled = _setEnabled

_setFile | setFile

_setFile2 | setFile2

_setFile3 | setFile3

_setFile4 | setFile4

_setFile5 | setFile5

_setFindOnlyEnabled = setFindOnlyEnabled

_setFindOnlyVisible = setFindOnlyVisible

_setHTML = setHTML

_setScrollTop = setScrollTop

_setSearchRetries = setSearchRetries

_setSelected = setSelected

_setUserAgent = setUserAgent

_setValue = setValue

_popup = popup

_writeText = writeText

_wait = wait (Fixed duration)

_wait = wait (Conditional wait)