org.safs.selenium.webdriver

Class SeleniumPlus

java.lang.Object

org.safs.SAFSPlus

org.safs.selenium.webdriver.SeleniumPlus

Direct Known Subclasses:

AISearchBase, GroovyBridge, SAFSActions, SAFSCommands, SPJVMInjector, WDSPC

public abstract class SeleniumPlus
extends SAFSPlus

 NOTE 1: Auto-evaluated expression.
 As SeleniumPlus inherits from SAFS, so it has the ability to process string as an expression.
 For example, "36+9", "25*6" will be calculated as "45", "150" automatically; "^" is considered
 as the leading char of a variable, hence "^var" will be considered as a variable "var",
 if variable "var" exists, then "^var" will be replaced by its value, otherwise replaced by empty string "".

 This ability is very useful for user, but sometimes it will cause UN-EXPECTED result during calling
 SeleniumPlus's API. For example, user wants to input a string "this is a combined-word" to an EditBox,
 the EditBox will receive "this is a 0", which is not an expected result; user wants to select all
 text of an EditBox, he uses "Ctrl+a" by calling SeleniumPlus.TypeKeys("^a") and he finds that doesn't
 work (the reason is that "^a" is parsed to "", because "^a" is considered as variable).

 To avoid the problem caused by arithmetic char "+ - * /", we can call API Misc.Expressions(false) to
 turn off the parse of an expression.
 
 Misc.Expressions(false);
 SeleniumPlus.TypeChars("this is a combined-word");
 ComboBox.CaptureItemsToFile(combobox, "ComboBoxData.txt", "UTF-8");
 
 To avoid the problem caused by caret ^ or by arithmetic char "+ - * /", we can double-quote the parameter
 
 SeleniumPlus.TypeKeys("\"^p\""));
 SeleniumPlus.TypeKeys(quote("^p")));//quote is a static method provided by SeleniumPlus
 SeleniumPlus.TypeChars(quote("this is a combined-word"));
 

 NOTE 2: File path deducing.
 In SeleniumPlus, there are some APIs like CaptureXXXToFile, VerifyXXXToFile, they require file-path as parameter.
 As our doc is not very clear, user may confuse with the file-path parameter. Let's make it clear:
   There are 2 types of file, the test-file and bench-file. User can provide absolute or relative file-path for them.
   If it is absolute, there is not confusion.
   If it is relative, we will combine it with a base-directory to form an absolute file. The base-directory depends
   on the type of file (test or bench):
     if it is test-file, the base-directory will be the test-directory, /Actuals/
     if it is bench-file, the base-directory will be the bench-directory, /Benchmarks/
     After the combination, the combined-file-name will be tested, if it is not valid, the project-directory will
     be used as base-directory.


 NOTE 3: DDVariable
 To use DDVariable ability, PLEASE remember to turn on the Expression by Misc.Expressions(true);
 The DDVariable is a variable reference, it can be expressed by a leading symbol ^ and the "variable name".
 For example:
 ^user.name
 ^user.password

 DDVariable can be used along with an assignment or by itself, example as following:
 
 Misc.Expressions(true);
 //set value "UserA" to variable "user.name", set "Password1" to variable "user.password"
 Misc.SetVariableValues("^user.name=UserA","^user.password=Password1");
 //input the value of variable "user.name"
 Component.InputCharacters(Map.AUT.UserInput, "^user.name");
 //input the value of variable "user.password"
 Component.InputCharacters(Map.AUT.PassWord, "^user.password");
 

 NOTE 4: a known issue about clicking on wrong item
 Please to TURN OFF the browser's status bar.

 

For more info on command-line options, see main(String[]).

Author:

Carl Nagle

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SeleniumPlus.Assert A set of assertions methods for tests.
static class	SeleniumPlus.CheckBox Wrapper class providing APIs to handle CheckBox keywords, like Check, UnCheck.
static class	SeleniumPlus.ComboBox Wrapper class providing APIs to handle ComboBox keywords, like Select, ShowList, SetTextValue etc.
static class	SeleniumPlus.Component Wrapper class to handle GenericMasterFunctions Reference and GenericObjectFunctions Reference, like VerifyProperty, IsPropertyExist etc.
static class	SeleniumPlus.Counters Wrapper class providing APIs to handle DriverCounter keywords, like StartTestSuite, StartCounter, LogCounterInfo etc.
static class	SeleniumPlus.EditBox Wrapper class providing APIs to handle EditBox keywords, like SetTextValue, SetTextCharacters etc.
static class	SeleniumPlus.Files Wrapper class providing APIs to handle File keywords, like OpenFile, ReadFileLine etc.
static class	SeleniumPlus.ListView Wrapper class providing APIs to handle ListView keywords, like ClickIndex, VerifyListContains etc.
static class	SeleniumPlus.Logging Wrapper class providing APIs to handle Logging keywords, like LogMessage, LogTestWarning etc.
static class	SeleniumPlus.Menu Wrapper class providing APIs to handle MenuBar/Menu keywords, like SelectMenuItem, VerifyMenuItemContains etc.
static class	SeleniumPlus.Misc Convenience class for miscellaneous Driver Commands. This is a sub-class of SAFSPlus.Misc and it provides more convenient wrapper APIs related to Selenium. The class SAFSPlus.Misc is a sub-class of DriverCommand.
static class	SeleniumPlus.Rest Wrapper class providing APIs to handle TIDRestFunctions Reference and DriverRestCommands Reference, like RestGetBinary, RestStoreResponse etc.
static class	SeleniumPlus.ScrollBar Wrapper class providing APIs to handle ScrollBar keywords, like OneDown, PageDown, PageUp etc.
static class	SeleniumPlus.Strings Wrapper class providing APIs to handle String keywords, like Compare, GetMultiDelimitedField etc.
static class	SeleniumPlus.TabControl Wrapper class providing APIs to handle TabControl keywords, like ClickTab, SelectTabIndex etc.
static class	SeleniumPlus.Tree Wrapper class providing APIs to handle Tree keywords, like ClickTextNode, ExpandTextNode etc.
static class	SeleniumPlus.WDTimeOut This class provides some static methods to set Selenium WebDriver's timeout thread-safely.
static class	SeleniumPlus.Window Wrapper class to handle Window keywords, like Maximize, Minimize, SetPosition etc.

Nested classes/interfaces inherited from class org.safs.SAFSPlus

SAFSPlus.DriverCommand

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	PRODUCT_DESCRIPTION 'The driver with embedded selenium engine to run test script in Java.'
static java.lang.String	PRODUCT_NAME 'SeleniumPlus'
static java.lang.String	PRODUCT_VERSION '1.0'
static EmbeddedHookDriverRunner	Runner The Runner object providing access to the underlying Selenium Engine.
static java.lang.String	TEMP_SELENIUM_PLUS_RS_VAR

Fields inherited from class org.safs.SAFSPlus

_autorun, _autorunClassProvided, _injectDataAwareness, _isInjected, _isSPC, _junit, allowExit, ARG_AUTORUN, ARG_AUTORUN_CLASS, ARG_JUNIT, ARG_SAFSVAR, DefaultRunner, exitCode, normalizeTextForInput, prevResults, RELATIVE_TO_PARENT, RELATIVE_TO_SCREEN, springApplicationContext

Constructor Summary

Constructors

Constructor and Description
SeleniumPlus() Internal framework use only.

Method Summary

