SeleniumPlus Welcome

Thanks for giving SeleniumPlus a try!

Select any of the links above ("Project Assets", "Sample Project" etc.) to go directly to an area of interest.

We welcome any feedback (both good and bad) that can help us make the test automation experience better!

When meeting any problem, please

1. Visit SE+ FAQ
2. Post thread at SE+ Discussion
3. Contact us at SAFS DEV Group

The SAFS/SeleniumPlus Development Team

Carl Nagle
Lei Wang
John W. Lewis

Try a SAMPLE Project

Create the Sample Project

1. Right-click in the Package Explorer view.
2. Select "New->Project..." in the popup menu.

   

3. Select "Selenium+ ->Selenium+ Sample Project" in the New Project dialog and click "Next".

   

4. Make sure "Use default location" is selected and click "Finish" in the dialog.
5. If prompted to Associate the project with the Selenium+ perspective select the "Remember my decision" CheckBox and click "Yes".

   

6. The SAMPLE project should now be installed for your review and experimentation.

   

Review the Sample Project

The SAMPLE project shows one desirable way to put together a suite of tests.
1. The root SAMPLE folder will contain the project's "test.ini" configuration file.
2. The TestCases package can hold one or more classes of simple testcase actions as shown in the TestCase1.java class.
3. The TestRuns package can hold one or more classes that piece together test suites that run testcases in any desired sequence as shown in the TestRun1.java class.
4. The Actuals folder may receive captured runtime files, data, or images.
5. The Benchmark folder will contain benchmark files, data, or images when required.
6. The Diffs folder may receive runtime compare differences in files, data, or images.
7. The Logs folder will receive test log(s) at the end of a test.
8. The Maps folder will contain tester-defined App Map files and the AppMap.order file used during testing.

   

Run the Sample Project

1. In the Package Explorer, select "SAMPLE->Tests->sample.testruns->TestRun1.java"
2. In the main menu, select "Run->Run As->Selenium+ Test".
   (The test should automatically start and run with Google in Firefox.)
3. When the test completes, Package Explorer should show a "TestRun1.txt" file in the "SAMPLE->Logs" folder.
   (You may have to hit Refresh(F5) for the Package Explorer to update.)
4. Double-click "TestRun1.txt" or right-click it to "Open With...->Text Editor" to see the test results.

Create and Review a New Project

Create a New Project

1. Right-click in the Package Explorer view.
2. Select "New->Project..." in the popup menu.

   

3. Select "Selenium+ ->Selenium+ Project" in the New Project dialog and click "Next".
4. Enter a name for the project and click "Finish" in the dialog.
5. If prompted to Associate the project with the Selenium+ perspective,
   select the "Remember my decision" CheckBox and click "Yes".

   

6. The new project should now be created for your review and experimentation.

   

Review the New Project

The new project provides a way to put together a suite of tests.
1. The root project folder will contain the project's "test.ini" configuration file.
2. The TestCases package can hold one or more classes of simple testcase actions.
   An empty TestCase1.java class is initially provided.
3. The TestRuns package can hold one or more classes that piece together test suites that run testcases in any desired sequence.
   An empty TestRun1.java class is initially provided.
4. The Actuals folder may receive captured runtime files, data, or images.
5. The Benchmark folder will contain benchmark files, data, or images when required.
6. The Diffs folder may receive runtime compare differences in files, data, or images.
7. The Logs folder will receive test log(s) at the end of a test.
8. The Maps folder will contain tester-defined App Map files and the AppMap.order file used during testing.

   

Import Existing Projects

SeleniumPlus Projects, like the SAMPLE project, are intended to be portable for other users and machines with SeleniumPlus installed. The entire Project should be saved--whether to CVS, GIT, or some othe storage medium. Although the "bin" subdirectory for the Project is generally not stored since these are compiled assets.

For example, to Import a Project that has been copied or saved to the local file system:

1. Select "File->Import..." from the Eclipse main menu,
2. Select "General->Existing Projects into Workspace" in the Import dialog and press "Next",
3. Press "Browse" on the "Select root directory:" item in the Import dialog and,
   Locate and select the root directory containing the Project folder in the local file system.
   The directory name should be the same name of the Project.
4. Press "OK" to confirm your folder selection.
5. Press "Finish" to complete the Import of the Project.

   Note: Eclipse will NOT let you have/import two projects with the same name.

Importing older SeleniumPlus projects may require you to "fix" some of the paths in that Project's Java Build Path configuration and in each test configuration INI file (Test.INI) used for testing.

Newer SeleniumPlus projects have been created with the information that follows so they are already portable to different machines. For these newer projects you should not have to "fix" anything.

Evaluating/Fixing Imported Projects

The latest versions of SeleniumPlus now support 2 features to maximize (or fix) Project portability:

1. SELENIUMPLUS_HOME: Java Build Path Classpath Variable.
2. %SELENIUM_PLUS%: Test.INI  [SAFS_DRIVER]  DriverRoot.

For more detailed information on each:

1. SELENIUMPLUS_HOME: Java Build Path Classpath Variable.

Automatically created by the latest version of the SeleniumPlus PlugIn.
Defines the path to the SeleniumPlus install directory. The value should be the same as the System's Environment Variable: %SELENIUM_PLUS%.

The setting can be found in the Eclipse main menu under:

Window->Preferences->Java->Build Path->Classpath Variables

New Projects created with the latest PlugIn will now automatically use this SELENIUMPLUS_HOME Classpath Variable for the Project's Java Build Paths. You can see the Project's Java Build Paths by:

1. Right-Click on the Project in the Package Explorer,
2. Select "Build Path->Configure Build Path.." in the popup menu,
3. Select "Java Build Path" in the Properties Dialog for the project,
4. Select the "Libraries" tab in the Java Build Path panel of the dialog.

Currently, you should see settings using SELENIUMPLUS_HOME like:

Java Build Path entries:

SELENIUMPLUS_HOME/libs/JSTAFEmbedded.jar
SELENIUMPLUS_HOME/libs/selenium-server-standalone-2.44.0.jar
SELENIUMPLUS_HOME/libs/seleniumplus.jar

Fixing the Java Build Path for Portability

If your existing projects instead have explicit hardcoded paths to these files then they are less portable. The machine importing your project may have SeleniumPlus installed in a different location.

To fix such a portability issue, you can replace the explicit hardcoded library paths with new ones referencing and extending the SELENIUMPLUS_HOME Classpath Variable. You can do this by:

1. Note the explicit hardcoded path for each listed JAR file coming from the SeleniumPlus /libs/ directory,
2. Select "Add Variable" in the Java Build Path dialog,
3. Select the "SELENIUMPLUS_HOME" Variable and then press "Extend...",
4. Select the appropriate JAR file in the "libs" directory in the Variable Extension dialog,
5. Press "OK" and the new Java Build Path entry like those above should now be present,
6. Select the older explicit hardcoded path entry you just replaced and select "Remove" to delete it from the list.
7. Do this until all old explicit hardcoded path entries to SeleniumPlus JAR files have been properly replaced.

2. %SELENIUM_PLUS%: Test.INI  [SAFS_DRIVER]  DriverRoot.

Automatically created by the latest version of the SeleniumPlus PlugIn, Nov 18, 2014 or later.
Defines the path to the SeleniumPlus install directory by retrieving it from the System Environment variable of the same name. The value is used in the DriverRoot setting of the Test.INI file to dynamically get the path to SeleniumPlus--which might be different on different systems.

NOTE: This setting will only work on SAFS or SeleniumPlus with installed or updated JARs dating Nov 18, 2014 or later.

The JAR files in question are:

SAFS:	/lib/safsselenium.jar
SeleniumPlus:	/libs/seleniumplus.jar

The portability setting can be found in the Test.INI as:

[SAFS_DRIVER]
DriverRoot="%SELENIUM_PLUS%\extra\automation"

Fixing the Test.INI file for Portability

If your existing projects instead have explicit hardcoded paths for this setting then they are less portable. The machine importing your project may have SeleniumPlus installed in a different location.

