Setup SmartBear TestComplete
for SAFS on Windows

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

The TestComplete Project (installed at C:\SAFS\TCAFS) has been "upgraded" to TestComplete V10.

If you are running an earlier version of TestComplete you will need to:

• Upgrade to TestComplete 10, OR
• Transfer TCAFS Script and UserForms to your pre-V10 TestComplete Project repository, OR
• You *might* be able to Overwrite this V10 TCAFS repository with an earlier version you already have.

After the SAFS install, if you install a version of TestComplete that is newer than V10, you will need to manually open and convert the existing TCAFS project at C:\SAFS\TCAFS\TCAFS.PJS for your newer version of TestComplete.  Open the TCAFS project and TestComplete will prompt for your approval to convert the project for you.

Script Updates and Overlays:

Released updates to SAFS and TCAFS can be found at:

• The GitHub SAFS Updates Downloads website.
• The SourceForge SAFS Updates Downloads website.

  Users should always check for and install any updates that might be available after the installed release.

If there are no updates to be installed, proceed to Verify Install.

TCAFS updates usually require you to add or replace scripts in your TCAFS project directories.  If you add or replace any script files to the TCAFS project space you will need to verify your project has these scripts properly imported.   To do this:

1. Open the TCAFS project in Test Complete.

2. Expand the Project Explorer TCAFS project tree to show and select the TCAFS "Script" item:
     

3. With "Script" selected, select the main menu item "Test->Check Syntax":

4. If there are "No Syntax Errors" then the project should be ready.

5. Resolve reports of missing files thru the "Add->Existing Item" menuitem when right-clicking the "Script" node:
   

   The new scripts are found in the \SAFS\TCAFS\TCAFS\Script directory.

6. Repeat Steps 3-5 until all the missing file errors have been resolved.

Verify the SAFS/TCAFS Install:

SmartBear TestComplete 9.0 or higher must be installed and connecting properly to any local or remote License Server.  You should also review and heed the TestComplete setup information that follows before attempting to verify the SAFS/TCAFS Engine.

1. If not done as part of the original SAFS install, or if TestComplete has been installed or upgraded AFTER the SAFS install:
   Execute: %SAFSDIR%\jre\bin\java org.safs.install.TCAFSInstaller, OR

   Execute: %SELENIUM_PLUS%\Java\bin\java org.safs.install.TCAFSInstaller,

   which will:

   Set the %TESTCOMPLETE_HOME% System Evironment variable to the correct TestComplete install directory.

2. Open/Connect TestComplete to the project at C:\SAFS\TCAFS\TCAFS.PJS
   Allow TestComplete to convert the project repository if you are prompted to do so.
   Shutdown TestComplete once the conversion, if any, is completed.

3. Verify SAFS/TCAFS runtime integration:

   • Execute C:\SAFS\Project\runTCAFSTest.bat

     SAFS, SmartBear TestComplete, and a sample test should be seen.

   • View the SAFS log output at:

     C:\SAFS\Project\Datapool\Logs\TCAFSTest.txt

   • SAFS and TestComplete should shutdown upon test completion.

4. Problem launching SmartBear TestComplete?
   Verify\Edit the contents of C:\SAFS\TCAFS\TCAFS.vbs:
   • 'projectname' and 'suitename' point to existing SAFS assets.

   • 'command' points to correct and existing executable:
     ...\bin\TestComplete.exe, OR
     ...\bin\TestExecute.exe

   • Try to execute the test again after all edits are complete.

Using TestExecute on older SAFS Installs

1. THIS STEP is only applicable if you installed TestExecute AND your C:\SAFS\TCAFS\TCAFS.vbs file is dated BEFORE 4/13/2011.

   SKIP this step if you installed TestComplete.
   SKIP this step if your TCAFS.vbs file is dated 4/13/2011 or LATER.

   Prior to the 4/13/2011 file, the SetupTCAFS.wsf file did not run properly if TestExecute was installed on the machine instead of TestComplete. Either put a copy of the newer TCAFS.vbs on your machine and run the SetupTCAFS.wsf file, or do the following instead of running the SetupTCAFS.wsf file:

   • Manually set the following System Variable in System Properties > Environment Variables:

     Example path to AQA Install Directory:
     TESTCOMPLETE_HOME C:\Program Files\Automated QA\TestExecute 8
     (Or ...\Program Files (x86)\... if the test machine is 64 bit)

   • In the C:\safs\TCAFS\TCAFS.vbs file:

     change

     %TESTCOMPLETE_HOME%\bin\TestComplete.exe
     to
     %TESTCOMPLETE_HOME%\bin\TestExecute.exe