Modifier and Type	Method and Description
static void	AbortTest(java.lang.String reason) Abort running test flow.
static boolean	AltLeftDrag(Component comp, java.lang.String coordinates) A Alt left mouse drag is performed on the object based on the stored coordinates relative to this object.
static boolean	Click(Component comp, java.lang.String... params) Click on any visible component.
static boolean	ClickUnverified(Component comp, java.awt.Point offset) Click on any visible component without verification. This API will not guarantee that the click does happen, it simply clicks.
static boolean	CtrlAltLeftDrag(Component comp, java.lang.String coordinates) A Ctrl Alt left mouse drag is performed on the object based on the stored coordinates relative to this object.
static boolean	CtrlClick(Component comp, java.lang.String... params) Control-Click on any visible component.
static boolean	CtrlLeftDrag(Component comp, java.lang.String coordinates) A Ctrl left mouse drag is performed on the object based on the stored coordinates relative to this object.
static boolean	CtrlRightClick(Component comp, java.lang.String... params) Control-Right-Click on any visible component.
static boolean	CtrlShiftLeftDrag(Component comp, java.lang.String coordinates) A Ctrl Shift left mouse drag is performed on the object based on the stored coordinates relative to this object.
static java.lang.String	deduceFilterAreas(Component parent, Component[] childrenToMask) Generate a "filter string" (Filter=x1,y1,x2,y2 x1,y1,x2,y2) according to a parent component and an array of children. The deduced "filter string" can be used in GetGUIImage(org.safs.model.Component, String, String...) or VerifyGUIImageToFile(org.safs.model.Component, String, String...).
static boolean	DoubleClick(Component comp, java.lang.String... params) Double-Click on any visible component.
static java.lang.Object	executeAsyncScript(java.lang.String script, java.lang.Object... scriptParams) Following explanations come from Selenium Java Doc. Execute an asynchronous piece of JavaScript in the context of the currently selected frame or window.
static boolean	ExecuteScript(Component comp, java.lang.String script, java.lang.String... scriptParams) Execute a simple piece of javascript on component synchronously.
static java.lang.Object	executeScript(java.lang.String script, java.lang.Object... scriptParams) Following explanations come from Selenium Java Doc. Executes JavaScript synchronously in the context of the currently selected frame or window.
static boolean	GetGUIImage(Component comp, java.lang.String fileName, java.lang.String... params) Take a screenshot of windows or component. See Detailed Reference
static boolean	GetGUIImage(Component comp, java.lang.String fileName, java.lang.String subArea, Component[] childrenToMask) Take a screenshot of windows or component and filter some children inside.
static org.openqa.selenium.WebElement	getObject(Component component) Find the WebElement according to the SAFS Component. This method will use the last webdriver as search context to find element, if user wants to find an element within an other context, please call #getObject(SearchContext, String)
static org.openqa.selenium.WebElement	getObject(org.openqa.selenium.SearchContext sc, Component component) Find the WebElement according to the SAFS Component.
static java.lang.String	GetVariableValue(java.lang.String variableName) Convenience routine to retrieve the value of a SAFS Variable stored in SAFSVARS.
static boolean	Highlight(boolean OnOff) Highlight object
static boolean	HoverScreenLocation(java.lang.String coordination, java.lang.String... optionals) Hover the mouse over a specified screen location.
static boolean	LeftDrag(Component comp, java.lang.String coordinates) A left mouse drag is performed on the object based on the stored coordinates relative to this object.
static void	main(java.lang.String[] args) Internal framework use only.
static boolean	Pause(int seconds) Pause test-case flow in seconds.
static boolean	PrintTestCaseSummary(java.lang.String tcname) Stop capturing test activity counts for a specific application feature or test-case if it is still active, then print a summary report of all tests counted, passed, failed, and skipped, etc...
static boolean	PrintTestSuiteSummary(java.lang.String suitename) Stop capturing test activity counts for the overall suite of tests if it is still active, then print a summary report of all counted, passed, failed, and skipped tests etc...
static boolean	RightClick(Component comp, java.lang.String... params) Right-Click on any visible component.
static boolean	RightDrag(Component comp, java.lang.String coordinates) A right mouse drag is performed on the object based on the stored coordinates relative to this object.
static boolean	SetVariableValue(java.lang.String variableName, java.lang.String variableValue) Convenience routine to set the value of a SAFS Variable stored in SAFSVARS. The act of logging success or failure will change prevResults.
static boolean	ShiftClick(Component comp, java.lang.String... params) Shift-Click on any visible component.
static boolean	ShiftLeftDrag(Component comp, java.lang.String coordinates) A Shift left mouse drag is performed on the object based on the stored coordinates relative to this object.
static boolean	StartTestCase(java.lang.String tcname) Start capturing test activity counts for a specific application feature or test-case.
static boolean	StartTestSuite(java.lang.String suitename) Start capturing test activity counts for the named test suite.
static boolean	StartWebBrowser(java.lang.String URL, java.lang.String BrowserID, java.lang.String... params) Start WebBrowser See Detailed Reference
static boolean	StopTestCase(java.lang.String tcname) Stop capturing test activity counts for a specific application feature or test-case.
static boolean	StopWebBrowser(java.lang.String BrowserID) Stop WebBrowser by ID.
static boolean	SwitchWebBrowser(java.lang.String ID) Switch WebBrowser by ID.
static boolean	TypeChars(java.lang.String textvalue) Sends characters to the current focused Component. See Detailed Reference
static boolean	TypeEncryption(java.lang.String encryptedDataFile, java.lang.String privateKeyFile) Sends secret-text (such as password) to the current focused Component. See Detailed Reference
static boolean	TypeKeys(java.lang.String keystrokes) Sends keystrokes to the current focused Component. See Detailed Reference
static boolean	VerifyBinaryFileToFile(java.lang.String benchFile, java.lang.String actualFile, java.lang.String... optionals) Verify the current contents of a binary (image, PDF) file with a benchmark file.
static boolean	VerifyFileToFile(java.lang.String benchFile, java.lang.String actualFile, java.lang.String... optionals) Verify the current contents of a text file with a benchmark file (same as VerifyTextFileToFile).
static boolean	VerifyGUIImageToFile(Component comp, java.lang.String benchFile, java.lang.String... params) Verify the screen shot of a GUI component with a benchmark image file.
static boolean	VerifyTextFileToFile(java.lang.String benchFile, java.lang.String actualFile, java.lang.String... optionals) Verify the current contents of a text file with a benchmark file (same as VerifyFileToFile).
static boolean	VerifyValueContains(java.lang.String wholeString, java.lang.String substring, java.lang.String... optionals) Verify that a string value contains a substring.
static boolean	VerifyValueContainsIgnoreCase(java.lang.String wholeString, java.lang.String substring, java.lang.String... optionals) Verify that a string value contains a substring, ignoring case.
static boolean	VerifyValueDoesNotContain(java.lang.String wholeString, java.lang.String substring, java.lang.String... optionals) Verify that a string value does NOT contain a substring.
static boolean	VerifyValues(java.lang.String value1, java.lang.String value2, java.lang.String... optionals) Verify that two string values are identical.
static boolean	VerifyValuesIgnoreCase(java.lang.String value1, java.lang.String value2, java.lang.String... optionals) Verify that two string values are identical, ignoring case.
static boolean	VerifyValuesNotEqual(java.lang.String value1, java.lang.String value2, java.lang.String... optionals) Verify that two string values are NOT identical.
static boolean	WaitForGUI(Component comp, long time) Wait for a Window or Component to become valid. Note: This API doesn't fit for switching according to GUI existence, please use SAFSPlus.Misc.IsComponentExists(org.safs.model.Component, String...) instead. If the GUI doesn't become valid within timeout, this method will return false. If the execution doesn't end properly, this method will also return false. User cannot distinguish these 2 cases; and in the same time, a failure message will be written into Log.
static org.openqa.selenium.WebDriver	WebDriver() Retrieve a reference to the Selenium WebDriver object used by the currently active (last) session.

Methods inherited from class org.safs.SAFSPlus

_getMappedValue, _getVariable, _processArgs, _resolveDDVariables, _setVariable, action, actionGUILess, autorun, back, combineParams, command, debug, error, forward, getAllowExit, getExitCode, getRunner, iDriver, normalizeTextForInput, quote, quotePath, replaceSeparator, runTest, setAllowExit, setExitCode, setLeveledTest, setNormalizeTextForInput, setRunner, testStatusCode

Methods inherited from class java.lang.Object

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

Field Detail

Runner

public static EmbeddedHookDriverRunner Runner

The Runner object providing access to the underlying Selenium Engine. This is the main object subclasses would use to execute SeleniumPlus actions and commands and to gain references to more complex services like the running JSAFSDriver or the Selenium WebDriver object(s).

PRODUCT_NAME

public static final java.lang.String PRODUCT_NAME

'SeleniumPlus'

See Also:

Constant Field Values

PRODUCT_VERSION

public static final java.lang.String PRODUCT_VERSION

'1.0'

See Also:

Constant Field Values

PRODUCT_DESCRIPTION

public static final java.lang.String PRODUCT_DESCRIPTION

'The driver with embedded selenium engine to run test script in Java.'

See Also:

Constant Field Values

TEMP_SELENIUM_PLUS_RS_VAR

public static final java.lang.String TEMP_SELENIUM_PLUS_RS_VAR

See Also:

Constant Field Values

Constructor Detail

SeleniumPlus

public SeleniumPlus()

Internal framework use only. Required Default no-arg constructor. Any subclass instantiation should also invoke this super();

Method Detail

StartWebBrowser

public static boolean StartWebBrowser(java.lang.String URL,
                                      java.lang.String BrowserID,
                                      java.lang.String... params)

Start WebBrowser See Detailed Reference

Parameters:

URL - String,

BrowserID - String, Unique application/browser ID.

params - optional

params[0] browser name String, (default is DCDriverCommand.DEFAULT_BROWSER), it can be one of:
• SelectBrowser.BROWSER_NAME_CHROME
• SelectBrowser.BROWSER_NAME_FIREFOX
• SelectBrowser.BROWSER_NAME_IE

params[1] timeout int, in seconds. Implicit timeout for search elements
params[2] isRemote boolean, (no longer used -- everything is now "remote")

Following parameters indicate the extra parameters, they MUST be given by PAIR(key, value)

The key can be one of:

Constants.BrowserConstants.getExtraParameterKeys()


params[3] extra parameter key1
params[4] extra parameter value for key1

params[5] extra parameter key2
params[6] extra parameter value for key2

params[7] extra parameter key3
params[8] extra parameter value for key3
...

Returns:

true on success

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo(), StopWebBrowser(String), SwitchWebBrowser(String)

