SAFS Selenium Quick Start
for Windows

Copyright (C) SAS Institute
General Public License: http://www.opensource.org/licenses/gpl-license.php

Be sure to check the latest Whats New In SAFS doc for the latest updates on SAFS and Selenium Support!

This tutorial intends to help you run SAFS tests with the SAFS Selenium WebDriver Engine.
(Use of the deprecated SAFS Engine for Selenium 1.x--before WebDriver--is highly discouraged.)

The SAFS Selenium WebDriver Engine is part of:

• GitHub SAFS Win Release,

This document supposes the installation directory:

• "C:\SAFS"

See the online version of this doc with images.

Prerequisites:

1. Installation:
   • SAFS for Windows
     Windows 7
     Chrome (chromedriver.exe)
     IE (IEDriverServer.exe and MicrosoftWebDriver.exe)
     FireFox 33 (minimum)
     (Firefox 43 and later not yet supported out-of-the-box due to SAFS issues with Selenium Server 2.48.x JAR dependencies)
     
     1. Latest SAFS Release for Windows

     2. Latest SAFS Update for Windows

2. Check Steps:

   Make sure you have the latest SAFS on your machine (see above).

   Next, verify that the following 3rd-party jars (among others) are in folder C:\SAFS\lib:

   • selenium-server-standalone-2.47.1.jar
   • SeInterpreter.jar
   • safsselenium.jar

   Finally, you could make sure that these jars are added to environment variable 'CLASSPATH':
   (Make sure any earlier versions of the selenium-server-standalone JAR(s) are removed from the CLASSPATH:)

   • %STAFDIR%\bin\JSTAF.jar
   • %SAFSDIR%\lib\safsselenium.jar
   • %SAFSDIR%\lib\selenium-server-standalone-2.47.1.jar

   However, note that most tests are launched from BAT files that will override any CLASSPATH environment variable setting.

Start from "SAFS Selenium sample"

The test script, "SAFS Selenium sample", intends to:
1. Open an IE/FireFox/Chrome browser to Google
2. Input some characters on a Google search window
3. Click the "Search" button to get the results
4. Close the browser and exit.

1.   The structure of "SAFS Selenium sample" project

Goto folder C:\SAFS\samples\Selenium2.0

This folder is the ProjectRoot defined in the section SAFS_PROJECT of configuration file. The folder will contain files/folders as below.

SafsDevTest.ini	--- Test configuration file
test.ini	--- Default configuration file
testSele.bat	--- Batch to Run test script
runSE2ProcessContainer.bat	--- Batch to Run the WebDriver Processor Container
Datapool\google.map	--- Application map file
Datapool\SafsDevTest.CDD	--- Test Cycle file
Datapool\KeywordHtmlTest.STD	--- Test Suite file
Datapool\SeleniumEditBoxTest.SDD	--- Test Step file
Datapool\Bench	--- Folder containing bench files
Datapool\Dif	--- Folder containing diff files
Datapool\Logs	--- Folder containing SAFS logs
Datapool\Runtime	--- Folder
Datapool\Test	--- Folder containing files generated during test.
doc\	--- Folder of documentation
extra\	--- Folder of dependencies

• SafsDevTest.ini and the default test.ini:

  These are configuration files that contain information which tells SAFS where and how to load user's test scripts, what engine to use, and the configuration about the engine etc..

  test.ini is the default that will be sought if no INI file is specified in command-line parameters.

  Normally, only advanced users would ever go in and change any of these settings.

  However, settings flagged as CRITICAL will likely have to changed for your environment.
  Note that '#' or ';' can be used to make a line an ignored COMMENT.

  ------------------------------------------------------------------

  [SAFS_DRIVER]
  DriverRoot="C:\SAFS"
  
  [SAFS_PROJECT]
  ProjectRoot="C:\safs\samples\Selenium2.0"
  
  [SAFS_TEST]
  TestName="SafsDevTest"
  TestLevel="Cycle"
  CycleSeparator=","
  CycleLogName="SafsDevTest.cycle"
  CycleLogMode="TEXTLOG|XMLLOG|CONSOLELOG"
  
  [SAFS_SELENIUM]
  AUTOLAUNCH=TRUE
  GATEWAYHOST=your.gateway.com
  GATEWAYPORT=80
  HOOK=org.safs.selenium.webdriver.SeleniumHook
  BROWSER="firefox"
  
  # SETUP to connect to Optional Remote Selenium Standalone Server
  # SELENIUMHOST=host.domain.com
  # SELENIUMPORT=4444
  
  [SAFS_ENGINES]
  First=org.safs.tools.engines.SAFSSELENIUM
  

  ------------------------------------------------------------------
  Note:
  • About GATEWAY

    If you need a Gateway to Access the Internet, please modify the folloing 2 settings:

    • GATEWAYHOST=your.gateway
    • GATEWAYPORT=80

    If you do not use a gateway, please add semi-colon '#' before these 2 settings to make them comments.

    • # GATEWAYHOST=no.gateway
    • # GATEWAYPORT=80

  • About SELENIUMHOST

    If you intend to connect to a Remote Standalone Selenium Server:

    • SELENIUMHOST=remotehost.domain.com
    • SELENIUMPORT=80

    If you do not use this, please add semi-colon '#' before these 2 settings to make them comments.

    • # SELENIUMHOST=no.remotehost
    • # SELENIUMPORT=80