2. Before running the C:\SAFS\Project\runTCAFSTest.bat file:
   • Make appropriate edits to the C:\SAFS\Project\tcafs.ini file.

   • Manually open TestComplete or TestExecute and set the log option so the log does not open automatically after a test run and interfere with automated tests.
     • In TestComplete, select the TCAFS project. Then, select Tools > Options > Engines > Log

       make sure the ‘Activate after test run’ option is not checked.

     • In TestExecute--from the TaskBar--select Options > Engines > Log

       make sure the ‘Activate after test run’ option is not checked.

   • If you plan to run the runTCAFSTest.bat file on a 64-bit machine, you do not need to follow the instructions in this file to point your tests to the 32-bit JVM.
     It is better to update the PATH env to the 32-bit JRE path.

3. The 1st time you run the runTCAFSTest.bat file, it may take a little time for TestComplete (or TestExecute) to become visible. Also, at the end of the test, it may take some time for TestComplete (TestExecute) to shut down. Please be patient.

TestComplete / TestExecute: Configuration and Usage Tips

1. Minimize TestComplete during playback:
   (Unfortunately, I think this has to be set for each of your TestComplete projects.)
   • For TestComplete:
     • Open TestComplete
     • Open your project (for our purposes, this is the TCAFS project)
     • Open the properties dialog for your project
       · In the Project Explorer on the left of the IDE, select your project (for example, TCAFS)
       · RMB (right-mouse-button) > Edit > Properties
     • On the right side of the IDE, select Playback
     • Under the Runtime category, check the box for Minimize TestComplete
       · For additional runtime options it is recommended you see Items 2 and 3 below.
       Save the project
       · In the Project Explorer on the left of the IDE, select your project (for example, TCAFS) · RMB (right-mouse-button) > Save
     • Exit TestComplete
     • Next time you run the test (in this case the sample test at C:\SAFS\Project\runTCAFSTest.bat), TestComplete will run minimized.

   • For TestExecute
     • Open TestExecute. (Double-click the desktop icon)
     • When TestExecute is opened there is no GUI displayed. An icon is placed onto the right-hand side of the desktop task bar.
     • Hover over the TestExecute icon, click the RMB (right-mouse button), and select Options.
     • In the Options dialog, select Engines.
     • In the expanded Engines list, select Log
     • On the right panel, uncheck "Activate after test run" and click the OK button.
     • Exit TestExecute. (RMB the TestExecute icon on the right-hand side of the desktop task bar and select Exit.)

2. Options to ensure quick playback:
   • For TestComplete:

   • Open TestComplete
   • Open your project (for our purposes, this is the TCAFS project)
   • From the main menu, select Tools > Current Project Properties
   • On the right side of the IDE, select Playback.
   • Under the Runtime category, set the following options, as desired:
     · Auto-wait timeout, ms: 1000
     · Delay between events, ms: 0
     · Key pressing delay, ms: 0
     · Dragging delay, ms: 5
     · Mouse movement delay, ms: 0
     · Stop on Error: Uncheck this property
     · Minimize TestComplete Check this property
     · Leave all other settings at the default settings.
   • Save the project
     · In the Project Explorer on the left of the IDE, select your project (for example, TCAFS)
     · RMB (right-mouse-button) > Save
   • Exit TestComplete

   • For TestExecute:
     • As far as I can tell, there is no way from within TestExecute to set any of the playback properties other than ensuring the log is not displayed after a test run.

       If TestExecute is running on a machine with TestComplete installed then the following steps should not be necessary.

     • To ensure TestExecute honors the TCAFS project properties:
       · Go to a machine where you have TestComplete installed.
       · Modify and save your TCAFS project properties per steps above.
       · Copy the project file from the TestComplete machine to the TestExecute machine.
       (When the TCAFS project tests are run using TestExecute they should run using the desired properties.)
       - The project file to copy is found at C:\SAFS\TCAFS\TCAFS\TCAFS.MDS

3. Other Options
   • Purge old logs:
     Sometimes, the TestComplete default log collection can slow down your system over time. The user can purge unnecessary old logs by changing the:

     Tools > Options > Engines > Log

     setting for the "Number of recent logs to keep". If you set this value to 2, TestComplete will only keep the 2 most recent test run logs. Note that this setting can be set on machines with TestExecute as well.

   • When testing .NET application (Outlook, etc.), you can enable the MSAA ‘*’ option: If you need TestComplete to see objects inside menus and trees of .NET applications, you may need to turn on the ‘*’ choice under the list of MSAA accepted windows. This is done as follows:
     • In TestComplete, with your project open, select:

       Tools > Default Project Properties > Project > Open Applications > MSAA

     • Make sure the ‘*’ item is checked.
     • Click OK.
     • Exit TestComplete and, if prompted to save changes, accept the changes.

     • You may also need to make the change on your project options if you have an already established project. This is done in a similar manner as follows:
       • In TestComplete, with your project open, select:

         Tools > Current Project Properties > Open Applications > MSAA

       • Make sure the ‘*’ item is checked.
       • RMB on your project name and select Save.

     NOTE: Although turning on MSAA seems to work for some testers doing certain .NET, WPF, or Outlook automation, it is not always working well for others doing Excel, Word, and PowerPoint automation. Here are some observations so far:

     The recognition strings are different for many windows.
     In the Tools > Current Project Properties > Open Applications, if NativeClrObject precedes NativeMSAA in the ‘Priority of objects’ list, then a lot of the recognition strings remain unchanged.

     However, there are still some Microsoft Message dialogs that do have different strings and there may be other windows with different strings as well.

     Performance is greatly reduced.
     When we run certain tests with MSAA turned on it runs much slower than when MSAA is turned off.