Example:

 StartWebBrowser("http://www.google.com", "GoogleMain");
 StartWebBrowser("http://www.google.com", "GoogleMain", SelectBrowser.BROWSER_NAME_CHROME);
 StartWebBrowser("http://www.google.com", "GoogleMain", SelectBrowser.BROWSER_NAME_IE, "10");

 
 The following gives some examples to start web browser with "custom profile" and "preferences".
 For the detail explanation of starting browser with "custom profile" and/or "preferences", please visit the section "Start Browser" at Selenium Welcome Document.
 

 //Start firefox browser with custom profile "myprofile" ( Create custom profile)
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_FIREFOX,
                                                        "10",
                                                        "true",
                                                        SelectBrowser.KEY_FIREFOX_PROFILE,
                                                        "myprofile"
                                                        });

 //Start firefox browser with some preference to set.
 String absolutePreferenceFile = "c:\\firefoxPref.json.dat";//A json file containing chrome preferences, like { "intl.accept_languages":"zh-cn", "accessibility.accesskeycausesactivation":false, "browser.download.folderList":2 }
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_FIREFOX,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_FIREFOX_PROFILE_PREFERENCE),
                                                        quote(absolutePreferenceFile)
                                                        });
 //Start firefox browser with preference by json string (not a file).
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_FIREFOX,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_FIREFOX_PROFILE_PREFERENCE),
                                                        "{ \"intl.accept_languages\":\"zh-cn\", \"accessibility.accesskeycausesactivation\":false, \"browser.download.folderList\":2 }"
                                                        });
 //Start firefox browser with preference by CSV array string, such as "key:value, key:value, key:value".
 Misc.Expressions(false);//This must be called to avoid expression-evaluation.
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_FIREFOX,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_FIREFOX_PROFILE_PREFERENCE),
                                                        "intl.accept_languages:zh-cn, accessibility.accesskeycausesactivation:false, browser.download.folderList:2 "
                                                        });

 //Start chrome browser with default data pool (chrome://version/, see "Profile Path") , and using the last-used user.
 String datapool = "C:\\Users\\some-user\\AppData\\Local\\Google\\Chrome\\User Data";
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_USER_DATA_DIR),
                                                        datapool
                                                        });
 //Start chrome browser with default data pool (chrome://version/, see "Profile Path") , and using the default user.
 String datapool = "C:\\Users\\some-user\\AppData\\Local\\Google\\Chrome\\User Data";
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_USER_DATA_DIR),
                                                        datapool,
                                                        quote(SelectBrowser.KEY_CHROME_PROFILE_DIR),
                                                        "Default"
                                                        });

 //Start chrome browser with custom data, and using the last-used user.
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_USER_DATA_DIR),
                                                        "c:\\chrome_custom_data"//Create custom data pool
                                                        });
 //Start chrome browser with custom data, and using the 1th user.
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_USER_DATA_DIR),
                                                        "c:\\chrome_custom_data",//Create custom data pool
                                                        quote(SelectBrowser.KEY_CHROME_PROFILE_DIR),
                                                        "Profile 1"
                                                        });

 //Start chrome browser with some options to be turned off, these options will be set to key SelectBrowser.KEY_CHROME_EXCLUDE_OPTIONS (excludeSwitches).
 String optionsToExclude = "disable-component-update";//comma separated options to exclude, like "disable-component-update, ignore-certificate-errors", be careful, there are NO 2 hyphens before options.
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_EXCLUDE_OPTIONS),
                                                        quote(optionsToExclude)
                                                        });

 //Start chrome browser with some chrome-command-line-options/preferences to set.
 String absolutePreferenceFile = "c:\\chromePref.json.dat";//A json file containing chrome command-line-options/preferences, like { "lang":"zh-cn", "start-maximized":"",  "seplus.chrome.preference.json.key":{ "intl.accept_languages":"zh-CN-pseudo", "intl.charset_default"  :"utf-8"} }
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_PREFERENCE),
                                                        quote(absolutePreferenceFile)
                                                        });
 //Start chrome browser with command-line-options/preferences by json string (not a file).
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_PREFERENCE),
                                                        "{ \"lang\":\"zh-cn\", \"start-maximized\":\"\",  \"seplus.chrome.preference.json.key\":{ \"intl.accept_languages\":\"zh-CN-pseudo\", \"intl.charset_default\" : \"utf-8\"} }"
                                                        });
 //Start chrome browser with command-line-options/preferences by CSV array string, such as "key:value, key:value, key:value".
 Misc.Expressions(false);//This must be called to avoid expression-evaluation.
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_PREFERENCE),
                                                        "lang:zh-cn, start-maximized: "
                                                        });

 //Start chrome browser with some chrome experimental options to set.
 String experimentalOptionsFile = "c:\\chromeExperimentalOptions.json.dat";//A json file containing chrome experimental options, like {"useAutomationExtension" : false, "excludeSwitches" : ["enable-automation"], "prefs" : { "credentials_enable_service" : false, "profile" : { "password_manager_enabled" : false } } }
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_EXPERIMENTAL_OPTIONS),
                                                        quote(experimentalOptionsFile)
                                                        });
 //Start chrome browser with experimental options by json string (not a file).
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_EXPERIMENTAL_OPTIONS),
                                                        "{\"useAutomationExtension\" : false, \"excludeSwitches\" : [\"enable-automation\"], \"prefs\" : { \"credentials_enable_service\" : false, \"profile\" : { \"password_manager_enabled\" : false } } }"
                                                        });
 //Start chrome browser with experimental options by CSV array string, such as "key:value, key:value, key:value".
 Misc.Expressions(false);//This must be called to avoid expression-evaluation.
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_CHROME_EXPERIMENTAL_OPTIONS),
                                                        " useAutomationExtension:false, excludeSwitches:[\"enable-automation\"] "
                                                        });

 //Start chrome browser out of sandbox (It is NOT suggested to use that way). But it can be used to avoid some chrome crash problem.
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(BrowserConstants.KEY_CHROME_NO_SANDBOX),
                                                        "true"
                                                        });
 //Start chrome browser with the 'network-conditions' of {"offline":false, "latency":5, "download_throughput":500000, "upload_throughput":500000}
 "latency" is in milliseconds, "download_throughput" is in bps, "upload_throughput" is in bps.

 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(BrowserConstants.KEY_SET_NETWORK_CONDITIONS),
                                                        "{ \"offline\":false, \"latency\":5, \"download_throughput\":500000 , \"upload_throughput\":500000}"
                                                        });

 //Start chrome browser with an empty 'network-conditions'. This call is needed if you want to adjust (set, get, delete) the 'network-conditions'.
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(BrowserConstants.KEY_SET_NETWORK_CONDITIONS),
                                                        ""
                                                        });

 //Start chrome browser with custom capabilities. The 'custom capabilities' will be a set of key:value pairs json data, each key:value will be stored in the Capabilities.
 String customCapsDat = "c:\\custom.caps.json.dat";//A json file containing 'custom capabilities', like {"goog:loggingPrefs": {"browser": "ALL", "client": "ALL", "driver": "ALL", "performance": "ALL", "server": "ALL"}}
 //This will set 'goog:loggingPrefs' as value {"browser": "ALL", "client": "ALL", "driver": "ALL", "performance": "ALL", "server": "ALL"} in the selenium capabilities to turn on all levels of logs.
 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(BrowserConstants.KEY_CUSTOM_CAPABILITIES),
                                                        quote(customCapsDat)
                                                        });

 //Start chrome browser with a chrome ModHeader extension to load, and load the ModHeader's profile if it is provided.
 The file "loadExtensions.json" contains "extensions" (required) and "extension-modheader-profile" (optional), such as:

 //only load the ModHeader extension
 {
 "extensions": ["C:\\SeleniumPlus\\extra\\ModHeader.crx"],
 }

 //or load ModHeader extension and load the ModHeader's profile by a json file
 {
 "extensions": ["C:\\SeleniumPlus\\extra\\ModHeader.crx"],
 "extension-modheader-profile": "C:\\SeleniumPlus\\extra\\ModHeader.json"
 }

 //or load ModHeader extension and load the ModHeader's profile by an URL
 {
 "extensions": ["C:\\SeleniumPlus\\extra\\ModHeader.crx"],
 "extension-modheader-profile": "https://bewisse.com/modheader/p/#NobwRAhgDlCmB2ATAsge0bMAuAZhANgM6wA0YARhAMYDWA5gE6oCuSAwqvqg9mAMQA2cgFYAzMIBMYMjgCW+AC6wGhbMAC6ZABawIGFWvBVUAWxMIFvaWAQRy+WImwKGzUmHgRzvAB4BaQghCPygmKAg6CCU-WScyADcCN15EUwhZeGZiHgBfTTAtWNgOMwtnV3cGWEIoAAldfVUsDTJCLW4FABVZBQdeAEZrJR8FDi4eLH4caZmhnr7JgAUmOQcAAkGyZgZ8ACVYKHxqWHN4BSaNPKA"
 }

 //or load ModHeader extension and load the ModHeader's profile by a json object
 {
 "extensions": ["C:\\SeleniumPlus\\extra\\ModHeader.crx"],
 "extension-modheader-profile": [{"appendMode":false,"backgroundColor":"#6b5352","filters":[],"headers":[{"comment":"","enabled":true,"name":"x-sas-propagate-id","value":"domainuser"}],"hideComment":true,"respHeaders":[],"shortTitle":"1","textColor":"#ffffff","title":"Profile 1","urlReplacements":[]}]
 }

 StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_CHROME,
                                                        "10",
                                                        "true",
                                                        quote(BrowserConstants.KEY_CHROME_LOAD_EXTENSIONS),
                                                        quote("loadExtensions.json")
                                                        });

 

StopWebBrowser

public static boolean StopWebBrowser(java.lang.String BrowserID)

Stop WebBrowser by ID. During test, multiple browsers can be opened by #StartWebBrowser(String, BrowserID, String...)
If user wants to stop one of these opened browser, use can call this method.
This method requires a parameter 'ID', which is given by user when he calls #StartWebBrowser(String, BrowserID, String...)

Parameters:

BrowserID - String, the BrowserID served as key to get the WebDriver from cache.

Returns:

- true on success

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo(), StartWebBrowser(String, String, String...)

Example:

 
 String browserID = "GoogleMain";
 StartWebBrowser("http://www.google.com", browserID);
 //do some testing, then
 StopWebBrowser(browserID);
 
 

SwitchWebBrowser

public static boolean SwitchWebBrowser(java.lang.String ID)

Switch WebBrowser by ID. During test, multiple browsers can be opened by #StartWebBrowser(String, int, String...)
If user wants to switch between these opened browser, use can call this method.
This method requires a parameter 'ID', which is given by user when he calls #StartWebBrowser(String, int, String...)
See Detailed Reference

Parameters:

ID - String, the ID served as key to get the WebDriver from cache.

Returns:

true on success

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo(), StartWebBrowser(String, String, String...)

Example:

 
 SwitchWebBrowser("GoogleNewWindow");
 
 

TypeKeys

public static boolean TypeKeys(java.lang.String keystrokes)

Sends keystrokes to the current focused Component.
See Detailed Reference

This supports special key characters like:

     {Enter} = ENTER Key
     {Tab} = TAB Key
     ^ = CONTROL Key with another key ( "^s" = CONTROL + s )
     % = ALT Key with another key ( "%F" = ALT + F )
     + = SHIFT Key with another key ( "+{Enter}" = SHIFT + ENTER )
 

We are generally providing this support through our generic InputKeys Support.

Parameters:

keystrokes - String, to send via input to the current focused Component.

Returns:

true on success

See Also:

Robot.inputKeys(String), SAFSPlus.quote(String)

Example:

 
 SeleniumPlus.TypeKeys("% n");//"Alt+Space+n" Minimize the current window
 SeleniumPlus.TypeKeys(quote("^p"));//"Ctrl+p" Open a printer window for current window
 
 

TypeChars

public static boolean TypeChars(java.lang.String textvalue)

Sends characters to the current focused Component.
See Detailed Reference

Parameters:

textvalue - String, to send via input to the current focused Component.

Returns:

true on success

See Also:

Robot.inputChars(String), SAFSPlus.quote(String)

Example:

 
 SeleniumPlus.TypeChars("Test Value");
 SeleniumPlus.TypeChars(quote("UTF-8"));
 SeleniumPlus.TypeChars(quote("^NotVariable"));
 
 

TypeEncryption

public static boolean TypeEncryption(java.lang.String encryptedDataFile,
                                     java.lang.String privateKeyFile)

Sends secret-text (such as password) to the current focused Component.
See Detailed Reference

Parameters:

encryptedDataFile - String, the file containing 'encrypted data' to send to the current focused Component. It can be an absolute path, or a path relative the the test project's root.

privateKeyFile - String, the file containing 'private key' to decrypt the 'encrypted data' It can be an absolute path, or a path relative the the test project's root.

Returns:

true on success

See Also:

Robot.inputChars(String), RSA

Example:

 //D:\secretPath\private.key contains "private key", which is generated by RSA
 //C:\safs\passwords\encrypted.pass contains the encrypted-data, which is encrypted by RSA with publickey
 
 SeleniumPlus.TypeEncryption("C:\safs\passwords\encrypted.pass", "D:\secretPath\private.key" );
 
 

HoverScreenLocation

public static boolean HoverScreenLocation(java.lang.String coordination,
                                          java.lang.String... optionals)

Hover the mouse over a specified screen location.

See Detailed Reference

Parameters:

coordination - String, The screen location, such as "200;400", or a mapKey defined under "ApplicationConstants" in map file

optionals -

optionals[0] hoverTime int, milliseconds to hover

Returns:

true if hover succeeds, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = SeleniumPlus.HoverScreenLocation("500, 300", "20");
 boolean success = SeleniumPlus.HoverScreenLocation("locKey", "20");//locKey="500, 300" defined in map file under "ApplicationConstants"
 
 

VerifyBinaryFileToFile

public static boolean VerifyBinaryFileToFile(java.lang.String benchFile,
                                             java.lang.String actualFile,
                                             java.lang.String... optionals)

Verify the current contents of a binary (image, PDF) file with a benchmark file.

See Detailed Reference

Parameters:

benchFile - String, File used as the comparison benchmark.

actualFile - String, File used as the comparison file under test.

optionals -

optionals[0] FilterMode String, one of FileUtilities.FilterMode. FileUtilities.FilterMode.TOLERANCE is valid only when the binary files are images.
optionals[1] FilterOption
• int, if the FileUtilities.FilterMode is FileUtilities.FilterMode.TOLERANCE, a number between 0 and 100, the percentage of bits need to be the same. 100 means only 100% match, 2 images will be considered matched; 0 means even no bits match, 2 images will be considered matched.
  
• other type, if the FilterMode is FilterMode.XXX
  
optionals[2] alterImageStyle ImageUtils.AlterImageStyle, it is used to alter the diff image when 2 image/PDF doesn't match.
optionals[3] alterImageFactor double, how much lighter or darker to make the original pixel (with no difference), it is a number between 0 and 1.
It only takes effect if the parameter 'alterImageStyle' is ImageUtils.AlterImageStyle.TINT or ImageUtils.AlterImageStyle.SHADE.
For SHADE, the bigger the factor, the darker the shade.
For TINT, the bigger the factor, the lighter the tint.
optionals[4] pdfResolution int, the resolution (DPI) used to convert PDF to image. The default is Constants.IMAGE_PDF_CONVERSION_RESOLUTION_DEFAULT.

Returns:

true if the 2 files contain the same content, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = SeleniumPlus.VerifyBinaryFileToFile("signIn.png", "signIn.png");
 boolean success = SeleniumPlus.VerifyBinaryFileToFile("c:\bench\signIn.png", "d:\test\signIn.png");
 boolean success = SeleniumPlus.VerifyBinaryFileToFile("c:\bench\signIn.png", "d:\test\signIn.png", FilterMode.TOLERANCE.name, "90");
 boolean success = SeleniumPlus.VerifyBinaryFileToFile("bench.pdf", "actual.pdf", FilterMode.TOLERANCE.name, "100", AlterImageStyle.TINT.name, "0.9", "100");
 
 

VerifyFileToFile

public static boolean VerifyFileToFile(java.lang.String benchFile,
                                       java.lang.String actualFile,
                                       java.lang.String... optionals)

Verify the current contents of a text file with a benchmark file (same as VerifyTextFileToFile).

See Detailed Reference

Parameters:

benchFile - String, File used as the comparison benchmark.

actualFile - String, File used as the comparison file under test.

optionals - -- NOT used yet

Returns:

true if the 2 files contain the same content, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = SeleniumPlus.VerifyFileToFile("benchFile.txt", "actualFile.txt");
 boolean success = SeleniumPlus.VerifyFileToFile("c:\bench\benchFile.txt", "d:\test\actualFile.txt");
 
 

VerifyTextFileToFile

public static boolean VerifyTextFileToFile(java.lang.String benchFile,
                                           java.lang.String actualFile,
                                           java.lang.String... optionals)

Verify the current contents of a text file with a benchmark file (same as VerifyFileToFile).

See Detailed Reference

Parameters:

benchFile - String, File used as the comparison benchmark.

actualFile - String, File used as the comparison file under test.

optionals - -- NOT used yet

Returns:

true if the 2 files contain the same content, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = SeleniumPlus.VerifyTextFileToFile("benchFile.txt", "actualFile.txt");
 boolean success = SeleniumPlus.VerifyTextFileToFile("c:\bench\benchFile.txt", "d:\test\actualFile.txt");
 
 

VerifyValueContains

public static boolean VerifyValueContains(java.lang.String wholeString,
                                          java.lang.String substring,
                                          java.lang.String... optionals)

Verify that a string value contains a substring.

See Detailed Reference

Parameters:

wholeString - String, the string value to verify.

substring - String, the substring

optionals -

optionals[0] String, Set to "SuppressValue" to prevent the logging of ugly multi-line values

Returns:

true if a string value does contain a substring, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 String labelVar = "labelVariable";
 Component.AssignPropertyVariable(Map.AUT.Lable,"textContent", labelVar);
 String label = SeleniumPlus.GetVariableValue(labelVar);
 boolean success = SeleniumPlus.VerifyValueContains(label, "labelContent");
 //or
 boolean success = SeleniumPlus.VerifyValueContains("^"+labelVar, "labelContent");
 
 

VerifyValueContainsIgnoreCase

public static boolean VerifyValueContainsIgnoreCase(java.lang.String wholeString,
                                                    java.lang.String substring,
                                                    java.lang.String... optionals)

Verify that a string value contains a substring, ignoring case.

See Detailed Reference

Parameters:

wholeString - String, the string value to verify.

substring - String, the substring

optionals -

optionals[0] String, Set to "SuppressValue" to prevent the logging of ugly multi-line values

Returns:

true if a string value does contain a substring ignoring case, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 String labelVar = "labelVariable";
 Component.AssignPropertyVariable(Map.AUT.Lable,"textContent", labelVar);
 boolean success = SeleniumPlus.VerifyValueContainsIgnoreCase("^"+labelVar, "subcontent");
 
 

VerifyValueDoesNotContain

public static boolean VerifyValueDoesNotContain(java.lang.String wholeString,
                                                java.lang.String substring,
                                                java.lang.String... optionals)

Verify that a string value does NOT contain a substring.

See Detailed Reference

Parameters:

wholeString - String, the string value to verify.

substring - String, the substring

optionals -

optionals[0] String, Set to "SuppressValue" to prevent the logging of ugly multi-line values

Returns:

true if a string value does NOT contain a substring, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 String labelVar = "labelVariable";
 Component.AssignPropertyVariable(Map.AUT.Lable,"textContent", labelVar);
 boolean success = SeleniumPlus.VerifyValueDoesNotContain("^"+labelVar, "substr");
 
 

VerifyValues

public static boolean VerifyValues(java.lang.String value1,
                                   java.lang.String value2,
                                   java.lang.String... optionals)

Verify that two string values are identical.

See Detailed Reference

Parameters:

value1 - String, the first value to compare.

value2 - String, the second value to compare.

optionals -

optionals[0] String, Set to "SuppressValue" to prevent the logging of ugly multi-line values

Returns:

true if the two values do equal, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 String labelVar = "labelVariable";
 Component.AssignPropertyVariable(Map.AUT.Lable,"textContent", labelVar);
 String label = SeleniumPlus.GetVariableValue(labelVar);
 boolean success = SeleniumPlus.VerifyValues(label, "labelContent");
 //or
 boolean success = SeleniumPlus.VerifyValues("^"+labelVar, "labelContent");
 
 

VerifyValuesIgnoreCase

public static boolean VerifyValuesIgnoreCase(java.lang.String value1,
                                             java.lang.String value2,
                                             java.lang.String... optionals)

Verify that two string values are identical, ignoring case.

See Detailed Reference

Parameters:

value1 - String, the first value to compare.

value2 - String, the second value to compare.

optionals -

optionals[0] String, Set to "SuppressValue" to prevent the logging of ugly multi-line values

Returns:

true if the two values do equal, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 String labelVar = "labelVariable";
 Component.AssignPropertyVariable(Map.AUT.Lable,"textContent", labelVar);
 boolean success = SeleniumPlus.VerifyValuesIgnoreCase("^"+labelVar, "labelcontent");
 
 

VerifyValuesNotEqual

public static boolean VerifyValuesNotEqual(java.lang.String value1,
                                           java.lang.String value2,
                                           java.lang.String... optionals)

Verify that two string values are NOT identical.

See Detailed Reference

Parameters:

value1 - String, the first value to compare.

value2 - String, the second value to compare.

optionals -

optionals[0] String, Set to "SuppressValue" to prevent the logging of ugly multi-line values

Returns:

true if the two values do NOT equal, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 String labelVar = "labelVariable";
 Component.AssignPropertyVariable(Map.AUT.Lable,"textContent", labelVar);
 boolean success = SeleniumPlus.VerifyValuesNotEqual("^"+labelVar, "labelContent");
 
 

Click

public static boolean Click(Component comp,
                            java.lang.String... params)

Click on any visible component.

See Detailed Reference

Parameters:

comp - -- Component (from App Map) to Click

params - optional

• params[0] X,Y coordinate. Example: "50,50", or "AppMapSubkey" defined in App Map
  For SE+, params[0] X,Y coordinate also support percentage format for X, or Y. Example: "20%,30%", "20%,30", "20,30%".
  
