Skip to content

Global

Global object. Use it to perform actions not related to a particular object. You do not need to record or learn this object, it is always automatically available in any test.

Action Summary

Action Description
_DoLoadObjects
DoAnalogPlay Performs Analog Playback of events recorded in a file.
DoAppActivate Activates window with the specified title.
DoClick Performs mouse click at the current position.
DoCmd Executes a BAT/CMD file specified in cmdLine.
DoCompareJsObjects Compares two JavaScript objects and prints differences to the report.
DoDecrypt Decrypts a piece of text.
DoEncrypt Encrypts a piece of text.
DoFindProcess Finds a process by executable path and, maybe, part of command line.
DoHorizontalScroll Simulates mouse horizontal wheel scroll gesture.
DoInvokeTest Invokes another test (aka subtest).
DoInvokeTestParallel Executes specified test in few parallel threads.
DoKillByName Terminates a given process.
DoKillByPid Terminates a given process or the last process created by DoLaunch if 'pid' is not specified.
DoLaunch Executes a command specified by the cmdLine parameter.
DoLoadObjects Loads objects from external .objects.js file.
DoMaximizeWindow Maximizes window that matches given title and class name.
DoMessageBox Shows message box (popup message) to a user.
DoMinimizeWindow Minimizes window that matches given title and class name.
DoMouseMove Moves mouse to the specified position.
DoPlayManual Executes a manual test.
DoRestoreWindow Restores window that matches given title and class name.
DoRunTest Executes a given test in isolated environment (new process is created).
DoRunTestSet Executes a test set.
DoSendKeys Sends series of keystrokes to a currently focused application.
DoSendText Sends text to the active application as is (while SendKeys also supports sending special keys).
DoSetScreenResolution Sets screen resolution.
DoSleep Delays/pauses execution for a given number of milliseconds (1000 = 1 second).
DoTrim Strips leading and trailing white-space from a string, replaces sequences of whitespace characters by a single space, and returns the resulting string.
DoTypePassword Types encrypted password into a control which has a focus.
DoVerticalScroll Simulates mouse vertical wheel scroll gesture.
DoWaitFor Waits for object specified by objectId to become available.
DoWaitForProperty Waits for specified value of object's property.
DoWaitForWindow Waits for window specified by title/class name to become available.
GetClipboardText Reads text stored in the windows clipboard.
GetCurrentDir Gets current directory path.
GetFileAsByteArray Reads file and returns its content as array of bytes.
GetFirstDayOfWeek Returns first day of week for current user.
GetFullPath Constructs an absolute file name using working directory (WORKDIR) of the test.
GetOsOwner Reads OS registered owner from the registry.
GetOsPath Returns OS root path.
GetOsType Reads OS type from the registry.
GetOsVersion Reads OS service pack version from the registry.
GetProperty Reads property value from file 'optConfig' if set, or from %WORKDIR%\Config.json otherwise.
GetRapiseVersion Reads Rapise version.
GetSpecialFolderPath Returns path to a special folder specified by one of possible values.
GetTestCasePath Finds full path to a Test Case.
SetClipboardText Updates clipboard text
SetConfigPath Set default path for config file instead of default %WORKDIR%\Config.json.
SetFileAsByteArray Creates or rewrites file and fills with contents of the provided byte array.
SetProperty Sets property value to file 'optConfig' if set, or to %WORKDIR%\Config.json otherwise.
SetWindowPosition Change position of the window with the specified title (and class, if specified).
SetWindowSize Change size of the window with the specified title (and class, if specified).

Action Detail

_DoLoadObjects

Global._DoLoadObjects(objectsFilePath, checkDuplicates, addToMap)

Parameters:

Name Type Description
objectsFilePath string
checkDuplicates bool
addToMap bool

DoAnalogPlay

Performs Analog Playback of events recorded in a file.

Global.DoAnalogPlay(path, left, top)

Parameters:

Name Type Description
path string This is a path to a file with recorded analog events.
left number X-coordinate of top-left corner of the analog area.
top number Y-coordinate of the top-left corner of the analog area.

DoAppActivate

Activates window with the specified title. I.e. Global.DoAppActivate("Calculator") will bring running instance (if any) of Windows Calculator to the foreground.