To fix such a portability issue, you can replace the explicit hardcoded DriverRoot path in the Test.INI with the same setting as shown above.

App Maps provide a critical single point of maintenance for important data and component recognition used throughout your tests.

Create new App Map file

Right click on Maps folder of the project, click "Selenium+->Create Map" to create new App Map file.
A new App Map will be created with .map extension. User can create multiple map files to separate language-specific component recognition strings and/or test configuration data.

Examples:

ProjectApp_en.map
ProjectApp_fr.map
ProjectApp_es-CO.map
ProjectApp_W7.map
ProjectApp_W8.map

The AppMap.order File

In general, there is a "primary" ProjectApp.map file which holds the bulk of all recognition strings and Application Constants. Then, there can be one or more App Map files containing language-specific values used by or overriding the primary App Map values.

The AppMap.order file is a means to chain multiple App Maps to be loaded in a specific order.

Example:

;
; Order App Maps Last In First Out (LIFO) for "chaining"
;
App.map
App_fr.map

The App Map Details

Review: App Map Format Info


Normally, an App Map contains multiple "sections". One of these is [ApplicationConstants] and the remaining user-defined sections are used to define "windows" or "containers" of components.

ApplicationConstants stores all test constants and data.

;
; Constants and other data.
;
[ApplicationConstants]
nlsSearch="Search"
url="http://www.google.com"
username="anonymous"
password="newpassword"

Window or Container sections hold recognition strings used to identify child components within those containers.

In a container section, the item with the same name as the container is optional.

Example: Google="id=viewport" is optional,
See the [Login] section? There is no "Login" item in that section. The default will be assumed (See the Note below.)

;
; Component recognition:
;
; Google main page window/component recognition
;
[Google]
Google="id=viewport"
Apps="title=Apps"
Search="text={^nlsSearch}"

;
; Google's Login window/component recognition
;
[Login]
UserName="name=Email"
Password="name=Passwd"
SignIn="id=signIn"

Note:
The item with the same name as the container (ex. "Google" and "Login"), if present, MUST contain a recognition string that *will* find the parent container of the contained children.  When searching for a child, the parent is sought first.
If the parent is not found, then the search for the child will NOT occur.

If the item with the same name as the container is NOT provided, the default container to search is assumed to be the topmost document of the webpage, or the topmost document in any frame or iframe that was last searched.

Component Recognition Strings or Object Locators

There are many ways to create component "recognition strings"(RS). The RS must be unique for the page, or unique for the specific parent container, if that was provided.
Specify a FRAME RS for the parent container, if frames are in-use:

FRAMEID=my_content_frame_id
FRAMENAME=my_content_frame_name
FRAMEXPATH=//iframe[@id='frameId']
FRAMEINDEX=N (1=first frame) RS by Index is not recommended.

(note: parent/child hierarchy is separated by ";\;" )
(note: If there is no frame-expression in a RS, the last visited frame
	   will be searched to find child components.
	   By default, the last viisited frame is the main frame.
	   And that is why if we specify a frame container, the children
	   do not need to specify the parent frame in their RS.

For example:

[HelpPopup]
HelpPopup="FRAMEID=VisualAnalyticsHubLogon_iframe"
BtnHelpCenter="id=__item23"

BtnHelpCenter is expected to be found in frame 'VisualAnalyticsHubLogon_iframe')
    

For child components, use supported type, property and attribute qualifiers, as necessary:

:PASM:  (Property Attribute Search Mode -- Must be first, if present. See Notes.)
TYPE="DOJO"|"SAP"; (See Notes.)
ID=id;
CLASS=class;
NAME=name;
TEXT=text;
TITLE=title;
LINK=linkInfo;
PARTIALLINK=partialLinkInfo;
TAG=tagname;
INDEX=n;                         (1-based, NOT used alone, indicates the Nth matching item.)
ITEMINDEX=n;                     (1-based, NOT used alone, indicates the Nth matching list item.)
PATH=parent->child->grandchild;  (NOT used alone. Path to a subitem in a List, ComboBox, Menu, Tree)
PROPERTY=propname:propvalue;             (can be used with others to provide more uniqueness)
PROPERTYCONTAINS=propname:partialValue;  (can be used with others to provide more uniqueness)

Notes:
Multiple qualifiers should be separated by semi-colons (";").
TYPE= is experimental and only supports "DOJO" and "SAP" at this time. Do not use.
:PASM: if used, means everything that follows is explicitly property=value pairs.

No PASM: Example 1:


MyObject="Text=Some Text;enabled=true;ItemIndex=2;"



"TEXT" and "ITEMINDEX" are known qualifiers--not property names,
while "enabled"--which is NOT a known qualifier--will be treated
as a native object property/attribute to match.

PASM: Example 2:


MyObject=":PASM:text=Some Text;enabled=true;itemindex=2;"



With ":PASM:" leading; "text", "enabled", and "itemindex" are all sought as native object
property/attribute values that must be matched.

Identify child elements by multiple native properties or attributes:

MyObject="aproperty=xxx;someattribute=yyy;anotherone=zzz"



You don't need :PASM: if none of the properties or attributes have the same
names as our qualifiers above.

Identify child objects using explicit XPATH or CSS RS:

MyObject="XPATH=.//div[contains(text(),'foo')]"
MyObject="CSS=div:contains('foo')"

Capture Recognition Strings - Browser Tools

Generally, the 3 major browsers seem to support the same or similar mechanism for inspecting web page elements.

1. Navigate to the desired application in the browser.
2. Press "F12" to display the browser Object Inspector.
   If "F12" does not do it then try Ctrl+Shift+C or Ctrl+Shift+I or consult your browser documentation for launching the Inspector.
3. Click the Inspector tool and then Click the desired application component.

   FireFox:
   

   Chrome:
   

   IExplore:
   

4. The Inspector panels should now show detailed information about the selected application component highlighted in the console.
5. If present, click the Inspector's "Attributes" tab (or equivalent) to see attributes (name="value" properties) for the component.

6. Common attributes to use for recognition are: name, type, id, title, value, and text.
   
   • 'text' is not a real 'attribute', but we support it as such.
   • Whenever using visible (and localizable) text as part of the recognition string, be sure to parameterize the recognition string in the App Map as discussed in the Test Design Guidelines.

7. Identify one or more attributes that together uniquely identify the component.
8. Multiple attributes can be used in the AppMap recognition string when separated by a semi-colon:
   Format:
   ComponentName="<recognition>"
   • OK="id=btnK"
   • OK="id=btnK;class=btn;name=OK"

   A Primary App Map hypothetically for Google (App.map):
   

   ;
   ; Constants and other data.
   ;
   [ApplicationConstants]
   nlsSearch="Search"
   
   ;
   ; Main Google window/component recognition
   ;
   [Google]
   Google="id=viewport"
   Apps="title=Apps"
   Search="text={^nlsSearch}"
   
   ;
   ; Google's Login window/compoent recognition
   ;
   [Login]
   Login="id=viewport"
   UserName="name=Email"
   Password="name=Passwd"
   SignIn="id=signIn"
   

   A French App Map to override the "Search" text in the Primary App Map (App_fr.map):
   

   ;
   ; Constants and other data.
   ;
   [ApplicationConstants]
   nlsSearch="Recherche"
   

Capture Recognition Strings - Selenium ProcessContainer

There is a SeleniumPlus ProcessContainer tool that can be used to interactively capture, modify, and test recognition strings natively using the SAFS/Selenium engine with the Selenium WebDriver. This can be used instead of--or in addition to--the Browser Tools mentioned above.



Review the SeleniumPlus ProcessContainer doc for more complete usage notes.

In particular, note that Selenium and SeleniumPlus only seek components ("Find Element") in the currently identified Frame or iFrame, if frames exist.  If you get "No Such Element" or "...not found." for a particular Recognition: string you believe is good, it may be we are looking in the wrong Frame.

So, when attempting "Find Element" with ProcessContainer, you must do one of the following:

• Search and then select the appropriate Frame in ProcessContainer before finding elements in it.

  Example:
  Recognition: XPATH=.//*[@id='aChildComponent_id']

  or

• Properly prepend the FRAMEID in the Recognition string for the elements.

  Example:
  Recognition: FRAMEID=myApps_iframe;\;XPATH=.//*[@id='aChildComponent_id']

Test Design Guidelines
App Map Format Info
Historic App Map Info

Specific "Categories" and "Qualifiers" in the above docs may not (yet) be supported by SeleniumPlus.

SAFS Expressions

A fundamental overview of SAFS Expression Processing.

Historically, expression processing happens on every "field" for every action or command in a SAFS "inputrecord". The JSAFS Java code that SeleniumPlus is based upon retained that functionality.

Expression processing is "ON" by default.

That is, for any String argument or parameter passed to a SeleniumPlus class "action" or "command" there will be an attempt to process that String argument for possible expressions. (Note, that calls to other libaries that are NOT in the SeleniumPlus class--like WDLibrary, SearchObject, or WebDriver--do NOT have arguments processed for expressions.)

If the action/command String argument is
NOT enclosed in double-quotes, and
DOES contain expression operators,
THEN it will get processed and changed accordingly.

Operators that trigger String changes in action/command arguments:

       ^                    '(Caret) Variable Prefix
       =                    'Assignment operator
       "                    'A single Double-Quote mark
       &                    'String concatenate operator
       +                    'Addition operator
       -                    'Subtraction operator
       *                    'Multiplication operator
       /                    'Division operator
       %                    'Modulus/Remainder operator
       (                    'Open Group operator
       )                    'Close Group operator

We have found that most SeleniumPlus users DO NOT need or want Expression processing enabled for the majority of their "action" or "comand" calls. Until an easy "fix" is available that does not break tests for existing JSAFS and SeleniumPlus users there are two options for controlling this:

1. Enclose these String arguments in double-quotes.

   There is a (somewhat) convenient quote() method available in your TestCase or TestRun for doing this.
   

   Example:

   Click(Map.Content.Canvas, quote("15,-20"));

   Because the (-) subtraction operator exists in the string we have to quote() it to avoid expression processing.

2. Alternatively/As needed--or at the very beginning of all your tests--disable Expressions:
   Misc.Expressions(false);

   This should make enclosing these String arguments with quote() unnecessary.

   Example:

   Misc.Expressions(false);
   ...
   Click(Map.Content.Canvas, "15,-20");

   Because Expressions are OFF, the (-) subtraction operator should not trigger expression processing and the argument should not need to be quoted.

Adding and Editing Tests

Adding TestCase Classes

1. In the Package Explorer,
   right-click on the TestCases package folder in your Project and select "Selenium+ ->Create Test File" in the popup menu.
2. Enter a unique Test Class name (Ex: "Login") for the new class and click OK.
3. A new TestCase class (Ex: "Login.java") should now exist in the TestCases package folder.

Adding TestCase Methods

1. Make sure the target TestCase class is open for editing in the main content view of Eclipse.
2. Click inside the TestCase class file on the line where you wish to insert the new testcase method.
   (Do NOT insert it in the ignored runTest() method of the the TestCase class!)
3. Right-click on the insertion line and select "Selenium+ ->Insert Test".
4. A new test method is inserted ("Test01" by default).
5. Rename the method as desired. (Ex: EnterUserID() instead of Test01())

Referencing AppMap Constants

1. There is a Map class that provides access to the ApplicationConstants stored in your AppMaps.
2. Sample AppMap ApplicationConstants entry:

   ;
   ; Constants and other data.
   ;
   [ApplicationConstants]
   GoogleURL="http://www.google.com"
   

3. To reference the NAME of the GoogleURL variable (not the value):
   Map.GoogleURL

4. To reference the VALUE of the GoogleURL variable (not the name):
   Map.GoogleURL()

5. Note: The value of a given item is retrieved at runtime via GetVariableValue calls.
6. It is possible for a test to alter the value of these "constants" at runtime.
7. Thus, at runtime, the value might NOT be the value as originally stored in the AppMap.

Calling SeleniumPlus Actions and Commands

1. To see a list of ALL available SeleniumPlus Actions and Commands:
   1. Place the edit cursor where you wish to insert the call in your TestCase method.
   2. Type "SeleniumPlus." (the dot is explicitly needed to show the list.)
   3. A list of commands and subclasses of commands will display.
   4. Single-click an item in the list to get detailed help and information.
   5. Click inside the displayed help to scroll and view all available information.
   6. Double-click the item in the list to insert the call into your code.
   7. If selecting a subclass of commands (ComboBox, EditBox, Files, etc..),
      you will need to press the dot (.) again to see and select from the list of commands provided by the subclass.
      Example: "SeleniumPlus.EditBox." to show the list of EditBox commands.

      (Note: Once you are familiar with the commands and subclasses, you don't have to type the "SeleniumPlus." prefix.
      You can just type the command name or subclass name directly.)

   8. Provide the needed values or variables to any parameters needed by the command.
   9. Remember, every program statement must end with a semi-colon.

2. To see a list of only the immediate SeleniumPlus Actions and Commands:
   1. Place the edit cursor where you wish to insert the call.
   2. Hold down the Ctrl key and press SPACE.
   3. A list of commands and subclasses of commands will display.
   4. Single-click an item in the list to get detailed help and information.
   5. Click inside the displayed help to be able to scroll or view all information.
   6. Double-click the item in the list to insert the call into your code.
   7. Provide the needed values or variables to any parameters needed by the command.
   8. Remember, every program statement must end with a semi-colon.

Adding TestRun Classes

1. In the Package Explorer,
   right-click on the TestRuns package folder in your Project and select "Selenium+ ->Create Test File" in the popup menu.