• params[1] auto-scroll boolean if the component will be scrolled into view automatically before clicking. if not provided, the default value is true.
• params[2] verify boolean check if the component is visible. We try several ways to scroll the component into view: if this parameter 'verify' is true then we will not try other ways if the component is already visible; otherwise we will try all the ways to show the element even the component may have already shown on the page. if not provided, the default value is true.

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 1) boolean success = Click(Map.Google.Apps);//Click at the center
 2) boolean success = Click(Map.Google.Apps,"20,20");//Click at the coordinate (20,20)
 3) boolean success = Click(Map.Google.Apps,"20%,30%"); // Click at the coordinate: its X value equals 20% width of component, its Y value equals 30% height of component.
 4) boolean success = Click(Map.Google.Apps,"AppMapSubkey");//Click at the coordinate defined by entry "AppMapSubkey" in App Map.
 5) boolean success = Click(Map.Google.Apps,"20,20", "false");//Click at the coordinate (20,20), and web-element will NOT be automatically scrolled into view
 6) boolean success = Click(Map.Google.Apps,"", "", "false");//Click at the center, and web-element will be automatically scrolled into view by all means
  // one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 Pay attention: If you use percentage format in SE+, you'd better use 'Misc.Expressions(false);' first.

 "AppMapSubkey" is expected to be an AppMap entry in an "Apps" section in the App Map.
 See Detailed Reference
 

CtrlClick

public static boolean CtrlClick(Component comp,
                                java.lang.String... params)

Control-Click on any visible component.

See Detailed Reference

Parameters:

comp - -- Component (from App Map) to Click

params - optional

• params[0] X,Y coordinate. Example: "50,50", or "AppMapSubkey" defined in App Map
  For SE+, params[0] X,Y coordinate also support percentage format for X, or Y. Example: "20%,30%", "20%,30", "20,30%".
  
• params[1] auto-scroll boolean if the component will be scrolled into view automatically before clicking. if not provided, the default value is true.
• params[2] verify boolean check if the component is visible. We try several ways to scroll the component into view: if this parameter 'verify' is true then we will not try other ways if the component is already visible; otherwise we will try all the ways to show the element even the component may have already shown on the page. if not provided, the default value is true.

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 1) boolean success = CtrlClick(Map.Google.Apps);//Control-Click at the center
 2) boolean success = CtrlClick(Map.Google.Apps,"20,20");//Control-Click at the coordinate (20,20)
 3) boolean success = CtrlClick(Map.Google.Apps,"20%,30%"); // Control-Click at the coordinate: its X value equals 20% width of component, its Y value equals 30% height of component.
 4) boolean success = CtrlClick(Map.Google.Apps,"AppMapSubkey");//Control-Click at the coordinate defined by entry "AppMapSubkey" in App Map.
 5) boolean success = CtrlClick(Map.Google.Apps,"20,20", "false");//Control-Click at the coordinate (20,20) and web-element will not be scrolled into view automatically
 6) boolean success = CtrlClick(Map.Google.Apps,"", "", "false");//Control-Click at the center, and web-element will be automatically scrolled into view by all means
  // one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 Pay attention: If you use percentage format in SE+, you'd better use 'Misc.Expressions(false);' first.

 

CtrlRightClick

public static boolean CtrlRightClick(Component comp,
                                     java.lang.String... params)

Control-Right-Click on any visible component.

See Detailed Reference

Parameters:

comp - -- Component (from App Map) to Click

params - optional

• params[0] X,Y coordinate. Example: "50,50", or "AppMapSubkey" defined in App Map
  For SE+, params[0] X,Y coordinate also support percentage format for X, or Y. Example: "20%,30%", "20%,30", "20,30%".
  
• params[1] auto-scroll boolean if the component will be scrolled into view automatically before clicking. if not provided, the default value is true.
• params[2] verify boolean check if the component is visible. We try several ways to scroll the component into view: if this parameter 'verify' is true then we will not try other ways if the component is already visible; otherwise we will try all the ways to show the element even the component may have already shown on the page. if not provided, the default value is true.

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 1) boolean success = CtrlRightClick(Map.Google.Apps);//Control-Right-Click at the center
 2) boolean success = CtrlRightClick(Map.Google.Apps,"20,20");//Control-Right-Click at the coordinate (20,20)
 3) boolean success = CtrlRightClick(Map.Google.Apps,"20%,30%"); // Control-Right-Click at the coordinate: its X value equals 20% width of component, its Y value equals 30% height of component.
 4) boolean success = CtrlRightClick(Map.Google.Apps,"AppMapSubkey");//Control-Right-Click at the coordinate defined by entry "AppMapSubkey" in App Map.
 5) boolean success = CtrlRightClick(Map.Google.Apps,"20,20", "false");//Control-Right-Click at the coordinate (20,20) and web-element will not be scrolled into view automatically
 5) boolean success = CtrlRightClick(Map.Google.Apps,"", "", "false");//Control-Right-Click at the center and web-element will be scrolled into view automatically by all means
  // one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 Pay attention: If you use percentage format in SE+, you'd better use 'Misc.Expressions(false);' first.

 

DoubleClick

public static boolean DoubleClick(Component comp,
                                  java.lang.String... params)

Double-Click on any visible component.

See Detailed Reference

Parameters:

comp - -- Component (from App Map) to Click

params - optional

• params[0] X,Y coordinate. Example: "50,50", or "AppMapSubkey" defined in App Map
  For SE+, params[0] X,Y coordinate also support percentage format for X, or Y. Example: "20%,30%", "20%,30", "20,30%".
  
• params[1] auto-scroll boolean if the component will be scrolled into view automatically before clicking. if not provided, the default value is true.
• params[2] verify boolean check if the component is visible. We try several ways to scroll the component into view: if this parameter 'verify' is true then we will not try other ways if the component is already visible; otherwise we will try all the ways to show the element even the component may have already shown on the page. if not provided, the default value is true.

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 1) boolean success = DoubleClick(Map.Google.Apps);//Double-Click at the center
 2) boolean success = DoubleClick(Map.Google.Apps,"20,20");//Double-Click at the coordinate (20,20)
 3) boolean success = DoubleClick(Map.Google.Apps,"20%,30%"); // Double-Click at the coordinate: its X value equals 20% width of component, its Y value equals 30% height of component.
 4) boolean success = DoubleClick(Map.Google.Apps,"AppMapSubkey");//Double-Click at the coordinate defined by entry "AppMapSubkey" in App Map.
 5) boolean success = DoubleClick(Map.Google.Apps,"20,20", "false");//Double-Click at the coordinate (20,20) and web-element will not be scrolled into view automatically
 5) boolean success = DoubleClick(Map.Google.Apps,"", "", "false");//Double-Click at the center and web-element will be scrolled into view automatically by all means
  // one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 Pay attention: If you use percentage format in SE+, you'd better use 'Misc.Expressions(false);' first.

 

RightClick

public static boolean RightClick(Component comp,
                                 java.lang.String... params)

Right-Click on any visible component.

See Detailed Reference

Parameters:

comp - -- Component (from App Map) to Click

params - optional

• params[0] X,Y coordinate. Example: "50,50", or "AppMapSubkey" defined in App Map
  For SE+, params[0] X,Y coordinate also support percentage format for X, or Y. Example: "20%,30%", "20%,30", "20,30%".
  
• params[1] auto-scroll boolean if the component will be scrolled into view automatically before clicking. if not provided, the default value is true.
• params[2] verify boolean check if the component is visible. We try several ways to scroll the component into view: if this parameter 'verify' is true then we will not try other ways if the component is already visible; otherwise we will try all the ways to show the element even the component may have already shown on the page. if not provided, the default value is true.

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 1) boolean success = RightClick(Map.Google.Apps);//Right-Click at the center
 2) boolean success = RightClick(Map.Google.Apps,"20,20");//Right-Click at the coordinate (20,20)
 3) boolean success = RightClick(Map.Google.Apps,"20%,30%"); // Right-Click at the coordinate: its X value equals 20% width of component, its Y value equals 30% height of component.
 4) boolean success = RightClick(Map.Google.Apps,"AppMapSubkey");//Right-Click at the coordinate defined by entry "AppMapSubkey" in App Map.
 5) boolean success = RightClick(Map.Google.Apps,"20,20", "false");//Right-Click at the coordinate (20,20) and web-element will not be scrolled into view automatically
 5) boolean success = RightClick(Map.Google.Apps,"", "", "false");//Right-Click at the center and web-element will be scrolled into view automatically by all means
  // one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 Pay attention: If you use percentage format in SE+, you'd better use 'Misc.Expressions(false);' first.

 

ShiftClick

public static boolean ShiftClick(Component comp,
                                 java.lang.String... params)

Shift-Click on any visible component.

See Detailed Reference

Parameters:

comp - -- Component (from App Map) to Click

params - optional

• params[0] X,Y coordinate. Example: "50,50", or "AppMapSubkey" defined in App Map
  For SE+, params[0] X,Y coordinate also support percentage format for X, or Y. Example: "20%,30%", "20%,30", "20,30%".
  
• params[1] auto-scroll boolean if the component will be scrolled into view automatically before clicking. if not provided, the default value is true.
• params[2] verify boolean check if the component is visible. We try several ways to scroll the component into view: if this parameter 'verify' is true then we will not try other ways if the component is already visible; otherwise we will try all the ways to show the element even the component may have already shown on the page. if not provided, the default value is true.

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 1) boolean success = ShiftClick(Map.Google.Apps);//Shift-Click at the center
 2) boolean success = ShiftClick(Map.Google.Apps,"20,20");//Shift-Click at the coordination (20,20)
 3) boolean success = ShiftClick(Map.Google.Apps,"20%,30%"); // Shift-Click at the coordinate: its X value equals 20% width of component, its Y value equals 30% height of component.
 4) boolean success = ShiftClick(Map.Google.Apps,"AppMapSubkey");//Shift-Click at the coordination defined by entry "AppMapSubkey" in App Map.
 5) boolean success = ShiftClick(Map.Google.Apps,"20,20", "false");//Shift-Click at the coordination (20,20) and web-element will not be scrolled into view automatically
 5) boolean success = ShiftClick(Map.Google.Apps,"", "", "false");//Shift-Click at the center, and web-element will be automatically scrolled into view by all means
  // one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 Pay attention: If you use percentage format in SE+, you'd better use 'Misc.Expressions(false);' first.

 

LeftDrag

public static boolean LeftDrag(Component comp,
                               java.lang.String coordinates)

A left mouse drag is performed on the object based on the stored coordinates relative to this object.