Global.DoAppActivate(title)

Parameters:

Name Type Description
title string Title of an application window.

See:

MSDN Article for AppActivate

DoClick

Performs mouse click at the current position.

Global.DoClick(clickType)

Parameters:

Name Type Description
clickType string Type of click, can be one of "L" - left click, "LD" - double left click, "R" - right click, "RD" - double right click, "M" - middle click, "MD" - double middle click, "N" - don't click Possible values: "L", "LD", "R", "RD", "M", "MD", "N"
Optional, Default: "L".

DoCmd

Executes a BAT/CMD file specified in cmdLine. Optionally one may specify working dir. Requires Rapise 6.4+

Global.DoCmd(cmdLine, wrkDir, wait, show)

Parameters:

Name Type Description
cmdLine string Command line to execute. Contains path to a batch file and parameters.
wrkDir string Working directory. By default it is a directory of the test.
Optional, Default: ".".
wait boolean If true - Wait until batch process exit. If false - immediately proceed to the next test steps.
Optional, Default: "true".
show boolean If true - maximize the command line window. If false - minimize the command line window.
Optional, Default: "true".

Returns:

number: Error code returned by the batch process. 0 - indicates success if wait is true.

DoCompareJsObjects

Compares two JavaScript objects and prints differences to the report.

Global.DoCompareJsObjects(msg, obj1, obj2)

Parameters:

Name Type Description
msg string Message to write into report.
obj1 object First object.
obj2 object Second object.

Returns:

boolean: 'true' if two objects are equal, 'false' otherwise.

DoDecrypt

Decrypts a piece of text.

Global.DoDecrypt(encryptedText)

Parameters:

Name Type Description
encryptedText string Text to decrypt.

Returns:

string: Decrypted text.

DoEncrypt

Encrypts a piece of text.

Global.DoEncrypt(plainText)

Parameters:

Name Type Description
plainText string Text to encrypt.

Returns:

string: Encrypted text.

DoFindProcess

Finds a process by executable path and, maybe, part of command line. Requires Rapise 8.1.29.39+

Global.DoFindProcess(exeName, partOfCmd)

Parameters:

Name Type Description
exeName string Command line to an executable with parameters.
partOfCmd string Command line (or regular expression)
Optional, Default: "".

Returns:

number: ID of the new process (positive number) or an error code (negative number)

DoHorizontalScroll

Simulates mouse horizontal wheel scroll gesture. Requires Rapise 6.5+

Global.DoHorizontalScroll(scrollAmountInClicks)

Parameters:

Name Type Description
scrollAmountInClicks number The amount to scroll in clicks. A positive value indicates that the wheel was rotated to the right; a negative value indicates that the wheel was rotated to the left.

DoInvokeTest

Invokes another test (aka subtest). The subtest should have the set of libraries as calling test. Otherwise it may lead to a conflict.

Global.DoInvokeTest(pathToTest, optionalParams)

Parameters:

Name Type Description
pathToTest string Path to .sstest file.
optionalParams object Parameters to pass into entry point Test() function of the subtest. I.e. it is called as Test(optionalParams).
Optional, Default: "[object Object]".

Returns:

boolean: 'true' if the test passed, 'false' otherwise.

DoInvokeTestParallel

Executes specified test in few parallel threads. Pass additional arguments in 'threads' param

DoInvokeTestParallel(
    "t2/t2.sstest",
    {
        "THR01": {
            g_browserLibrary: 'Selenium - Chrome'
        },
        "THR02": {
            g_browserLibrary: 'Selenium - Edge'
        }
    }
);
Global.DoInvokeTestParallel(testPath, threads, commonParams)

Parameters:

Name Type Description
testPath string Path to .sstest to execute.
threads object Structure, defining parallel threads to execute.
commonParams object Object containing {name:'value',...} pairs to be passed as parameters to all tests.
Optional.

Returns:

boolean: true, if execution finished with exit code 0 (all tests executed successfully)

DoKillByName

Terminates a given process.

Global.DoKillByName(processName)

Parameters:

Name Type Description
processName string Executable name to kill (such as 'iexplore.exe').

Returns:

boolean: 'true' if the process was terminated, 'false' otherwise.

DoKillByPid