4. TCAFS Timeout so TestComplete has time to open during SAFS test:
   Like the tcafs.ini file in C:\SAFS\Projects, your tests must also have a test configuration file. In your INI file, in the [SAFS_TC] section, you can set a Timeout value.   Something like: ‘Timeout=120’.  This example gives TestComplete 120 seconds to open before SAFS begins to process test commands.

   An example mytest.ini file:

   [SAFS_DRIVER]
   DriverRoot="C:\SAFS"
   
   [SAFS_PROJECT]
   ProjectRoot="C:\Automation\MyTest"
   
   [SAFS_TEST]
   TestName="Mytest"
   
   TestLevel="Cycle"
   CycleSeparator="	" <======== NOTE: That is a TAB separator.
   CycleLogName="MyTestLog"
   CycleLogMode="TEXTLOG CONSOLELOG XMLLOG"
   
   [SAFS_ENGINES]
   First=org.safs.tools.engines.SAFSTC
   
   [SAFS_TC]
   AUTOLAUNCH=TRUE
   HOOK="C:\SAFS\TCAFS\TCAFS.vbs"
   Timeout=120
   
   ConvertSAFSInputKeysSyntax=TRUE
   
   ;Note: best practice is to comment out or not include "depthLevel" and just use the default of 5.
   ;depthLevel=25
   

Configuration for running either TestComplete or TestExecute on the same machine

Read this entire section before deciding which method to use to set your machine for either TestComplete or TestExecute.

1. When you are just running tests and not developing tests, you should use TestExecute instead of TestComplete.
2. TestExecute licenses are separate and cheaper than TestComplete licenses, so you can have more of them.
3. You can have both TestComplete and TestExecute installed on the same machine and you can execute either one.
4. You can modify the the System Environment Variables or C:SAFS\TCAFS\TCAFS.vbs file to invoke TestExecute instead of TestComplete.

5. You can switch runtime execution between TestComplete and TestExecute by setting the system environment variable TESTCOMPLETE_EXE to the desired EXE--"TestComplete.exe" or "TestExecute.exe" and TESTCOMPLETE_HOME to the proper install location.

6. You can also prepare separate TCAFS.vbs files--one for TestComplete and one for TestExecute.

Configuration for HTML and Flex playback (IMPORTANT!):

NOTE: If you will be testing web and/or Flex applications you should make sure you have the latest patches for your version of TestComplete and TestExecute supporting the versions of the browsers you will be using for testing.

Go to TestComplete Download Center and get any and all patches and instructions to apply the patches for BOTH TestComplete and TestExecute.

You will also need to follow the instructions in this Smartbear Support Article to install and configure the Adobe Debug Flash Player for Flex testing.

Additional information for configuring the debug player for Internet Explorer:

1. Download Adobe Debug Flash Player.
2. See Version Information Here
3. Configure for HTML and Flex playback per the install document above.
4. Configure the Flash Player for Flash injection:

   (Below is an overview of the steps, see the full details in this Smartbear Article.)

   • Create\Configure the ..\mm.cfg file
   • Add the fully-qualified name of the \Open Apps\Flex folder to the list of trusted locations in the Flash Player’s Flash Player Settings Manager.

You also need to verify/edit your TestComplete Project Properties settings:

1. Open TestComplete
2. Open your project (for our purposes, this is the TCAFS project)
3. From the main menu, select Tools > Current Project Properties
4. On the left side select Open Applications > Web Testing
5. On the right side select "Tree" from the Tree model dropdown.
6. Save the project
7. Exit TestComplete

TestComplete / Execute Enablement:

1. When you first move to Flex testing, you must make sure the your TestComplete Project directory (Ex: C:\SAFS\TCAFS\TCAFS\) has an up-to-date TCAFS.mds file appropriate for your version of TestComplete.

2. The System Environment "PATH" variable should have the STAF and SAFS "bin" directories at the beginning of the PATH:
   c:\staf\bin;C:\SAFS\bin;...