See Detailed Reference

Parameters:

comp - Component, the component (from App Map) relative to which to calculate coordinates to drag

coordinates - String, the relative coordinates. Example: "Coords=3,10,12,20", or "coordsKey" defined in App Map

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = LeftDrag(Map.Google.Apps,"3,10,12,20");//Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = LeftDrag(Map.Google.Apps,"Coords=3,10,12,20");//Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = LeftDrag(Map.Google.Apps,"coordsKey");//"coordsKey" is defined in map file under section [Apps]
 //one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 

ShiftLeftDrag

public static boolean ShiftLeftDrag(Component comp,
                                    java.lang.String coordinates)

A Shift left mouse drag is performed on the object based on the stored coordinates relative to this object.

See Detailed Reference

Parameters:

comp - Component, the component (from App Map) relative to which to calculate coordinates to drag

coordinates - String, the relative coordinates. Example: "Coords=3,10,12,20", or "coordsKey" defined in App Map

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = ShiftLeftDrag(Map.Google.Apps,"3,10,12,20");//Shift-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = ShiftLeftDrag(Map.Google.Apps,"Coords=3,10,12,20");//Shift-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = ShiftLeftDrag(Map.Google.Apps,"coordsKey");//"coordsKey" is defined in map file under section [Apps]
 //one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 

CtrlShiftLeftDrag

public static boolean CtrlShiftLeftDrag(Component comp,
                                        java.lang.String coordinates)

A Ctrl Shift left mouse drag is performed on the object based on the stored coordinates relative to this object.

See Detailed Reference

Parameters:

comp - Component, the component (from App Map) relative to which to calculate coordinates to drag

coordinates - String, the relative coordinates. Example: "Coords=3,10,12,20", or "coordsKey" defined in App Map

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = CtrlShiftLeftDrag(Map.Google.Apps,"3,10,12,20");//Ctrl-Shift-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = CtrlShiftLeftDrag(Map.Google.Apps,"Coords=3,10,12,20");//Ctrl-Shift-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = CtrlShiftLeftDrag(Map.Google.Apps,"coordsKey");//"coordsKey" is defined in map file under section [Apps]
 //one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 

CtrlLeftDrag

public static boolean CtrlLeftDrag(Component comp,
                                   java.lang.String coordinates)

A Ctrl left mouse drag is performed on the object based on the stored coordinates relative to this object.

See Detailed Reference

Parameters:

comp - Component, the component (from App Map) relative to which to calculate coordinates to drag

coordinates - String, the relative coordinates. Example: "Coords=3,10,12,20", or "coordsKey" defined in App Map

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = CtrlLeftDrag(Map.Google.Apps,"3,10,12,20");//Ctrl-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = CtrlLeftDrag(Map.Google.Apps,"Coords=3,10,12,20");//Ctrl-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = CtrlLeftDrag(Map.Google.Apps,"coordsKey");//"coordsKey" is defined in map file under section [Apps]
 //one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 

AltLeftDrag

public static boolean AltLeftDrag(Component comp,
                                  java.lang.String coordinates)

A Alt left mouse drag is performed on the object based on the stored coordinates relative to this object.

See Detailed Reference

Parameters:

comp - Component, the component (from App Map) relative to which to calculate coordinates to drag

coordinates - String, the relative coordinates. Example: "Coords=3,10,12,20", or "coordsKey" defined in App Map

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = AltLeftDrag(Map.Google.Apps,"3,10,12,20");//Alt-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = AltLeftDrag(Map.Google.Apps,"Coords=3,10,12,20");//Alt-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = AltLeftDrag(Map.Google.Apps,"coordsKey");//"coordsKey" is defined in map file under section [Apps]
 //one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 

CtrlAltLeftDrag

public static boolean CtrlAltLeftDrag(Component comp,
                                      java.lang.String coordinates)

A Ctrl Alt left mouse drag is performed on the object based on the stored coordinates relative to this object.

See Detailed Reference

Parameters:

comp - Component, the component (from App Map) relative to which to calculate coordinates to drag

coordinates - String, the relative coordinates. Example: "Coords=3,10,12,20", or "coordsKey" defined in App Map

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = CtrlAltLeftDrag(Map.Google.Apps,"3,10,12,20");//Ctrl-Alt-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = CtrlAltLeftDrag(Map.Google.Apps,"Coords=3,10,12,20");//Ctrl-Alt-Left-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = CtrlAltLeftDrag(Map.Google.Apps,"coordsKey");//"coordsKey" is defined in map file under section [Apps]
 //one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 

RightDrag

public static boolean RightDrag(Component comp,
                                java.lang.String coordinates)

A right mouse drag is performed on the object based on the stored coordinates relative to this object.

See Detailed Reference

Parameters:

comp - Component, the component (from App Map) relative to which to calculate coordinates to drag

coordinates - String, the relative coordinates. Example: "Coords=3,10,12,20", or "coordsKey" defined in App Map

Returns:

true if successfully executed, false otherwise.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

Example:

 
 boolean success = RightDrag(Map.Google.Apps,"3,10,12,20");//Right-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = RightDrag(Map.Google.Apps,"Coords=3,10,12,20");//Right-Drag from (3,10) to (12,20), relative to the Left Up corner of component Map.Google.Apps
 boolean success = RightDrag(Map.Google.Apps,"coordsKey");//"coordsKey" is defined in map file under section [Apps]
 //one of the above and then,
 int rc = prevResults.getStatusCode();      // if useful
 String info = prevResults.getStatusInfo(); // if useful
 

 

Highlight

public static boolean Highlight(boolean OnOff)

Highlight object

Parameters:

OnOff - -- true or false for object highlight

Returns:

true on success

Pause

public static boolean Pause(int seconds)

Pause test-case flow in seconds. If you want to pause in millisecond, use SAFSPlus.DriverCommand.Delay(int).

Parameters:

seconds - int, the seconds to pause

Returns:

true if successfully executed, false otherwise.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo(), SAFSPlus.DriverCommand.Delay(int)

Example:

 
 Pause(20);
 
 

GetGUIImage

public static boolean GetGUIImage(Component comp,
                                  java.lang.String fileName,
                                  java.lang.String... params)

Take a screenshot of windows or component.
See Detailed Reference

Parameters:

comp - Component, the component to get its image.

fileName - String, the file name to store image. Suggest to save as .png image.
It can be relative or absolute. If it is relative, the file will be stored to TestDirectory "Actuals".
Supported file extensions are ".jpeg", ".tif", ".gif", ".png", ".pnm", ".bmp" etc.
If the file extension is not supported, then suffix ".bmp" will be appended to filename.

params - optional

params[1] SubArea String, (x1,y1,x2,y2) indicating partial image of the component to capture, such as "0,0,50%,50%",
it can be app map subkey under component name.
params[2] FilteredAreas String, (x1,y1,x2,y2 x1,y1,x2,y2) a set of areas to filter the current GUI image.
it has a prefix "Filter", and followed by a set of subareas. Such as "Filter=0,0,5,5 50%,50%,15,15"
Multiple areas are separated by a space character. The filtered area is covered by black.

Returns:

boolean, true on success; false otherwise

Example:

 
 GetGUIImage(Map.Google.SignIn,"SignIn");//will be saved at <testProject>\Actuals\SignIn.bmp
 GetGUIImage(Map.Google.SignIn,"c:/temp/SignIn.gif");

 //Following example will store part of the SingIn image,
 GetGUIImage(Map.Google.SignIn,"SignInPartial.png", "0,0,50%,50%");
 //"subarea" is defined in map file
 //[SignIn]
 //subarea="0,0,50%,50%"
 GetGUIImage(Map.Google.SignIn,"SignInPartial.png", "subarea");
 //or
 //"subarea" is defined in map file
 //[ApplicationConstants]
 //subarea="0,0,50%,50%"
 GetGUIImage(Map.Google.SignIn,"SignInPartial.png", Map.subarea);
 GetGUIImage(Map.Google.SignIn,"SignInPartial.png", Map.subarea());

 //Filter the SingIn image and save it
 GetGUIImage(Map.Google.SignIn,"SignInFiltered.gif", "", quote("Filter=0,0,10,10 60,60,10,10"));
 //"filterAreas" is defined in map file
 //[SignIn]
 //filterAreas="Filter=0,0,10,10 60,60,10,10"
 GetGUIImage(Map.Google.SignIn,"SignInFiltered.gif", "", "filterAreas");
 //"filterAreas" is defined in map file
 //[ApplicationConstants]
 //filterAreas="Filter=0,0,10,10 60,60,10,10"
 GetGUIImage(Map.Google.SignIn,"SignInFiltered.gif", "", Map.filterAreas);
 GetGUIImage(Map.Google.SignIn,"SignInFiltered.gif", "", Map.filterAreas());
 
 

GetGUIImage

public static boolean GetGUIImage(Component comp,
                                  java.lang.String fileName,
                                  java.lang.String subArea,
                                  Component[] childrenToMask)

Take a screenshot of windows or component and filter some children inside.

Parameters:

comp - org.safs.model.Component, the component to get its image.

fileName - String, the file name to store image. Suggest to save as .png image.
It can be relative or absolute. If it is relative, the file will be stored to TestDirectory "Actuals".
Supported file extensions are ".jpeg", ".tif", ".gif", ".png", ".pnm", ".bmp" etc.
If the file extension is not supported, then suffix ".bmp" will be appended to filename.

subArea - String, (x1,y1,x2,y2) indicating partial image of the component to capture, such as "0,0,50%,50%",
it can be app map subkey under component name.

childrenToMask - org.safs.model.Component[], an array of child to filter, if some child is outside of parent, then it will be ignored.

Returns:

boolean, true on success; false otherwise

 
 org.safs.model.Component[] filterChildren = new org.safs.model.Component[5];
 filterChildren[0]=Map.SAPDemoPage.Basc_Button;
 filterChildren[1]=Map.SAPDemoPage.Basc_Radio;
 filterChildren[2]=Map.SAPDemoPage.Basc_Link;
 filterChildren[3]=Map.SAPDemoPage.Basc_Password;
 filterChildren[4]=Map.SAPDemoPage.Basc_TextArea_L;
 GetGUIImage(Map.SAPDemoPage.Panel_Basc, "Panel_Basc_Filtered.png", "", filterChildren);
 //compare with image "Panel_Basc.png", which is not filtered
 GetGUIImage(Map.SAPDemoPage.Panel_Basc, "Panel_Basc.png");
 
 