Terminates a given process or the last process created by DoLaunch if 'pid' is not specified.

Global.DoKillByPid(pid)

Parameters:

Name Type Description
pid number ID of the process.
Optional.

Returns:

boolean: 'true' if the process was terminated, 'false' otherwise.

DoLaunch

Executes a command specified by the cmdLine parameter. Use to start external desktop apllications. Optionally specify the working dir and window name to attach if the application is already running. Example: Global.DoLaunch("calc.exe")

Global.DoLaunch(cmdLine, wrkDir, attachIfExists, attachToWindow, wait, parentProcess)

Parameters:

Name Type Description
cmdLine string Command line with the executable file name/path and parameters.
wrkDir string Working directory. By default it is a directory of the test.
Optional, Default: ".".
attachIfExists boolean Try to find a process with the same executable path instead of launching it.
Optional, Default: "false".
attachToWindow string When attachIfExists is 'true' this parameter may be used to specify top window name to find a process to attach to.
Optional, Default: "".
wait bool Try to find a process with the same executable path instead of launching it. Requires Rapise 8.1.29.39+
Optional, Default: "false".
parentProcess number | string Optional parent process. By default parent process will be a current script's process. May be ID or executable path to the process. Requires Rapise 8.1.29.39+
Optional, Default: "0".

Returns:

number: ID of the new process (positive number) or an error code (negative number)

DoLoadObjects

Loads objects from external .objects.js file.

Global.DoLoadObjects(objectsFilePath)

Parameters:

Name Type Description
objectsFilePath string Path to *.objects.js file.

Returns:

object: saved_script_objects or null if the load was unsuccessful.

DoMaximizeWindow

Maximizes window that matches given title and class name. Requires Rapise 7.2+

Global.DoMaximizeWindow(title, className)

Parameters:

Name Type Description
title string Title of a window to search for. Use exact value or regex: expression.
className string Class name of a window to search for. Use exact value or regex: expression. Empty or null value matches any class name.
Optional, Default: "".

Returns:

boolean: true if window was found, otherwise false.

DoMessageBox

Shows message box (popup message) to a user.

buttons is a value or a sum of values that specifies the number and type of buttons to display, the icon style to use, the identity of the default button, and the modality of the message box. Default value is 0.

    0 = vbOKOnly - OK button only
    1 = vbOKCancel - OK and Cancel buttons
    2 = vbAbortRetryIgnore - Abort, Retry, and Ignore buttons
    3 = vbYesNoCancel - Yes, No, and Cancel buttons
    4 = vbYesNo - Yes and No buttons
    5 = vbRetryCancel - Retry and Cancel buttons
    16 = vbCritical - Critical Message icon
    32 = vbQuestion - Warning Query icon
    48 = vbExclamation - Warning Message icon
    64 = vbInformation - Information Message icon
    0 = vbDefaultButton1 - First button is default
    256 = vbDefaultButton2 - Second button is default
    512 = vbDefaultButton3 - Third button is default
    768 = vbDefaultButton4 - Fourth button is default
    0 = vbApplicationModal - Application modal (the current application will not work until the user responds to the message box)
    4096 = vbSystemModal - System modal (all applications wont work until the user responds to the message box)

We can divide the buttons values into four groups: The first group (0–5) describes the buttons to be displayed in the message box, the second group (16, 32, 48, 64) describes the icon style, the third group (0, 256, 512, 768) indicates which button is the default; and the fourth group (0, 4096) determines the modality of the message box. When adding numbers to create a final value for the buttons parameter, use only one number from each group.

The function returns a number representation of a button pressed by user:

    vbOK = 1 - OK button was clicked. 
    vbCancel = 2 - Cancel button was clicked. 
    vbAbort = 3 - Abort button was clicked. 
    vbRetry = 4 - Retry button was clicked. 
    vbIgnore = 5 - Ignore button was clicked. 
    vbYes = 6 - Yes button was clicked. 
    vbNo = 7 - No button was clicked. 
Global.DoMessageBox(prompt, buttons)

Parameters:

Name Type Description
prompt string Message to display.
buttons number Buttons to show. Possible values: 0, 1, 2, 3, 4, 5, 16, 32, 48, 64, 0, 256, 512, 768, 0, 4096
Optional, Default: "0".