3. After making any System Environment variable changes, make sure you log out and back in so the Window's user session takes the changes.

Determine recognition strings:

1. Open TestComplete
2. Open your project or create a new project for determining your project strings. (Most testers use the C:\SAFS\TCAFS project.)
3. In your application, open to the dialog of interest (the one you want to determine the recognition string).
4. In TestComplete, in the toolbar, you can use the 'Map Object from Screen' icon or the 'Object Spy' icon.
5. Use the 'Map Object from Screen' tool if you just need the long string as this tool will not block your other windows.
6. Use the 'Object Spy' tool if you need information about object properties or if you need the short string for TFSM.
7. In the tool, click the "drag" button to the desired screen or component and release the mouse button.

8. Be patient....Really patient.

9. Eventually, the recognition string will be appropriately displayed in the tool.

10. HTML and Flex tip:
    For full strings, highlight the entire browser window to get the string for your Window component. The Window recognition string is not a prefix for the component strings in that window, so use the full string as given by TestComplete for each component as well.

11. For TFSM strings see the TFSM FAQ.

    If you are using TFSM strings:

    • If your test runs seem to be excessively slow in object find times, either use full strings, or reduce the depthLevel value in your TFSM strings to the very minimum (see the TFSM FAQ document referenced above).

      For example, do not set the depthLevel in the .ini file. Instead the default depthLevel=5 value is used. Then if some individual components require a larger depthLevel, just add the depthLevel to the recognition string for that component.

    • When creating TFSM component recognition strings, instead of using the generic Name property, it is best practice to use the FlexObject.name property. In this way, we will know immediately if development has provided the optional Name object property.
      Notes about Names:

      TestComplete creates the generic Name property and it can be created from the FlexObject.name, FlexObject.label, or FlexObject.id properties.

      If there is no FlexObject.name property, TestComplete will create the generic Name property from either the FlexObject.label or FlexObject.id properties.

      As an example, a ButtonLineChart component found in some Main window does NOT have the proper name property available. Instead of using the recognition string of Name=ButtonBarButton("line")--which masks the missing name property--it is best practice to try the recognition string of FlexObject.name=line.

      Note: If the FlexObject.name property is missing the object will not be found. This should prompt testers to inform development about the oversight as soon as possible.

      In the meantime, as a work around until development provides the name, testers can use the generic Name= property.

TestComplete 9 and TestComplete 10 on the same machine:

When\If you upgrade to TestComplete 10 it will prompt you to convert your project files to the TestComplete 10 format. So, before trying TestComplete 10, be sure to back up your TCAFS directory C:\SAFS\TCAFS.

The V10 conversion does not change many files, but does modify the .pjs and .mds files. So for those who want to try TestComplete 10, do the following (Assuming you have TestComplete 9 on machine already)

1. Make a copy of C:\SAFS\TCAFS
2. Install TestComplete 10 (it goes to a unique directory)
3. Make sure your License Manager is pointing to appropriate licenses, if applicable.
4. Bring up TestComplete 10, open up your existing TCAFS project (File->Open)
5. It will prompt to convert files (do so)
6. Exit TestComplete

If you want/need to have both TestComplete 9 and 10 on the same machine, please be aware of the following:

1. Have separate TCAFS project directories for V9 and one for V10

   Make sure you made a copy\backup of the V9 TCAFS Project before using V10 on it.
   TestComplete 10 will CONVERT the TCAFS project as mentioned above!
   This will allow you to use both V9 or V10, if you wish.

2. Note that V9 and V10 are in different named default install directories

3. Updating the applicable V9 or V10 TCAFS.VBS file to execute TestComplete or TestExecute
   o example paths:

   "C:\Program Files (x86)\SmartBear\TestComplete 9\Bin\TestComplete.exe"
   "C:\Program Files (x86)\SmartBear\TestComplete 10\Bin\TestComplete.exe"

   "C:\Program Files (x86)\SmartBear\TestExecute 9\Bin\TestExecute.exe"
   "C:\Program Files (x86)\SmartBear\TestExecute 10\Bin\TestExecute.exe"

4. Updating the Adobe Debug Flash Player..\mm.cfg file to load the correct swf
   o example mm.cfg settings:

   PreloadSwf=C:\Program Files (x86)\SmartBear\TestComplete 9\Open Apps\Flex\FlashInjector.swf
   PreloadSwf=C:\Program Files (x86)\SmartBear\TestComplete 10\Open Apps\Flex\FlashInjector.swf
   

Making sure you have both V9 and V10 swf directories defined in the Flash Player Settings Manager

If you want to run your tests with TestComplete 10, you will have to update your TCAFS.VBS script to point to TestComplete 10 instead of 9. Then let it rip.

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