deduceFilterAreas

public static java.lang.String deduceFilterAreas(Component parent,
                                                 Component[] childrenToMask)

Generate a "filter string" (Filter=x1,y1,x2,y2 x1,y1,x2,y2) according to a parent component and an array of children.
The deduced "filter string" can be used in GetGUIImage(org.safs.model.Component, String, String...) or
VerifyGUIImageToFile(org.safs.model.Component, String, String...).
As the deduced "filter string" contains "Filter=", it will be considered variable-assignment and "Filter=" will be removed,
while GetGUIImage/VerifyGUIImageToFile needs the filterAreas parameter containing "Filter=". To avoid this problem:
It is SUGGESTED to call SAFSPlus.quote(String) to wrap the "filter string" and then pass it to GetGUIImage/VerifyGUIImageToFile
Or make sure the expression-evaluation is off by calling SAFSPlus.DriverCommand.Expressions(boolean)

Parameters:

parent - org.safs.model.Component, the parent component

childrenToMask - org.safs.model.Component[], the children inside the parent component; the child outside of parent component will be ignored.

Returns:

a filter string such as Filter=x1,y1,x2,y2 x1,y1,x2,y2

VerifyGUIImageToFile

public static boolean VerifyGUIImageToFile(Component comp,
                                           java.lang.String benchFile,
                                           java.lang.String... params)

Verify the screen shot of a GUI component with a benchmark image file. See Detailed Reference

Parameters:

comp - Component, the component to get its image.

benchFile - String, the benchmark file name. Suggest to compare with .png image.
It can be relative or absolute. If it is relative, the file will be found at BenchDirectory "Benchmarks".
Supported file extensions are ".jpeg", ".tif", ".gif", ".png", ".pnm", ".bmp" etc.
If the file extension is not supported, then suffix ".bmp" will be appended to filename.

params - optional

params[1] SubArea String, indicating partial image of the component to capture, such as "0,0,50%,50%",
it can be app map subkey under component name.
params[2] PercentageTolerance int, the percentage of bits need to be matched. it is between 0 and 100.
100 means only all bits of images match, the images will be considered matched.
0 means even no bits match, the images will be considered matched.
params[3] UUIDFlag boolean, set to quote("UUID=False") to prevent runtime Test/Actual filenames appended with Universally Unique IDs
This essentially allows the runtime Test/Actual filename to be the same as the Benchmark.
params[4] FilteredAreas String, a set of areas to filter the current GUI image and the bench image before comparing.
it has a prefix "Filter", and followed by a set of subareas. Such as "Filter=0,0,5,5 50%,50%,15,15"
Multiple areas are separated by a space character. The filtered area is covered by black.

Returns:

boolean, true if verification success; false otherwise

Example:

 
 VerifyGUIImageToFile(Map.Google.SignIn,"SignIn");//will be compared with file <testProject>\Benchmarks\SignIn.bmp
 VerifyGUIImageToFile(Map.Google.SignIn,"c:/benchDir/SignIn.gif");
 VerifyGUIImageToFile(Map.Google.SignIn,"c:/benchDir/SignIn.gif", "", "", quote("UUID=False"));// Simple output filename, no UUID.
 VerifyGUIImageToFile(Map.Google.SignIn,"c:/benchDir/SignIn.gif", "", "95");//if 95% bits match, the verification will pass.

 //Following example will verify part of the SingIn image,
 GetGUIImage(Map.Google.SignIn,"SignInPartial.png", quote("0,0,50%,50%"));
 //"subarea" is defined in map file
 //[SignIn]
 //subarea="0,0,50%,50%"
 VerifyGUIImageToFile(Map.Google.SignIn,"SignInPartial.png", "subarea");
 //or
 //"subarea" is defined in map file
 //[ApplicationConstants]
 //subarea="0,0,50%,50%"
 VerifyGUIImageToFile(Map.Google.SignIn,"SignInPartial.png", Map.subarea);
 VerifyGUIImageToFile(Map.Google.SignIn,"SignInPartial.png", Map.subarea());

 //Filter the SingIn image and the bench image at certain areas and compare them
 VerifyGUIImageToFile(Map.Google.SignIn,"c:/benchDir/SignIn.gif", "", "", "", quote("Filter=0,0,10,10 60,60,10,10"));
 //"filterAreas" is defined in map file
 //[SignIn]
 //filterAreas="Filter=0,0,10,10 60,60,10,10"
 VerifyGUIImageToFile(Map.Google.SignIn,"c:/benchDir/SignIn.gif", "", "", "", "filterAreas");
 //"filterAreas" is defined in map file
 //[ApplicationConstants]
 //filterAreas="Filter=0,0,10,10 60,60,10,10"
 VerifyGUIImageToFile(Map.Google.SignIn,"c:/benchDir/SignIn.gif", "", "", "", Map.filterAreas);
 VerifyGUIImageToFile(Map.Google.SignIn,"c:/benchDir/SignIn.gif", "", "", "", Map.filterAreas());
 
 

ExecuteScript

public static boolean ExecuteScript(Component comp,
                                    java.lang.String script,
                                    java.lang.String... scriptParams)

Execute a simple piece of javascript on component synchronously. See Detailed Reference

If the script will return a string value, call SeleniumPlus.prevResults.getStatusInfo() to get it.
Object result is NOT supported yet.
You can also call executeScript(String, Object...) instead, it is more efficient.

Parameters:

comp - org.safs.model.Component, (from generated Map.java).
In your script you reference this DOM WebElement as 'arguments[0]'.

script - String, the javascript to execute.

scriptParams - optional, Script arguments must be a number, a boolean, a String, WebElement, or a List of any combination of the above. An exception will be thrown if the arguments do not meet these criteria. The arguments will be made available to the JavaScript via the "arguments" variable.

scriptParams[0] : Passed to the script as 'arguments[1]', if used.
scriptParams[1] : Passed to the script as 'arguments[2]', if used.
... more script's parameter

Returns:

true if no errors were encountered.

See Also:

executeScript(String, Object...), executeAsyncScript(String, Object...)

Example:

 
 SeleniumPlus.ExecuteScript(
     Map.Google.SignIn,                       // The WebElement passed as 'arguments[0]' to the script.
     "arguments[0].innerHTML=arguments[1];",  // Script to set the WebElements innerHTML value.
     "my text value");                        // The value passed as 'arguments[1]' to set to innerHTML.

 SeleniumPlus.ExecuteScript(
     Map.Google.SignIn,                       // The WebElement passed as 'arguments[0]' to the script.
     "return arguments[0].innerHTML;");       // A script to return the WebElemenbts innerHTML.

  // scriptResult should get the innerHTML value returned.
 String scriptResult = SeleniumPlus.prevResults.getStatusInfo();
 
 

getObject

public static org.openqa.selenium.WebElement getObject(Component component)
                                                throws SeleniumPlusException

Find the WebElement according to the SAFS Component.
This method will use the last webdriver as search context to find element,
if user wants to find an element within an other context, please call #getObject(SearchContext, String)

Parameters:

Component, - The component to search.

Returns:

WebElement, the sought webelement

Throws:

SeleniumPlusException

getObject

public static org.openqa.selenium.WebElement getObject(org.openqa.selenium.SearchContext sc,
                                                       Component component)
                                                throws SeleniumPlusException

Find the WebElement according to the SAFS Component.

Parameters:

sc - could be the WebDriver or a parent WebElement context.

Component, - The component to search.

Returns:

WebElement, the sought webelement

Throws:

SeleniumPlusException

WaitForGUI

public static boolean WaitForGUI(Component comp,
                                 long time)

Wait for a Window or Component to become valid.
Note:
This API doesn't fit for switching according to GUI existence, please use SAFSPlus.Misc.IsComponentExists(org.safs.model.Component, String...) instead.
If the GUI doesn't become valid within timeout, this method will return false.
If the execution doesn't end properly, this method will also return false.
User cannot distinguish these 2 cases; and in the same time, a failure message will be written into Log.

Parameters:

comp - -- Component (from generated Map.java)

time - - time in second

Returns:

true if the GUI appear within the timeout.
false there 2 possibilities:
1. The execution finishes properly but the GUI doesn’t appear within the timeout.
2. The execution doesn't finish properly.

See Also:

SAFSPlus.Misc#IsComponentExists(org.safs.model.Component, String...)

Example:

 
 WaitForGUI(Map.Google.SignIn,10);
 
 

StartTestCase

public static boolean StartTestCase(java.lang.String tcname)

Start capturing test activity counts for a specific application feature or test-case.

Parameters:

tcname - The name of the test-case to start using a Counter on.

Returns:

false only if a failure of some kind was reported in attempting to start the counter.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

StartTestSuite

public static boolean StartTestSuite(java.lang.String suitename)

Start capturing test activity counts for the named test suite.

Parameters:

suitename - The name of the suite counter to start.

Returns:

false only if a failure of some kind was reported in attempting to start the counter.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, TestRecordData.getStatusCode(), TestRecordData.getStatusInfo()

StopTestCase

public static boolean StopTestCase(java.lang.String tcname)

Stop capturing test activity counts for a specific application feature or test-case.

Parameters:

tcname - The name of the test-case to stop. The name must match a counter that was previously started.

Returns:

false only if a failure of some kind was reported in attempting to stop the counter.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, StartTestCase(String), PrintTestCaseSummary(String)

GetVariableValue

public static java.lang.String GetVariableValue(java.lang.String variableName)

Convenience routine to retrieve the value of a SAFS Variable stored in SAFSVARS.
This will exploit the SAFSMAPS look-thru and app map chaining mechanism.
That is, any variable that does NOT exist in SAFSVARS will be sought as an ApplicationConstant in the SAFSMAPS service.

See Test Design Guidelines for Localization.

Parameters:

variableName -

Returns:

String value, or an empty String. Null if an Exception or Error was encountered.

Does not change prevResults.

See Also:

SAFSPlus.prevResults

SetVariableValue

public static boolean SetVariableValue(java.lang.String variableName,
                                       java.lang.String variableValue)