Returns:

number: A number representation of a button pressed by user.

DoMinimizeWindow

Minimizes window that matches given title and class name. Requires Rapise 7.2+

Global.DoMinimizeWindow(title, className)

Parameters:

Name Type Description
title string Title of a window to search for. Use exact value or regex: expression.
className string Class name of a window to search for. Use exact value or regex: expression. Empty or null value matches any class name.
Optional, Default: "".

Returns:

boolean: true if window was found, otherwise false.

DoMouseMove

Moves mouse to the specified position.

Global.DoMouseMove(x, y, duration)

Parameters:

Name Type Description
x number Absolute X-coordinate of the target mouse position.
y number Absolute Y-coordinate of the target mouse position.
duration number Mouse move duration (milliseconds). If 0 - do immediate move.
Optional, Default: "0".

DoPlayManual

Executes a manual test. Results are shown in the report of the calling test.

Global.DoPlayManual(rmtFilePath, rmtParams)

Parameters:

Name Type Description
rmtFilePath string Path to manual test (.rmt) file.
rmtParams object Additional parameters to pass to the manual test executor.
Optional.

Returns:

boolean: 'true' if the manual test passed, 'false' otherwise.

DoRestoreWindow

Restores window that matches given title and class name. Requires Rapise 7.2+

Global.DoRestoreWindow(title, className)

Parameters:

Name Type Description
title string Title of a window to search for. Use exact value or regex: expression.
className string Class name of a window to search for. Use exact value or regex: expression. Empty or null value matches any class name.
Optional, Default: "".

Returns:

boolean: true if window was found, otherwise false.

DoRunTest

Executes a given test in isolated environment (new process is created). Requires Rapise 8.1+.

Global.DoRunTest(testPath, optionalParams)

Parameters:

Name Type Description
testPath string Path to .sstest to execute.
optionalParams object Object containing {name:'value',...} pairs to be passed as parameters to the test.
Optional.

DoRunTestSet

Executes a test set. Results are shown in the report of the calling test.

Global.DoRunTestSet(testSetFilePath, testSetParams)

Parameters:

Name Type Description
testSetFilePath string Path to a test set file.
testSetParams object Additional parameters to pass for each test in the test set.
Optional.

DoSendKeys

Sends series of keystrokes to a currently focused application.

Global.DoSendKeys(keys)

Parameters:

Name Type Description
keys string Keystrokes, including special characters and control symbols.

DoSendText

Sends text to the active application as is (while SendKeys also supports sending special keys). Requires Rapise 6.5+

Global.DoSendText(text)

Parameters:

Name Type Description
text string Text to input.

DoSetScreenResolution

Sets screen resolution. Use to run UI tests in unattended RDP sessions.

Global.DoSetScreenResolution(width, height)

Parameters:

Name Type Description
width number Screen width in pixels
height number Screen height in pixels

DoSleep

Delays/pauses execution for a given number of milliseconds (1000 = 1 second). Use to wait given amount of time and then continue running the test.

Global.DoSleep(millis)

Parameters:

Name Type Description
millis number Number of milliseconds to wait/sleep.

DoTrim

Strips leading and trailing white-space from a string, replaces sequences of whitespace characters by a single space, and returns the resulting string. Whitespace characters are [\f\n\r\t\v\u00a0\u1680\u180e\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff].

Global.DoTrim(str, global, trimChars)

Parameters:

Name Type Description
str string String to trim.
global boolean If 'true' then global trim is performed (whitespaces in the middle are substituted with a single space). If 'false' only ends are trimmed.
Optional, Default: "false".
trimChars string String with each char to be subject for trim.
Optional.

Returns:

string: Trimmed string.

DoTypePassword

Types encrypted password into a control which has a focus.

Global.DoTypePassword(encryptedPassword)

Parameters:

Name Type Description
encryptedPassword string Password to type. Encrypted.

Returns:

string: 'true'

DoVerticalScroll

Simulates mouse vertical wheel scroll gesture. Requires Rapise 6.5+

Global.DoVerticalScroll(scrollAmountInClicks)

Parameters:

Name Type Description
scrollAmountInClicks number The amount to scroll in clicks. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user.

DoWaitFor