2. Enter a unique Test Class name (Ex: "SmokeTest") for the new class and click OK.
3. A new TestRun class (Ex: "SmokeTest.java") should now exist in the TestRuns package folder.
   (Note: TestRun class calls many TestCase's methods, like main file)

Calling TestCases from your TestRun classes

2. To see a list of ALL methods in a given TestCase class:
   1. Place the edit cursor where you wish to insert the TestCase call in your TestRun runTest() method.
   2. Type "<testcaseclass>." (the dot is explicitly needed to show the list.)
      Ex: "TestCase1."
   3. A list of testcases (methods) of the TestCase1 class will display.
   4. Single-click an item in the list to get detailed help and information.
   5. Click inside the displayed help to scroll and view all available information.
   6. Double-click the item in the list to insert the call into your runTest() method.
   7. Provide the needed values or variables to any parameters needed by the command.
   8. Remember, every program statement must end with a semi-colon.

Automatic Configuration

Classes in your "current" project will automatically receive RuntimeDataAware-ness at Runtime (i.e. when the test is run.) These classes will receive required object instances at runtime for doing things like retrieving values out of the runtime App Maps.

You normally don't have to think or worry about this because it happens for you behind the scenes every time you run a test. If you only use classes in your current Project, and don't reference Maps or Utility classes from other SeleniumPlus projects, then you can stop reading this and explore other sections of the Intro.

However, if you DO reference "other" SeleniumPlus projects in your current project--like an external "helper" project--or other projects that have runtime functionality you want to share and NOT duplicate--then you do need to consider the following.

Classes in those "other" projects that are not the "current" project will NOT receive their normal RuntimeDataAware-ness at runtime. This can present a problem if your try to use another project's testcases, or if you try to use those other projects' Map classes:

    String val = helper.Map.SomeConstant();

The call will work normally when that project is the "current" project, but it may not work correctly if it is the "other" project. You can verify this by reviewing the Debug Log after a run. The Debug Log will show which packages and classes were checked for automatic injection of RuntimeDataAware-ness. The classes in the "other" project will NOT be listed in the log.

To fix this runtime issue:

• Any Class--usually any one testcase or testrun (except the dynamically generated Map class)--you have in the "current" project can be modified to support automatic injection of RuntimeDataAware classes in other projects referenced at runtime. Those other project classes must be in the Classpath (or BuildPath) of the current project. In other words, those other external classes have to be findable at runtime.

• To the desired Class in the current project, you add a Java annotation right above the Class definition. Below I show a sample.Utilities class as an example of enabling:
  @AutoConfigureJSAFS(include="mypackage.Map;another.package.Map")
  public class Utilities extends SeleniumPlus {
  ...
  

  The above example tells SeleniumPlus to check all classes in:

  • "mypackage" package and all its subpackages, and
    
  • "another.package" package and all its subpackages.

• You only have to place this annotation on any one class in your current project--perhaps a Utilities class?
  (But not the dynamically generated Map class.)

• The annotation will enable this for all tests in the current project.
  This is because when we check to auto-inject dependencies for a test/Class we check all classes in the same packages and all subpackages of that test/Class.

• The compiler may warn/inform you that you need to import the AutoConfigureJSAFS annotation class:
  import org.safs.model.annotations.AutoConfigureJSAFS;

Recompile and Run and the issues encountered in the "other" project(s) should be resolved.

You can review the Debug Log after the Run and you should see where injecting the RuntimeDataAware classes in the "other" project(s) was attempted.

Running Tests

Run a Project TestRun Class

1. Only SeleniumPlus subclasses with executable content in the runTest() method can be executed as tests.
2. In the Package Explorer, select the desired TestRun or TestCase Java file in your Project.
3. In the main menu, select "Run->Run As->Selenium+ Test".
   (The test should automatically start.)
4. When the test completes, Package Explorer should show the resulting log file in the Project's Logs folder.
   (You may have to hit Refresh(F5) for the Package Explorer to update.)
5. Double-click the log file or right-click it to "Open With...->Text Editor" to see the logged results.

Command-line TestRun

1. Open your project's runAutomation.bat in text editor. (e.g: C:\SeleniumPlus\SAMPLE\runAutomation.bat)
2. Verify/Replace "< package name>" with actual package name. (e.g: sample.testruns.TestRun1)
3. open command-line window.
4. cd to the project dir.
5. run runAutomation.bat file.

   example:

   From cmd window

   cd c:\SeleniumPlus\SAMPLE
   runAutomation.bat
   

   Note: See runAutomation.bat file for how to override App Map variables and App Map order.

Logging

SAFS and SeleniumPlus normally log a significant amount of information into the test log. This normally includes generic info as well as pass and fail information for test records.

The test INI file can be configured to change the LOGLEVEL for information sent to the logs.
The valid values for LOGLEVEL are:

1. "INFO"   -- the normal default setting.
2. "WARN"  -- log only warnings and errors.
3. "ERROR" -- log only errors.

;
; Test Info
;
[SAFS_TEST]
...
LOGLEVEL="INFO"
...

Note that "Counters" are still counting all records--including PASS and FAIL counts regardless of how the log is being filtered. However, if the LOGLEVEL is set to WARN or ERROR then the traditional test count summary that normally appears in the log will NOT be logged since they are not WARNings or ERRORs. This is a good thing for those that don't like the summary. It is a bad thing for those that do.

In SeleniumPlus we have provded some new Logging commands that allow the tester/developer to change the LOGLEVEL dynamically at runtime:

• SeleniumPlus.Logging
  SuspendLogging
  ResumeLogging
  SetLogAllInfoMode
  SetLogWarningsAndFailuresMode
  SetLogFailuresOnlyMode
  

Logging.SetLogAllInfoMode()

This will enable that end-of-log test summary to make it into the log.

Asserts

• SeleniumPlus.Assert
  setAbortOnFailure(true/false)

Only failed Asserts appear in the log. However, just like all other tests, the PASS/FAIL information increments in the test record Counters--which can be queried--will print to the log if the LOGLEVEL is set to the default "INFO".

Backup Tests with CVS

Check-in project into CVS repository

1. Right click on the project to be checked-in.

   

2. Select "CVS"" and "Next".

   

3. Enter CVS host, repository path, uname, password and click "Next"".

   

4. Create or Use existing repository and click "Next".

   

5. Enter project name as module name.

   

6. Verify check in resources.

   

7. Enter inital check-in comment and click "Finish".

   

Exmaple: Check-in, Check-out or Compare tests against CVS

1. Right click on File or Project.

   

Check-out Tests from CVS

Check-out project from CVS repository

1. Right click on the Package Explorer area to import the project.

   

2. Select "CVS->Projects from CVS" and "Next".

   

3. Enter CVS host, repository path, uname, password and click "Next"".

   

4. Select module/project and click "Next".

   

5. Check-out project and click "Finish".

   

6. Check-out project assets .

   

7. (Optional) If the project shows compile error then correct java build path, Right click on the Project->Properties.

   

8. Update or Verify DriverRoot location in test.ini file.

   		[SAFS_DRIVER]
   		DriverRoot="c:\seleniumplus\extra\automation"
   		

Exmaple: Check-in, Check-out or Compare tests against CVS

1. Right click on File or Project.

   

Advanced Users

The modified SeleniumPlus Eclipse IDE with the SeleniumPlus PlugIn provides many convenience features and a simplified interface for novice programmers. This includes certain levels of Eclipse interface filtering or hiding that may not be desirable for developers already comfortable with the Eclipse IDE--or even some other Java development environments.

It is possible to develop SeleniumPlus tests without these conveniences in your existing Eclipse environment or other Java IDE.

Primary concerns for standard IDE development:

1. Appropriate SeleniumPlus and Selenium JAR files included in the Build Path for the project.
2. Ideally, App Map text files to be visible and editable within the IDE.
3. The manual or automatic execution of the Dynamic Map.java Generator program any time the text App Map files are edited or modified.

Primary concerns for test execution:

1. SeleniumPlus--or SAFS and its STAF dependency--must be installed and configured for proper SAFS execution.
2. A SeleniumPlus Project or comparable SAFS Project must exist with all necessary test files--primarily:
   • AppMap and AppMap.order files,
   • test.ini, or other test configuration file.
3. The test configuration file (test.ini) must be configured to match the SeleniumPlus or SAFS Project location to be used.
4. The command-line invocation must invoke the desired SeleniumPlus subclass to execute and the test configuration file (test.ini) to be used for test configuration.

Setup Internet Explorer

For Internet Explorer the user should make sure "Protected Mode" and the Status Bar are disabled.

Disable "Protected Mode"

1. In the Internet Explorer Tools menu, or via the Internet Options in Control Panel,
   access the Internet Options dialog.
2. Select the Security Tab.
3. Make sure the "Enable Protected Mode" item is disabled--NOT selected.
4. Click "OK" to save the setting and close the dialog.
5. This may require a restart of Internet Explorer if the mode was changed.

   

Disable the Status Bar

1. In the Internet Explorer View menu, access and disable (uncheck) the Toolbars->Status Bar option.
2. This may require a restart of Internet Explorer if the mode was changed.

   

For IE 11 only

• For 32-bit Windows installations, the key you must examine in the registry editor is: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_BFCACHE.
• For 64-bit Windows installations, the key is: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_BFCACHE.

Appendix: Selenium Offical settings of InternetExplorerDriver

About Profile and Preferences

1. Start web browser with persistent custom profile.
2. Start web browser with default profile and set the preferences at runtime.

Using custom profile

1. Start Firefox

   • Prepare the profile
     1. Run "firefox.exe -ProfileManager -no-remote" in Windows Start "Search" input box.
     2. Create custom profile "myprofile" and configure custom setting
        
   • Examples:
     
     1. Start Firefox with the custom profile "myprofile"

        1
        2
        

        String profile = "myprofile";
        StartWebBrowser(URL, ID, SelectBrowser.BROWSER_NAME_FIREFOX, "30", "true", SelectBrowser.KEY_FIREFOX_PROFILE, profile);
        

2. Start Chrome

   Chrome's profile is a little different from Firefox's. There is a "user data pool" and under that "data pool" there are multiple users. Among these users, there is a Default user. SeleniumPlus can start browser with a "user data pool" and a certain "user". If the "user" is not specified, then the Last Active user will be used.
   • Prepare the profile
     1. Create custom data pool by running "chrome.exe --user-data-dir=c:\chrome_custom_data". This command will start up a chrome browser and a new folder c:\chrome_custom_data will be created. Under that folder there is a sub folder Default, which is for the default user.
     2. Create multiple users, then under folder c:\chrome_custom_data, there will be sub folder "Profile 1", "Profile 2" etc. for those new added users.
        
        • Open chrome settings: click the button to show a pop-up menu, and then click the item "Settings".
          
        • Add new person: click the button "Add person..."
          
     3. Modify chrome settings (chrome://settings/ or chrome://flags/) manually, and the new settings will be kept in this custom profile for current active user. As this chrome is started the first time by "chrome.exe --user-data-dir=c:\chrome_custom_data", the current active user will be Default user. Refer to the following snapshot, the Default user is "Person 1" marked with (current), which means it is active. Later, with more users added, the active user could be anyone.
        
        If we want to change the settings for another user, we need to start chrome with the option profile-directory, for example, run chrome.exe --user-data-dir=c:\chrome_custom_data --profile-directory="Profile 1", and then modify the chrome settings manually for him.
        

   • Examples:
     
     1. Start Chrome with the custom data pool "c:\chrome_custom_data" and Last Active user, the Last Active could be "Default User" or any other one.

        1
        2
        

        String datapool = "c:\\chrome_custom_data";
        StartWebBrowser(URL, ID, SelectBrowser.BROWSER_NAME_CHROME, "30", "true", quote(SelectBrowser.KEY_CHROME_USER_DATA_DIR), datapool);
        

     2. Start Chrome with the custom data pool "c:\chrome_custom_data" and Default user

        1
        2
        3
        

        String datapool = "c:\\chrome_custom_data";
        String user = "Default";
        StartWebBrowser(URL, ID, SelectBrowser.BROWSER_NAME_CHROME, "30", "true", quote(SelectBrowser.KEY_CHROME_USER_DATA_DIR), datapool, quote(SelectBrowser.KEY_CHROME_PROFILE_DIR), user);
        

     3. Start Chrome with the custom data pool "c:\chrome_custom_data" and the second user "Profile 1".

        1
        2
        3
        

        String datapool = "c:\\chrome_custom_data";
        String user = "Profile 1";
        StartWebBrowser(URL, ID, SelectBrowser.BROWSER_NAME_CHROME, "30", "true", quote(SelectBrowser.KEY_CHROME_USER_DATA_DIR), datapool, quote(SelectBrowser.KEY_CHROME_PROFILE_DIR), user);
        

Using preferences

1. Start Firefox

   • Prepare the json data file
     1. Create a new json data file, for example c:\Pref.json.dat
     2. Write the preferences into this json file, for example,

        {
            #The line begins with # is considered as comment
            #The preference is given as key:value, there are 3 kinds of value: string, boolean and integer.
            #The string value is quoted with double-quote, while boolean and integer are not quoted.
            "intl.accept_languages":"zh-cn",
            "accessibility.accesskeycausesactivation":false,
            "browser.download.folderList":2
        }
        

   • Examples:
     
     1. Start Firefox with the custom preferences data file "c:\Pref.json.dat"

        1
        2
        

        String preferenceDataFile = "c:\\Pref.json.dat";
        StartWebBrowser(URL, ID, SelectBrowser.BROWSER_NAME_FIREFOX, "30", "true", SelectBrowser.KEY_FIREFOX_PROFILE_PREFERENCE, preferenceDataFile);
        

2. Start Chrome

   Chrome's json data file is a little different from Firefox's. There are 2 kinds of settings: command line options and chrome preferences.
   The command line options will be defined normally as key : value pair in the json file, while chrome preferences will be defined as value of key "seplus.chrome.preference.json.key".
   • Prepare the json data file
     1. Create a new json data file, for example c:\Pref.json.dat
     2. Write the preferences and/or command-line-options into this json file, for example,

        {
            #The line begins with # is considered as comment
            #Define command-line-options as key:value
            "lang":"en",
            #If the command-line-options doesn't need a value, then provide an empty value as key:""
            "start-maximized":"",
            #"disable-smooth-scrolling":"",
        
            #Define preferences as value of key "seplus.chrome.preference.json.key"
            "seplus.chrome.preference.json.key":
            {
                #The preferences are given as key:value
                "intl.accept_languages" :"zh-CN-pseudo",
                "intl.charset_default"  :"utf-8"
            }
        }
        

   • Examples:
     
     1. Start Chrome with the custom preferences data file "c:\Pref.json.dat"

        1
        2
        

        String preferenceDataFile = "c:\\Pref.json.dat";
        StartWebBrowser(URL, ID, SelectBrowser.BROWSER_NAME_CHROME, "30", "true", quote(SelectBrowser.KEY_CHROME_PREFERENCE), preferenceDataFile);
        

Important References

SeleniumPlus Class JavaDoc
Selenium WebDriver API

SAFS Keywords Reference
SAFS Homepage on SourceForge
SAFS Test Design Guidelines
SAFS Image-Based Testing

"Update" expects that "SeleniumPlus" has already successfully installed, so the system environment %SELENUM_PLUS% has been defined correctly.
Update SelenumPlus jars and SeleniumPlus eclipse plugin to the latest level. During the update, %SELENUM_PLUS%/update_bak and %SELENIUM_PLUS%/eclipse/plugins/update_bak are created so user can revert the changes back.
There are 3 ways:

• Update From SeleniumPlus IDE
• Update by script
• Manual SeleniumPlus update steps

Update From SeleniumPlus IDE

Before update, make sure correct Selenium+ preference are enable.
1. From the Eclipse main menu.
2. Select Windows->Preferences.
3. Expand Selenium+ preference and click on Update Site.
4. Make sure desired update types are enabled or disabled.
   For example: if user want both Library Updates and the PlugIn Update then enable both check boxes.
   
5. Adjust the timeout value(s) if your network (or the internet) seem to be slow.

For Update SeleniumPlus, following are the steps.

1. From the Eclipse main menu.
2. Select Selenium+->Update->Update SeleniumPlus.
3. A window will popup, click Proceed with Download.
4. Click on Procced with Update.
5. When Update finish, Jars will be updated into build path.
6. Close the Update Complete window.

Update by script

This script should be in folder %SELENIUM_PLUS%\extra or %SAFSDIR%\extra.

1. If it exists and is latest
   The script usage is updateRuntime.bat [ALL|SE|SAFS], with parameter "SE" it updates SeleniumPlus, with "SAFS" it updates SAFS, with "ALL" it updates both "SeleniumPlus" and "SAFS".
   So call updateRuntime.bat SE to update SeleniumPlus.
   
2. If it exists but is not latest
   No parameter is needed, call updateRuntime.bat directly to get latest version of SeleniumPlus.
3. If it does not exist
   Please get its sourcecode manually. The latest script should be dated 11/30/2016.
   Then call updateRuntime.bat SE.

In the script, we are using the internal update resource which is faster. If you prefer using external update resource, then comment "internal resource" and un-comment "external resource".

    REM External update resource
    REM SET SE_LIB_UPDATE=https://github.com/SAFSDEV/UpdateSite/releases/download/seleniumplus/SEPLUS.LIB.UPDATE.ZIP
    REM SET SE_PLUGIN_UPDATE=https://github.com/SAFSDEV/UpdateSite/releases/download/seleniumplus/SEPLUS.PLUGIN.UPDATE.ZIP
    REM SET SAFS_LIB_UPDATE=https://github.com/SAFSDEV/UpdateSite/releases/download/safs/SAFS.LIB.UPDATE.ZIP

    REM Internal update resource
    SET SE_LIB_UPDATE=http://safsbuild:81/jenkins/job/SeleniumPlus/ws/updatesite/lib/latest/SEPLUS.LIB.UPDATE.ZIP
    SET SE_PLUGIN_UPDATE=http://safsbuild:81/jenkins/job/SeleniumPlus/ws/updatesite/plugin/latest/SEPLUS.PLUGIN.UPDATE.ZIP
    SET SAFS_LIB_UPDATE=http://safsbuild:81/jenkins/job/SAFS/ws/updatesite/lib/latest/SAFS.LIB.UPDATE.ZIP
    

If automated update fails then use manual steps to update SeleniumPlus environment.

Manual SeleniumPlus update steps

SeleniumPlus library update:

1. Shutdown Selenium+->RemoteServer->Stop and close Eclipse IDE.
2. Go to SeleniumPlusUpdates website.
3. Click on LibraryUpdates/latest and download SEPLUS.LIB.UPDATE.ZIP.
4. Extract the SELPLUS.LIB.UPDATE.ZIP and copy dir/files to the c:\seleniumplus\lib dir.
5. Example: copy extra/* to c:\seleniumplus\extra\ and lib/* to c:\seleniumplus\lib\. (Note: Please back-up dir/files before update).
6. Click Selenium+->Update->Refresh Build Path.

SeleniumPlus eclipse plugin update:

1. Shutdown Selenium+->RemoteServer->Stop and close Eclipse IDE.
2. Go to SeleniumPlusUpdates website.
3. Click on PlugInUpdates/latest and download SEPLUS.LIB.UPDATE.ZIP.
4. Extract the SELPLUS.LIB.UPDATE.ZIP and copy Seleniumplus.xxxx.jar to the c:\SeleniumPlus\eclipse\plugins\ dir.
5. Example: copy extra/* to c:\seleniumplus\extra\ and lib/* to c:\seleniumplus\lib\. (Note: Please back-up dir/files before update).
6. Click Selenium+->Update->Refresh Build Path.

Project's Assets

Enable SAFS

SeleniumPlus is packaged and delivered for a small-footprint, fast execution environment when compared to a full SAFS install.  It has been optimized to provide targetted test automation support for HTML applications using Selenium WebDriver.  The traditional capability to interface to other test automation tools capable of testing other technologies is intentionally removed from the SeleniumPlus install.

However, individual SeleniumPlus Projects can be configured to take advantage of SAFS and other testing tools if a full SAFS installation exists on the runtime machine.  For example, if you have a hybrid application that needs both HTML *and* Flex support then you might wish to enable SAFS within the project used to test that application.

So how do you enable this coolness?

• SAFS must be properly installed and configured on the machine.

• The SeleniumPlus Project Build Path must be modified:
  1. REMOVE: Library reference for JSTAFEmbedded.jar
  2. ADD: Library reference for JSTAF.jar
     ( Typically found at C:\STAF\bin\JSTAF.JAR, or wherever STAF was installed. )

• The SeleniumPlus Project TEST.INI must be modified as shown below.
  You must add the [<section>] and/or Item if it does not already exist, or overwrite the existing item if it does already exist.
  1. The NOSTAF option must be set to FALSE:
     [STAF]
     NOSTAF=FALSE

  2. The DriverRoot must be changed to use SAFS:
     [SAFS_DRIVER]
     DriverRoot="%SAFSDIR%"

     Note how the setting uses the SAFSDIR Environment variable that MUST exist at runtime.

Your test execution won't look any different, and you should get the exact same results.
By reviewing the running processes in Task Manager you would find 2 additional processes at runtime:

• java -- with a command-line "STAFJVM1" housing SAFS services:
  SAFSLOGS
  SAFSMAPS
  SAFSVARS
  

• STAFProc -- The inter-process communication layer to those services.

Other tools, scripting languages, Command(CMD) prompts, and COM-enabled applications or languages can now:

• Log to the same test log (SAFSLOGS) and any Debug Log at runtime.
• Monitor the Application Map (AppMap) data at runtime using SAFSMAPS.
• Monitor and modify the SAFS/SeleniumPlus Variables at runtime using SAFSVARS.
• Pause/Step/Resume/Stop the running test using SAFSVARS.
• Add automation support beyond Selenium WebDriver HTML support.
  (Example: Native windows, Java, Flex or hybrid HTML/Flex apps.)

Adding another SAFS Engine into the mix:

With SAFS enabled, you can now add automation support provided by other SAFS engines like:

• IBM Rational Functional Tester: Java, .NET, WPF, Native Win, and some HTML support.
• SmartBear TestComplete: Flex, .NET, WPF, Native Win, and some HTML support.

At this time, the most recommended alternative SAFS Engine would be the SmartBear TestComplete engine.  It has received the most development support in recent years along with the SAFS/Selenium Engine.

In order to use an alternative SAFS Engine, the underlying tool--like SmartBear's TestComplete--must be properly installed on the runtime system.  Consult the SAFS Install/Release Notes for information concerning configuring the particular tool for SAFS integration.

Then, we simply enable the use of the engine in the TEST.INI configuration file. The SAFS/SeleniumPlus execution runtime will automatically handle the launching and shutdown of the tool during testing.

Below is an example of enabling the SmartBear TestComplete engine in the Project's TEST.INI configuration file:

• Specify which engine(s) you want to enable:
  [SAFS_ENGINES]
  First=org.safs.tools.engines.SAFSTC

• Specify the specific engine's configuration information:
  [SAFS_TC]
  AUTOLAUNCH=TRUE
  HOOK="%SAFSDIR%\TCAFS\TCAFS.vbs"
  ConvertSAFSInputKeysSyntax=TRUE
  ConvertSAFSItemPathSyntax=TRUE
  

And that's it.  The next time a test is run the newly configured Engine will be part of the available toolset.  If the tool launches any startup window or Monitor of its own you will likely see it during the course of test execution.

Note that different tools will likely require different component recognition string syntax in the App Map. So, for example, an HTML XPATH recognition string that works for Selenium WebDriver will not work for SmartBear TestComplete.  You will need to consult the information available for the chosen Engine to know how to acquire and specify App Map entries for that specific Engine.

Remote Servers

About Selenium Server (standalone or hub+nodes)

1. standalone-server: the test actions will actually happen in the browser opened on the standalone-server.
2. grid-server: there is one hub connecting to multiple nodes, and the test actions will actually happen in the browser opened on nodes.

Why we need test runs remotely

• Testing browsers running on a Mac.
• Testing browsers running on Linux.
• Testing browsers running on iOS or Android devices.
• Testing different browser versions hosted on different machines.

Prerequisites:

1. Get SeleniumPlus stuff ready on every machine

• All SeleniumPlus\libs assets (JARs and ZIPs, etc.) must be copied and available on the remote machine.
• All Selenium Server OS-specific assets like specific browsers and browser drivers must be available on the remote machine.
• The Selenium Server should be launched.
  

2. Install and configure STAF (Optional step, but recommended)

1. Firstly, download STAF and install it on every machine (testing machine, server machine etc.)
2. Then, Modify the STAF config file on server machine (standalone or hub+nodes) to let them trust your testing machine.
   For example, we have a testing machine named "testing.machine", remote server named "remote.server", and STAF has been installed on both machine at C:\STAF;
   We need to modify the STAF config file C:\STAF\bin\STAF.cfg of machine "remote.server" by add a line "trust machine testing.machine level 5"
   

3. Configuration of Selenium Server

Here are the critical settings in a test.ini:

# Settings for a remote Selenium Server
# SELENIUMHOST and SELENIUMPORT are used to connect Selenium Server (standalone or hub)
SELENIUMHOST=remote.server.name
SELENIUMPORT=4444 (setting not required if default)
# SELENIUMNODE defines the selenium nodes to run.
# If SELENIUMNODE is given, SELENIUMHOST will start as a selenium hub; otherwise as a stand-alone server.
SELENIUMNODE=node1:port:config1;node2:port:config2

# Selenium standalone server should run on local machine at default port 4444
# [SAFS_SELENIUM]
# If nothing is specified.

# Selenium standalone server should run on local machine at port 6666
[SAFS_SELENIUM]
SeleniumPort=6666

# Selenium standalone server should run on machine D99999.yourCompany.com at port 4444
# test actions will actually happen in the browser opened on machine D99999.yourCompany.com
[SAFS_SELENIUM]
SeleniumHost=D99999.yourCompany.com
SeleniumPort=4444

# Selenium hub should run on machine selenium.hub.machine at port 5555
# Selenium node should run on machine node.yourCompany.com at port 6666 and connecting to hub server
# test actions will actually happen in the browser opened on machine node.yourCompany.com
[SAFS_SELENIUM]
SeleniumHost=selenium.hub.machine
SeleniumPort=5555
SELENIUMNODE=node.yourCompany.com:6666

# Selenium hub should run on local machine at port 5555
# Selenium node should run on machine node.yourCompany.com at port 6666 and connecting to hub server
# test actions will actually happen in the browser opened on machine node.yourCompany.com
[SAFS_SELENIUM]
SeleniumPort=5555
SELENIUMNODE=node.yourCompany.com:6666

4. Configuration of browser drivers

• Configure in .ini file:

  [SAFS_SELENIUM]
  # WEB_DRIVERS is used to set the specific browser
  # drivers (separated by colon :) to start with selenium server.
  # The following setting means 3 drivers, IE, chrome and edge will
  # start with the selenium server.
  WEB_DRIVERS=explorer:chrome:MicrosoftEdge
  

• Configured by VM parameter:

  VM parameter 'safs.selenium.web.drivers' is used to
  set the specific browser drivers (separated by colon :) to start with selenium server.
  The following setting means 2 drivers, IE and edge will start with the selenium server,
  and in the class SampleTest, the user can test with the chrome or edge browser.
  java -Dsafs.selenium.web.drivers=chrome:MicrosoftEdge SampleTest
  

5. Launch Selenium Server

• Launch automatically by SE+. If we install and configure STAF, SE+ CAN start automatically servers remotely.
• Launch manually.

Start SeleniumPlus Test

Reference

Launch Selenium Server manually

1. The simplest way is to use RemoteDriverLauncher. Examples are listed below:
   • Start a selenium standalone server (with SeleniumPlus-RMI-Server).
     We could run the following command: start a standalone server with RMI on port 4567 with minimum memory 512M and maximum memory 4g.
     "%SELENIUM_PLUS%\Java64\jre\bin\java.exe" org.safs.selenium.webdriver.lib.RemoteDriverLauncher -safs.rmi.server "-port 4567" "SELENIUMSERVER_JVM_OPTIONS=-Xms512m -Xmx4g"
   • Start a selenium grid.
     1. Start a selenium hub
        Suppose the hub machine's name is selenium.hub.machine, on which we run the following command: start a hub server on default port 4444 with minimum memory 512M and maximum memory 2g.
        "%SELENIUM_PLUS%\Java64\jre\bin\java.exe" org.safs.selenium.webdriver.lib.RemoteDriverLauncher "-role hub" "SELENIUMSERVER_JVM_OPTIONS=-Xms512m -Xmx2g"
     2. Start a selenium node (with SeleniumPlus-RMI-Server) connecting the hub (the same way, we can launch multiple nodes on different machine)
        On node machine, we could run the following command: start a node server with RMI on port 5678 with minimum memory 256M and maximum memory 4g, and this node will register on hub running on port 4444 at machine selenium.hub.machine
        "%SELENIUM_PLUS%\Java64\jre\bin\java.exe" org.safs.selenium.webdriver.lib.RemoteDriverLauncher -safs.rmi.server "-role node -hub http://selenium.hub.machine:4444/grid/register" "-port 5678" "SELENIUMSERVER_JVM_OPTIONS=-Xms256m -Xmx4g"

2. SeleniumPlus provides a Windows BATCH file for launching just such a remote Selenium Server on Windows.
   The batch file named "RemoteServerWithRMI.bat" should be in the %SELENIUM_PLUS%\extra directory. It can serve as an example of the command-line syntax needed to launch a SeleniumPlus compatible remote Selenium Server. The comments in that batch file should tell us how to launch different servers (standalone, hub, node).

3. The most powerful and complicated way is to call Selenium-Server-Runner.
   In fact the first 2 ways, they both finally call Selenium-Server-Runner. Whether launched on a command-line, or preparing an OS-specific batch file or script, a Windows sample command-line invocation of the augmented Selenium Server is shown below: This command-line will launch the Selenium Server Runner (standalone) which will inject an RMI Server into the running JVM. The Selenium Server Runner will also launch the Selenium Server found in the Selenium Server JAR file specified with the -jar command-line argument.

   SET CLASSPATH=
        <pathTo>\seleniumplus.jar;
        <pathTo>\JSTAFEmbedded.jar;
        <pathTo>\selenium-server-standalone-<version>.jar
   
   SET JAVA_EXE=<pathTo>\java.exe  (JRE Java 7 minimum)
   
   %JAVA_EXE%
        -Xms512m -Xmx1g
        -Djava.rmi.server.hostname=machine.intranet.com
        -Dwebdriver.chrome.driver=<pathTo>\chromedriver.exe
        -Dwebdriver.ie.driver=<pathTo>\IEDriverServer.exe
        -cp %CLASSPATH%
   
        org.safs.selenium.util.SeleniumServerRunner
   
        -jar <pathTo>\selenium-server-standalone-<version>.jar
        -timeout=20
        -browserTimeout=60
        -safs.rmi.server
   

   There are 2 special command-line parameters to enable the SeleniumPlus RMI Server:
   1. -Djava.rmi.server.hostname=<machine.intranet.com> or <123.456.789.10> ip address
   2. -safs.rmi.server

About SeleninumPlus-RMI-Server.

In order for a remote Selenium Server to provide equivalent augmented support provided by SeleniumPlus, the remote Selenium Server must be launched in a manner that allows us to inject that support into the remote Java JVM running the Selenium Server. Consult Using Selenium Server Runner to know how.

Snapshots about launched Selenium Servers.

Selenium hub Server.
The first line tells us that a selenium hub server is being started.

Selenium node Server with injected RMI server into the Selenium Server JVM.
The first 3 lines of the output tell us that RMI-server has been injected into the Selenium Server JVM;
while the 4th line tells us that a selenium node server is being started;
and the last 2th line tells us that the node has registered on hub server.

Browser Drivers

About Browser Drivers

• chromedriver.exe is needed to run test on Chrome;
• IEDriverServer.exe is needed for IE;
• MicrosoftWebDriver.exe is needed for Edge
• etc.

Currently supported browsers

• IE 11 or earlier
• Firefox 45.0 or earlier
• Chrome v55-57
• Edge 14.14393 or earlier

Update browser drivers

1. We can put it into the folder %SELENIUM_PLUS%/extra
2. User may also need to update the selenium-server-standalone-xxx.jar and put it to %SELENIUM_PLUS%/libs

Configure browser drivers

Calling Javascript

During the test, sometimes users need to manipulate the object within the browser directly, which can be achieved by Javascript. This section explains how to execute Javascript through SeleniumPlus.

• SE+ provides APIs
• Before calling Javascript
• Examples

SE+ provides APIs:

1. To execute a Javascript in the context of the currently selected frame or window:
   • SeleniumPlus.executeScript()
   • SeleniumPlus.executeAsyncScript()
2. To execute a Javascript on a certain Component (WebElement) in the context of the currently selected frame or window:
   • SeleniumPlus.ExecuteScript()

Before calling Javascript:

There are something we should understand. Such as the parameters of these APIs and how these Java-parameters are passed to Javascript as parameters, it is important! We don't need to understand all of them :) , the items below are listed by necessity priority:

1. "Javascript snippet": It is passed in as first parameter for executeScript() and executeAsyncScript(); While it is passed in as second parameter for ExecuteScript().
2. "Javascript parameters": They are defined by keyword arguments, so arguments[0], arguments[1] ... can be used in the Javascript snippet. They are passed in as second, third ... parameters of executeScript() and executeAsyncScript(); While for ExecuteScript(), the first parameter Component is arguments[0], and the third parameter is arguments[1], fourth parameter is arguments[2] etc.
3. "callback method": It is ONLY for asynchronous invocation executeAsyncScript(), this callback is always injected automatically as the last argument, so it is always arguments[arguments.length - 1]. The Javascript snippet must explicitly signal it is finished by invoking this callback. The first argument passed to the callback function will be used as the script's result. The conversion from Javascript object to Java object definition.
4. "script timeout": It is ONLY for asynchronous invocation executeAsyncScript(), the default timeout for a script to be executed is 0ms. In most cases one must set the script timeout beforehand to a value sufficiently large enough by calling setScriptTimeout(long,TimeUnit).
5. "debug() method": For synchronous invocation executeScript() and ExecuteScript(), user can call debug(debug-message) in the Javascript snippet to write debug message into SE+ debug log. By default, this functionality is off, user can turn it on by setting JavaScriptFunctions.jsDebugLogEnable=true. Normally the debug message will be written to a file, we can also send debug message to browser's console by setting JavaScriptFunctions.logToBrowserConsole=true.
6. "throw_error() method": For synchronous invocation executeScript() and ExecuteScript(), user can call throw_error(error-message) in the Javascript snippet so that a JSException will be thrown out in Java code. Below is how it is normally used in Javascript snippet.

    try{
      //do some javascript actions
    }catch(err){
      throw_error(err);
    }
   

7. "event listener": Here we are NOT talking about the "event listener" inside Javascript, BUT about the Java listener reacting to the Javascript event. We can call addJavaScriptEventListener(WebElement, eventName, listener)/ removeJavaScriptEventListener(WebElement, eventName, listenerID) to add/remove listener. Below is an example how to add a DefaultJSEventListener for "mousedown" event on a WebElement. This DefaultJSEventListener is not public class, it is a protected inner class inside SearchObject, click this link and search "DefaultJSEventListener" to get the source code, you can imitate it to write your own listener.

    WebElement webelement = null;//User must assign it with a valid value.
    String event = "mousedown";
    int timeout = 1000;//milliseconds
    DefaultJSEventListener listener = new DefaultJSEventListener(event);
    //add listener for event
    String listenerID = WDLibrary.addJavaScriptEventListener(webelement, event, listener);
    //do some mousedown related work, for example 'click'
    webelement.click();
    //wait for event happen
    if(listener.waitEventFired(timeout)){ //ok, event has been fired.}
    //remove the listener
    WDLibrary.removeJavaScriptEventListener(webelement, event, listenerID);
   

Examples:

There are something we should understand. Such as the parameters of these APIs and how these Java-parameters are passed to Javascript as parameters, it is important! We don't need to understand all of them :) , the items below are listed by necessity priority:

1. SeleniumPlus.executeScript()

    //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]));
   



2. SeleniumPlus.executeAsyncScript()

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

   
   

    //Example #2, call REST service to get a result.
    try{
     WDTimeOut.setScriptTimeout(1, TimeUnit.SECONDS);
     JavaScriptFunctions.DEBUG_OUTPUT_JAVASCRIPT_FUNCTIONS = true;
     JavaScriptFunctions.setJsDebugLogEnable(true);
   
     String script   = "try{ "
                 + "  var callback = arguments[arguments.length - 1];"
                 + "  debug('try to get registration service.');"
                 + "  var service = registry.getRegistrationService();"
                 + "  if(service==undefined){"
                 + "    debug('Failed to get service');"
                 + "  }else{"
                 + "    debug('we got registration service.'); "
                 + "  }"
                 + "  service.get({'user-id': 'administrator'}).done(callback).fail(callback);"
                 + "}catch(error){"
                 + "  debug('we met exception');"
                 + "  throw_error(error);"
                 + "}";
   
     Object results = SeleniumPlus.executeAsyncScript(script);
     System.out.println(results);
    }catch(Exception e){
     System.out.println(e.getMessage());
    }finally{
     WDTimeOut.resetScriptTimeout(0, TimeUnit.MILLISECONDS);
    }
   

   
   

    //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();";
    //Wait result for at the most 5 seconds
    WDTimeOut.setScriptTimeout(5, TimeUnit.SECONDS);
    Object result = SeleniumPlus.executeAsyncScript(script);
    JsonObject json = new JsonParser().parse((String) result);
   

   
   

    //Example #4: 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");
   



3. SeleniumPlus.ExecuteScript()

    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();
   

Using SeleniumScripts

There are some tools can record "selenium test" and store it into a file.
Selenium Builder will store it in JSON format.
Selenium IDE can store it in HTML format.
This kind of file contains the "selenium test" and we call these files as "Selenium Scripts".
This section explains how to execute "Selenium Scripts" through SeleniumPlus API CallScript.

• SeBuilder JSON script
• SelRunner HTML script

SeBuilder JSON script:

1. The script is stored in Sebuilder JSON file.
2. Run this JSON file by SeleniumPlus API CallScript

SelRunner HTML script:

The HTML script is stored as a Table.
the tag <tbody> means the begin of the test. the tag </tbody> means the end of the test.
the tag <tr> means the begin of one step. the tag </tr> means the end of one step.
each test step can contain multiple <td></td>, they are used to hole the comand and parameters.
Below is an example snippet, which is part of the real sebuild script in regression test.

  <tbody>
    <tr>
        <td>open</td>
        <td>${baseurl}</td>
        <td>${FormsBrowser}</td>
    </tr>
    <tr>
        <td>pause</td>
        <td>2000</td>
        <td> </td>
    </tr>
    <tr>
        <td>captureEntirePageScreenshot</td>
        <td>Actuals/FormsSRTest/formsSRTest-1.png</td>
        <td></td>
    </tr>
    <tr>
        <td>click</td>
        <td>${Map:FormsMain:CheckBox2}</td>
        <td></td>
    </tr>
    <tr>
        <td>close</td>
        <td>${FormsBrowser}</td>
        <td> </td>
    </tr>
  </tbody>

HTTP Proxy

In some testing environment, Internet access is not direct, but through a Proxy server. This section is talking about HTTP proxy settings in SeleniumPlus.
There are 2 ways:

• Global setting
• By API parameters

Global setting:

[SAFS_SELENIUM]
;define the HTTP PROXY host name to connect Internet
GATEWAYHOST=yourGateway.net
;define the HTTP PROXY port number to connect Internet
GATEWAYPORT=80
;define the HTTP PROXY "bypass address" when connecting INTRANET
PROXY_BYPASS_ADDRESS=localhost,127.0.0.1,host.not.thru.gateway

By API parameters:

The HTTP proxy can also be set by the optional parameters of StartWebBrowser API. The optional parameters are given as pair (key, value). The keys related to "HTTP proxy" are:

1. KEY_PROXY_SETTING: the key for proxy string; The value is colon separated string as "proxyserver:port"
2. KEY_PROXY_BYPASS_ADDRESS: the key for proxy bypass address string; The value is comma separated string as "localhost,tadsrv,rnd.yourCompany.com"

//Start the firefox web browser with proxy server as "proxy.server" and proxy server port as "8080"
StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_FIREFOX,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_PROXY_SETTING),
                                                        quote("proxy.server:8080")
                                                        });

//Start the firefox web browser with proxy server as "proxy.server" and proxy server port as "8080"
//local.site1, local.site2 will not be routed through "proxy.server"
StartWebBrowser("http://www.google.com", "GoogleMain", new String[]{
                                                        SelectBrowser.BROWSER_NAME_FIREFOX,
                                                        "10",
                                                        "true",
                                                        quote(SelectBrowser.KEY_PROXY_SETTING),
                                                        quote("proxy.server:8080"),
                                                        quote(SelectBrowser.KEY_PROXY_BYPASS_ADDRESS),
                                                        quote("local.site1, local.site2")
                                                        });