Convenience routine to set the value of a SAFS Variable stored in SAFSVARS.
The act of logging success or failure will change prevResults.

Parameters:

variableName - -- Name of variable to set.

variableValue - -- value to store in variableName.

Returns:

true if successfully executed, false otherwise.

See Also:

SAFSPlus.prevResults, SAFSPlus.DriverCommand.SetVariableValues(String, String...), SAFSPlus.DriverCommand.SetVariableValueEx(String, String)

PrintTestCaseSummary

public static boolean PrintTestCaseSummary(java.lang.String tcname)

Stop capturing test activity counts for a specific application feature or test-case if it is still active, then print a summary report of all tests counted, passed, failed, and skipped, etc...

Parameters:

tcname - The name of the test-case to start using a Counter on. The name must match a counter that was previously started.

Returns:

false only if a failure of some kind was reported in attempting to stop the counter or print the summary report into the log.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults, StartTestCase(String)

PrintTestSuiteSummary

public static boolean PrintTestSuiteSummary(java.lang.String suitename)

Stop capturing test activity counts for the overall suite of tests if it is still active, then print a summary report of all counted, passed, failed, and skipped tests etc...

Parameters:

suitename - The name of the suite to stop (if still running) and process. The name must match a counter that was previously started.

Returns:

false only if a failure of some kind was reported in attempting to stop the counter or print the summary report into the log.

Sets prevResults TestRecordHelper to the results received or null if an error occurred.

See Also:

SAFSPlus.prevResults

AbortTest

public static void AbortTest(java.lang.String reason)
                      throws java.lang.Throwable

Abort running test flow. Prints a detailed abort message to the log and throws a RuntimeException to abort the test run.

Parameters:

reason - will be prepended to the detailed abort information.

Throws:

java.lang.Throwable

See Also:

SAFSPlus.prevResults

Example:

 
 AbortTest("reason for abort");
 
 

Clears prevResults TestRecordHelper to null.

ClickUnverified

public static boolean ClickUnverified(Component comp,
                                      java.awt.Point offset)

Click on any visible component without verification.
This API will not guarantee that the click does happen, it simply clicks. If user wants
to make sure of that, he can call Click(org.safs.model.Component, String...) instead.

Parameters:

comp - -- Component (from App Map) to Click

offset - Point, the offset relative to the component to click

Returns:

true if successfully executed, false otherwise.

See Also:

Click(org.safs.model.Component, String...)

Example:

 
 1) boolean success = ClickUnverified(Map.Google.Apps);//Click at the center
 2) boolean success = ClickUnverified(Map.Google.Apps, new Point(20,20));//Click at the coordinate (20,20)
 

 

WebDriver

public static org.openqa.selenium.WebDriver WebDriver()

Retrieve a reference to the Selenium WebDriver object used by the currently active (last) session.

Returns:

The currently active (last) WebDriver object, or null if there isn't one.

executeAsyncScript

public static java.lang.Object executeAsyncScript(java.lang.String script,
                                                  java.lang.Object... scriptParams)
                                           throws SeleniumPlusException

Following explanations come from Selenium Java Doc.
Execute an asynchronous piece of JavaScript in the context of the currently selected frame or window. Unlike executing synchronous JavaScript, scripts executed with this method must explicitly signal they are finished by invoking the provided callback. This callback is always injected into the executed function as the last argument.

The first argument passed to the callback function will be used as the script's result. This value will be handled as follows:

• For an HTML element, this method returns a WebElement
• For a number, a Long is returned
• For a boolean, a Boolean is returned
• For all other cases, a String is returned.
• For an array, return a List<Object> with each object following the rules above. We support nested lists.
• Unless the value is null or there is no return value, in which null is returned

The default timeout for a script to be executed is 0ms. In most cases, including the examples below, one must set the script timeout WebDriver.Timeouts.setScriptTimeout(long, java.util.concurrent.TimeUnit) beforehand to a value sufficiently large enough.

Parameters:

script - String, the script to execute

scriptParams - optional, Script arguments must be a number, a boolean, a String, WebElement, or a List of any combination of the above. An exception will be thrown if the arguments do not meet these criteria. The arguments will be made available to the JavaScript via the "arguments" variable.

scriptParams[0] Object, Passed to the script as 'arguments[0]', if used.
scriptParams[1] Object, Passed to the script as 'arguments[1]', if used.
... more script's parameter

Returns:

Object or null.

Throws:

SeleniumPlusException

See Also:

SearchObject.executeAsyncScript(String, Object...)

Example:

 
 //Example #1: Performing a sleep in the browser under test.
 long start = System.currentTimeMillis();
 String script = "window.setTimeout(arguments[arguments.length - 1], 500);";
 SeleniumPlus.executeAsyncScript(script);
 System.out.println("Elapsed time: " + System.currentTimeMillis() - start);

 //Example #2: Synchronizing a test with an AJAX application:
 Click(Map.Mail.ComposeButton);
 String script = "var callback = arguments[arguments.length - 1];" +
                 "mailClient.getComposeWindowWidget().onload(callback);";
 Object result = SeleniumPlus.executeAsyncScript(script);
 Component.InputCharacters(Map.Mail.To, "bog@example.com");

 //Example #3: Injecting a XMLHttpRequest and waiting for the result:
 String script =  "var callback = arguments[arguments.length - 1];" +
                  "var xhr = new XMLHttpRequest();" +
                  "xhr.open('GET', '/resource/data.json', true);" +
                  "xhr.onreadystatechange = function() {" +
                  "  if (xhr.readyState == 4) {" +
                  "    callback(xhr.responseText);" +
                  "  }" +
                  "};" +
                  "xhr.send();";
 Object result = SeleniumPlus.executeAsyncScript(script);
 JsonObject json = new JsonParser().parse((String) response);

 

executeScript

public static java.lang.Object executeScript(java.lang.String script,
                                             java.lang.Object... scriptParams)
                                      throws SeleniumPlusException

Following explanations come from Selenium Java Doc.
Executes JavaScript synchronously in the context of the currently selected frame or window. The script fragment provided will be executed as the body of an anonymous function.

Within the script, use document to refer to the current document. Note that local variables will not be available once the script has finished executing, though global variables will persist.

If the script has a return value (i.e. if the script contains a return statement), then the following steps will be taken:

• For an HTML element, this method returns a WebElement
• For a decimal, a Double is returned
• For a non-decimal number, a Long is returned
• For a boolean, a Boolean is returned
• For all other cases, a String is returned.
• For an array, return a List<Object> with each object following the rules above. We support nested lists.
• Unless the value is null or there is no return value, in which null is returned

Parameters:

script - String, the script to execute

scriptParams - optional, Script arguments must be a number, a boolean, a String, WebElement, or a List of any combination of the above. An exception will be thrown if the arguments do not meet these criteria. The arguments will be made available to the JavaScript via the "arguments" variable.

scriptParams[0] Object, Passed to the script as 'arguments[0]', if used.
scriptParams[1] Object, Passed to the script as 'arguments[1]', if used.
... more script's parameter

Returns:

Object or null.

Throws:

SeleniumPlusException

See Also:

SearchObject.executeAsyncScript(String, Object...)

Example:

 
 //set "your text" to innerHTML of component Map.Google.SignIn
 WebElement we = SeleniumPlus.getObject(Map.Google.SignIn);
 String script = "arguments[0].innerHTML=arguments[1];";
 List<Object> params = new ArrayList<Object>();
 params.add(we);//arguments[0]
 params.add("your text");//arguments[1]
 SeleniumPlus.executeScript(script, params.toArray(new Object[0]));

 //get innerHTML of component Map.Google.SignIn
 script = "return arguments[0].innerHTML;";
 params.clear();
 params.add(we);//arguments[0]
 Object result = SeleniumPlus.executeScript(script, params.toArray(new Object[0]));
 

main

public static void main(java.lang.String[] args)

Internal framework use only. Main inherited by subclasses is required. Subclasses should not override this main method.

Any subclass specific initialization should be done in the default no-arg constructor for the subclass. That Constructor will be instantiated and invoked automatically by this main startup method.

By default will seek an AppMap.order file. However, the user can specify an alternate AppMap order file by using the following JVM argument:

Examples:
• -Dtestdesigner.appmap.order=AppMap_en.order, or
• -Dtestdesigner.appmap.order=AppMap_ja.order, or
• -Dtestdesigner.appmap.order=AppMap_win.order, or
• -Dtestdesigner.appmap.order=AppMap_mac.order
• etc...

By default, the Browser Type that will be used is FireFox. The user can specify a different default browser by using the following JVM argument SelectBrowser.SYSTEM_PROPERTY_BROWSER_NAME:

-DBROWSER=explorer
-DBROWSER=chrome
-DBROWSER=firefox
etc...

By default, the RemoteServer that will be used is at host and port: localhost:4444 . The user can specify a different host and/or port (grid) by using the JVM arguments SelectBrowser.SYSTEM_PROPERTY_SELENIUM_HOST and SelectBrowser.SYSTEM_PROPERTY_SELENIUM_PORT:

-Dselenium.host=localhost or
-Dselenium.host=L12345.company.com
-Dselenium.port=5555

By default, a Debug Log is usually enabled and named in the test configuration (INI) file. The user can specify or override the name of this debug log file by using the following JVM argument:

-Dtestdesigner.debuglogname=mydebuglog.txt

Parameters:

args - --

-safsvar:name=value

(Any number of these can be provided to preset variables or override App Map Constants. Note the entire argument must be enclosed in quotes if there are spaces in it.)

 -safsvar:platform=win8 -safsvar:browserType=firefox "-safsvar:spacedpath=C:\Project With Spaces\Special Directory"

-autorun -- Perform Dependency Injection, AutoConfig, and AutoExecution if "-autorun" is provided.

-autorunclass -- followed by the class that is requesting the automatic configuration and execution, only take effect when parameter '-autorun' is present.

-autorunclass autorun.full.classname

-junit:classname -- perform a JUnit test instead of executing runTest() in the SeleniumPlus subclass.
The normal SeleniumPlus bootstrap process and initialization is performed prior to executing the JUnit test.

-junit:com.sas.spock.tests.SpockExperiment

See Also:

AutoConfigureJSAFS, JSAFSBefore, JSAFSAfter, JSAFSTest, InjectJSAFS