Waits for object specified by objectId to become available. Function returns if object was found or timeout.

Global.DoWaitFor(objectId, timeout, sleepTimeIfFound)

Parameters:

Name Type Description
objectId objectid Id of an object to wait for.
timeout number Maximum time to wait (milliseconds).
Optional, Default: "10000".
sleepTimeIfFound number Wait time (milliseconds) after object is found.
Optional, Default: "0".

Returns:

SeSObject |
boolean: Found object or 'false'.

DoWaitForProperty

Waits for specified value of object's property. Function returns object handle if object was found and specified property equals to desired value or 'false' in the case of timeout.

propValue may be a callback function:

function(value)
{
    if (value != 'some text')
    {
        // if the condition is met
        return true;
    }
    return false;
}
Use the callback if you need to check more complex condition than equality.

Global.DoWaitForProperty(obj, getterName, propValue, timeout, params)

Parameters:

Name Type Description
obj objectid | SeSObject Id of an object to wait for or object itself.
getterName string Property getter function name.
propValue string | number | boolean | function Desired property value or callback function (see description).
timeout number Maximum time to wait (milliseconds).
Optional, Default: "10000".
params array | string | number | boolean Parameters for property getter function.
Optional.

Returns:

SeSObject |
boolean: Found object or 'false'.

DoWaitForWindow

Waits for window specified by title/class name to become available. Function returns if window was found or timeout. Requires Rapise 7.2+

Global.DoWaitForWindow(title, className, timeout)

Parameters:

Name Type Description
title string Title of a window to wait for. Use exact value or regex: expression.
className string Class name of a window to wait for. Use exact value or regex: expression. Empty or null value matches any class name.
Optional, Default: "".
timeout number Maximum time to wait (milliseconds).
Optional, Default: "10000".

Returns:

boolean: true if window was found, otherwise false.

GetClipboardText

Reads text stored in the windows clipboard.

Global.GetClipboardText()

Returns:

string: Clipboard text

GetCurrentDir

Gets current directory path.

Global.GetCurrentDir()

Returns:

string: Path of the current directory.

GetFileAsByteArray

Reads file and returns its content as array of bytes. May be useful for binary files and for passing data to web services.

Global.GetFileAsByteArray(fileName)

Parameters:

Name Type Description
fileName string Filename to read (recommended to use absolute file name).

Returns:

object: Array of bytes.

GetFirstDayOfWeek

Returns first day of week for current user.

Global.GetFirstDayOfWeek()

Returns:

number: 0 - Sunday, 1 - Monday.

GetFullPath

Constructs an absolute file name using working directory (WORKDIR) of the test.

Global.GetFullPath(fileName)

Parameters:

Name Type Description
fileName string Name of a file.

Returns:

string: Absolute file name.

GetOsOwner

Reads OS registered owner from the registry.

Global.GetOsOwner()

Returns:

string: OS registered owner.

GetOsPath

Returns OS root path.

Global.GetOsPath()

Returns:

string: OS root path without the trailing backslash, e.g. 'C:\Windows'.

GetOsType

Reads OS type from the registry.

Global.GetOsType()

Returns:

string: OS type string.

GetOsVersion

Reads OS service pack version from the registry.

Global.GetOsVersion()

Returns:

string: Service pack version.

GetProperty

Reads property value from file 'optConfig' if set, or from %WORKDIR%\Config.json otherwise.

Global.GetProperty(name, defValue, configPath)

Parameters:

Name Type Description
name string Name of a property
defValue string | number | boolean Default value to return if property does not exist
Optional.
configPath string Path to options file (.json, .xlsx).
Optional.

Returns:

string |
number |
boolean: Property value. If a property does not exist then defValue is returned. If defValue is not set then null is returned.

GetRapiseVersion

Reads Rapise version. If 'optMinVersion' is specified, then returns true/false depending on 'optMinVersion' less than actual Rapise version.

Global.GetRapiseVersion(optMinVersion)

Parameters:

Name Type Description
optMinVersion string Minimum version to check
Optional.

Returns:

string: Rapise Version (i.e. 6.3.18.5), 'true' if optMinVersionRapise version.

GetSpecialFolderPath

Returns path to a special folder specified by one of possible values.