• testSele.bat

  After setting the %CLASSPATH%, there is only one command line as shown below. SAFSDRIVER Command Line takes SafsDevTest.ini as its project configuration file, launches the Selenium Engine and runs each step defined .CDD, .STD, .SDD files.

  %SAFSDIR%\jre\bin\java -Dsafs.project.config=SafsDevTest.ini org.safs.tools.drivers.SAFSDRIVER

• runSE2ProcessContainer.bat

  After setting the %CLASSPATH%, there is only one command line as shown below. It takes (initially missing) se2processcontainer.ini as its project configuration file and launches the WebDriver Process Container:

  "%EXECUTE%" -Dsafs.project.config="se2processcontainer.ini" -cp "%CLASSPATH%" org.safs.selenium.spc.WDSPC

  Because the se2processcontainer.ini is initially missing, the Process Container should resort to the test.ini file for initial configuration.

• SafsDevTest.CDD, KeywordHtmlTest.STD, SeleniumEditBoxTest.SDD

  They are test tables containing test records, refer to Automation Workflow for details.

• google.map

  This is an application map file.  It contains the Recognition Strings of the GUI components of Google Search page.

  How do I get/specify the Recognition Strings for Selenium WebDriver?

  Refer to:
  • SAFS Selenium Recognition Strings
  • Selenium's XPATH CSS Locators Table
  1. How to specify Recognition String?

     If equal sign (=) exists in the id, name, XPATH, CSS etc. expression, you need to escape it by backslash (\)
     

     1. Use component's attributes to create RS, such as id, name, class etc.
        • Unique attribute: If you use id or name, as they are unqiue for an element on a page, you can simply specify RS as "id=xxx", "name=xxx".
        • Non-unique attribute: If you use other attributes, to locate an element you may need more than 1 attribute to specify RS, such as "attr1=xxx;attr2=xxx;attr3=xxx", attributes are separated by semi-comma(;)

     2. Use XPATH or CSS to specify RS as "xpath=xxx" or "css=xxx".

        Take the Google page as example:
        

        • To specify the "Body" element
          • By XPATH: "xpath=/html/body"
          • By CSS: "css=body"

        • To specify the "Search Button" element
          • By XPATH: "xpath=//input[contains(@jsaction,'sf.c')]", or "xpath=//input[@jsaction\='sf.chk')]"
          • By CSS: "css=input[jsaction*='sf.c']" or "css=input[jsaction\='sf.chk']"
     
     
  2. How to get the element's attributes?
     You can use browser to get them. Here, FireFox will be used to illustrate, it is quite similliar for IE.
     • Open the FireBug by clicking menu "Tools->Web Developper->Firebug->Open Firebug", or simply press "F12"

     • Switch to 'HTML' View by clicking the 'HTML' tab in the left side of Firebug.

     • Search a component. In the right side of Firebug, there is an editbox where a string can be filled to find a compoent. For example, we try to find the Google's Input search box, as we know its tag name is 'input', we write 'input' in the editbox, a popup menu will be shown, we can click the 'Next' button to locate the html component with tagname as 'input' in the 'HTML' view of Firebug.

     • Highlight a component. In the 'HTML' view of Firebug, if the mouse hovers on a component, that component will be highlighted on the page so that you will know if this is what you want or not.

     • Look at the componet in the 'HTML' view, we can see all attributes.

  3. Store the Recognition String into map file.
     If you specify "id=lst-ib" for the search input box of Google page, you can name it as EditBox and store EditBox="id=lst-ib" in the map file so that 'EditBox' can represent the Google's Input search box in the future test.

  4. The quickest way to get the Recognition String.
     If you have the Selenium IDE installed use it to record a script, then in the IDE, the recorded steps will be shown under the tab "Table"; In the column "Target" the "Recognition String" will be listed there. Normally it can be used by SeleniumPlus directly, But if the string is XPATH, you need to add prefix "XPATH="; If equal sign (=) exists in the id, name, XPATH, CSS etc. expression, you need to escape it by backslash (\)
     IDE recorded table, refer to picture

2.   Use Process Container

The Selenium Process Container is a SAFS test tool used to investigate application components and properties and help build the application Map. It can drill down a chosen web page and generate the Recognition Strings for each GUI component on the page.

3.   Run SAFS Test with Selenium

Double-click testSele.bat to run the SAFS Test..

When running testSele.bat:

1. the console below should appear
2. SAFS Selenium will open a browser containing the Google home page
3. input some characters, and press the Enter key automatically.

The log file SafsDevTest.cycle.txt should be output into the C:\SAFS\samples\Selenium2.0\Datapool\Logs directory.

Carl Nagle, SAS
Project Lead, SAFSDEV
Subscribe to appropriate Support Forums to review support archives and ask questons.