Possible values:
ApplicationDataThe directory that serves as a common repository for application-specific data for the current roaming user.
CommonApplicationDataThe directory that serves as a common repository for application-specific data that is used by all users.
CommonProgramFilesThe directory for components that are shared across applications.
CookiesThe directory that serves as a common repository for Internet cookies.
DesktopThe logical Desktop rather than the physical file system location.
DesktopDirectoryThe directory used to physically store file objects on the desktop.
FavoritesThe directory that serves as a common repository for the user's favorite items.
HistoryThe directory that serves as a common repository for Internet history items.
InternetCacheThe directory that serves as a common repository for temporary Internet files.
LocalApplicationDataThe directory that serves as a common repository for application-specific data that is used by the current, non-roaming user.
MyComputerThe "My Computer" folder.
MyDocumentsThe "My Documents" folder.
MyMusicThe "My Music" folder.
MyPicturesThe "My Pictures" folder.
PersonalThe directory that serves as a common repository for documents.
ProgramFilesThe program files directory.
ProgramsThe directory that contains the user's program groups.
RecentThe directory that contains the user's most recently used documents.
SendToThe directory that contains the Send To menu items.
StartMenuThe directory that contains the Start menu items.
StartupThe directory that corresponds to the user's Startup program group.
SystemThe System directory.
TemplatesThe directory that serves as a common repository for document templates.
Global.GetSpecialFolderPath(folder)

Parameters:

Name Type Description
folder string Folder Id. Possible values: "ApplicationData", "CommonApplicationData", "CommonProgramFiles", "Cookies", "Desktop", "DesktopDirectory", "Favorites", "History", "InternetCache", "LocalApplicationData", "MyComputer", "MyDocuments", "MyMusic", "ProgramFiles", "Programs", "Recent", "SendTo", "StartMenu", "Startup", "System", "Templates"

Returns:

string: System specified folder path without the trailing backslash, e.g. 'C:\Program Files'.

GetTestCasePath

Finds full path to a Test Case. The Path is resolved for file path or for TC alias name.

Global.GetTestCasePath(pathToTest)

Parameters:

Name Type Description
pathToTest string Path to .sstest file or Test Case alias name.

Returns:

string: path to .sstest

SetClipboardText

Updates clipboard text

Global.SetClipboardText(txt)

Parameters:

Name Type Description
txt string Text to store into clipboard.

Returns:

boolean: 'true' when clipboard is set.

SetConfigPath

Set default path for config file instead of default %WORKDIR%\Config.json. Supports .xlsx and .json file format. This path is used by default for further calls to Global.GetProperty and Global.SetProperty

Global.SetConfigPath(defPath)

Parameters:

Name Type Description
defPath string New config path, i.e. %WORKDIR%\Config.xlsx

Returns:

string: Previous config path

SetFileAsByteArray

Creates or rewrites file and fills with contents of the provided byte array.

Global.SetFileAsByteArray(fileName, bytes)

Parameters:

Name Type Description
fileName string Filename to write (recommended to use absolute file name).
bytes array Array of bytes to write.

Returns:

number: Number of bytes written.

SetProperty

Sets property value to file 'optConfig' if set, or to %WORKDIR%\Config.json otherwise. If the file does not exist it will be created.

Global.SetProperty(name, value, configPath)

Parameters:

Name Type Description
name string Name of a property.
value string | number | boolean Value to set.
configPath string Path to options file (.json, .xlsx).
Optional.

Returns:

boolean: 'true' if property value set successfully, 'false' otherwise.

SetWindowPosition

Change position of the window with the specified title (and class, if specified).

Global.SetWindowPosition(x, y, windowTitle, windowClass)

Parameters:

Name Type Description
x number Position left offset in pixels.
y number Position top offset in pixels.
windowTitle string String or regular expression to match window title.
windowClass string String or regular expression to match window class.
Optional, Default: "regex:.*".

SetWindowSize

Change size of the window with the specified title (and class, if specified).

Global.SetWindowSize(width, height, windowTitle, windowClass)

Parameters:

Name Type Description
width number New width in pixels.
height number New height in pixels.
windowTitle string String or regular expression to match window title.
windowClass string String or regular expression to match window class.
Optional, Default: "regex:.*".