How I may help
LinkedIn Profile Email me!
Call me using Skype client on your machine

another page on this site Tester another page on this site Software Testing another page on this site WinRunner

Reload this page

Here are my notes on programming WinRunner TSL (Test Script Language) and crafting GUI maps,

Idea Want script example Winrunner code? I suggest that you begin with source from Data/Keyword Driven Frameworksanother page on this site

Sound: Disapointed “Oh man” by Cheech Marin


Topics this page:
on this page GUI Mapping
on this page Add-Ins
on this page Logical Names and Regular Expressions
on this page Learning GUI Maps
on this page MSW_Classes
on this page Checkpoints
on this page Errors & Debugging
on this page Synchronization
on this page Comparisons
on this page Exception Handling
on this page Conventions
on this page Your comments???


Site Map List all pages on this site 
About this site About this site 
Go to first topic Go to Bottom of this page

Related Topics:
another page on this site WinRunner Functions 
another page on this site Data Driven Testing 
another page on this site Transition Testing 
another page on this site Sample Test 
another page on this site LoadRunner 

  From a powerpoint file MS Powerpoint file containing narration:

WinRunner GUI
Click here to pop this graphic up to a new floating window

Set screen GUI Mapping Overview

  1. Two aspects of Activity in an Application under test are
  2. captured during a
  3. recording session:
  4. WinRunner generates script code into
  5. a script file.
  6. At the same time, newly recognized mappings of logical to physical names of classes and objects in the application WinRunner stores in a
  7. temporary gui map file
  8. that WinRunner uses later
  9. when it runs scripts
  10. to control the application under test.

  11. In order for WinRunner to reference objects from several GUI maps, it stores
  12. permanent GUI maps that can be
  13. loaded by several scripts.
  14. Use the GUI Map Editor to
  15. move individual entries from the
  16. temporary gui map to the
  17. permanent gui file.
  18. You can merge
  19. an entire GUI map into
  20. another.

  21. Object recognition during recording is controlled by the
  22. GUI Map Configuration service which
  23. resides in memory. The recognition process can be controlled by
  24. specifications that need to be
  25. copied and pasted into the initialization section of scripts. Otherwise,
  26. default recognition specifications are obtained from dll's when winRunner starts each time.

  27. When scripts misbehave (can't recognize objects),
  28. press the left Ctrl+F3 keys within
  29. the GUI Spy to capture object recognition specifications which can be
  30. copied and pasted into the GUI Map Editor.

  31. Objects can also be learned dynamically with a
  32. double click of the mouse
  33. into the temporary GUI map.

Go to Top of this page.
Previous topic this page
Next topic this page

Set screen Logical vs. Physical GUI Map Names

    TSL code identify objects using virtual names. The physical descriptions are stored in a GUI map.

    The TSL statement below presses the "Introduction" link in the AUT's "Main Menu" window:

      set_window("Main Menu");

    These references needs to be pre-defined before the test is run.

      Reminder "Each object mentioned in a test script must exist in the GUI map."

    Internally, WinRunner looks up the physical description associated with logical names in gui map files. For example, in the GUI file entry below, "class:" and "label:" are the physical attributes to the logical name "Main Menu":

      class: window,
      label: "!Main Menu.",

      The class property defines the object's type.

      The exclamation point ! starts a regular expression which interprets the period as a wildcard which allows any text to come after "Main Window".

    In WinRunner, testers can use human-readable Logical Names to reference each unique window and object presented by the AUT. The logical name for an edit field is typically the text label associated with that field.

    WinRunner can "learn" the names of windows and objects from looking inside the AUT itself.

    As WinRunner captures actions into script code, it also captures the names and recognition parameters into a temporary GUI map.

    Those recognition parameters are determined by GUI Map configuration specifications which WinRunner has in memory.

    Reminder When you click on Tools > GUI Map configurations, what you see is from WinRunner memory that disappears when WinRunner exits.

    To save the configuration, use the "Paste" button.
    Reminder So before you click "GUI Map Configuration", position your cursor at the part of your custom initialization script where you want the configurations to type when you click that "Paste" button.

    GUI maps have file extension of .gui . Since they are shared by several scripts, they are stored in a common folder. GUI map files exceeding 500 items may cause performance problems for the GUI Map Editor.


    WinRunner's logical name assignment capability during recording can be customized using the add_cust_record_class function.

    The mic_if Mercury Interface API (Application Programming Interface) library can be used to conduct "inside testing" of "invisible" applications that have no user interface because this library uses pipe and RPC (Remote Procedure Call) communication mechanisms. Samples of this are in \samples\inside.tst\src\ insidtst.exe

Go to Top of this page.
Previous topic this page
Next topic this page

    Set screen Classes

    This is reorganized from WinRunner User's Guide Part VI - "Working with the GUI Map" - "Configuring the GUI Map" - "Understanding WinRunner Objects Classes". Links are provided to my page detailing specific functions.

    Type Class Name Description ActiveX Name
    Window window another page on this site Any application window, dialog box, or form, including MDI windows.
    frame_mdiclient Enables WinRunner to treat a window as an mdiclient object.
    mdiclient An mdiclient object.
    mic_if_win Enables WinRunner to defer all record and run operations on any object within this window to the mic_if library described in the WinRunner Customization Guide.
    Itemsanother page on this site
    status bar A status bar on a window.
    static_text Display-only text not part of any GUI object.
    edit A text input field. EditBox
    list Pull-down menu selection ListBox
    Controls another page on this site
    check_button A check box. CheckBox
    push_button A push (command) button.
    radio_button A radio (option) button.
    menu_item A menu item.
    scroll A scroll bar or slider.
    tab A tab item.
    toolbar A toolbar object. ToolbarWindow32
    Controls another page on this site
    calendar A standard MSW calendar object. CDateTimeCtrl or
    spin A spin object.
    Generic object - Any object not included in one of the classes described here.


Go to Top of this page.
Previous topic this page
Next topic this page

Set screen Learning GUI Maps

    WinRunner always learns Obligatory properties.

    What is obligatory can be specified in tools > GUI Map Configuration. After selecting the class (such as "object"),

    WR also learns optional properties to ensure uniqueness of identification.

    To differentiate among objects with the same name, WinRunner appends "_1", "_2", etc. These are called spatial location selectors.

    You can manually edit the gui map to add index selector numbers to control uniqueness among physical descriptions.

    Reminder A large number of items in the gui map can make playback very slow! So only learn the elements that will actually be referenced by scripts.

    KB 17955 "WinRunner does not have a direct method to learn objects into a GUI Map file from within a script." However, the GUI_add function allows you to add objects to the GUI Map at runtime, if know the physical description of the object before calling the function.

    The GUI Map will not allow a variable to be used in place of an actual value. However, you can update the GUI Map at runtime or use the object's physical description directly within the function using the GUI_buf_set_desc_attr function, which sets the value of a property for an object in a GUI Map file. See Problem ID 26036 - How to add a property to the physical description of an object in the GUI Map.

    You can also build the physical description for an object at runtime and use it directly. This option bypasses the GUI Map completely. See KB 4391 - How to use a physical description in place of a logical name.

    KB 25653 - How to use a physical description in a set_window() function

    KB 4389 - How to map a custom object to a standard object

    User-defined custom objects are defined in physical description with class value of simply "object".

    The "Virtual Object Wizard" from the Tool menu provides cross hairs for a tester to mark the specific coordinates of objects and assign them a logical name. However, be aware that virtual objects must be relearned whenever those objects are moved or resized.

Go to Top of this page.
Previous topic this page
Next topic this page

    Set this at top of window. GUI Map Properties

    This is reorganized from WinRunner User's Guide Part VI - "Working with the GUI Map" - "Configuring the GUI Map" - "Understanding Object Properties"

    Type Property Description
    ID class The GUI objects classes recognized by WinRunner [above]
    class_index An index number that identifies an object, relative to the position of other objects from the same class in the window (Java add-in only).
    handle A run-time pointer to the object: the HWND handle.
    MSW_class The Microsoft Windows class.
    regexp_MSWclass The Microsoft Windows class combined with a regular expression. Enables WinRunner to identify objects with a varying MSW_class.
    MSW_id The Microsoft Windows ID.
    TOOLKIT_class The value of the specified toolkit class. The value of this property is the same as the value of the MSW_class in Windows, or the X_class in Motif.
    owner (For windows), the application (executable) name to which the window belongs.
    vb_name A text string assigned to Visual Basic objects by the developer (the name property). (The property applies only to WinRunner with Visual Basic add-in support.)
    pb_name A text string assigned to PowerBuilder objects by the developer. (The property applies only to WinRunner with PowerBuilder add-in support.)
    obj_col_name A concatenation of the DataWindow and column names. For edit field objects in WinRunner with PowerBuilder add-in support, indicates the name of the column.
    module_name The name of an executable file which created the specified window.
    Text text The visible text in an object or window.
    attached_text The static text located near the object.
    label The text that appears on the object, such as a button label.
    regexp_label The text string and regular expression that enables WinRunner to identify an object with a varying label.
    Rank parent The logical name of the parent of the object.
    nchildren The number of children the object has: the total number of descendants of the object.
    count The number of menu items contained in a menu.
    position The position (top to bottom) of a menu item within the menu (the first item is at position 0).
    num_columns A table object in Terminal Emulator applications only.
    num_rows A table object in Terminal Emulator applications only.
    Number abs_x The horizontal x-coordinate of the top left corner of an object, relative to the origin (upper left corner) of the screen display.
    abs_y The vertical y-coordinate of the top left corner of an object, relative to the origin (upper left corner) of the screen display.
    x The horizontal x-coordinate of the top left corner of an object, relative to the window origin.
    y The vertical y-coordinate of the top left corner of an object, relative to the window origin.
    height Height up/down an object, in screen pixels.
    width Width across an object, in screen pixels.
    Boolean active 1 indicates this is the top-level visible window associated with input focus.
    displayed 1 indicaties this object is displayed, visible on screen, 0 if not.
    enabled 1 indicates the object can be selected or activated, 0 if not.
    focused 1 indicates whether keyboard input will be directed to this object, 0 if not.
    maximizable 1 indicates the window can be maximized, 0 if not.
    minimizable 1 indicates the window can be minimized, 0 if not.
    submenu 1 indicates this menu item has a submenu, 0 if not.
    sysmenu 1 indicates the menu item is part of a system menu, 0 if not.
    Mixed value Different for each class:
    Radio and check buttons: 1 if the button is checked, 0 if not.
    Menu items: 1 if the menu is checked, 0 if not.
    List objects: indicates the text string of the selected item.
    Edit/Static objects: indicates the text field contents.
    Scroll objects: indicates the scroll position.
    All other classes: the value property is a null string.

Go to Top of this page.
Previous topic this page
Next topic this page

    Set screen Timer: How long did that take to run?

    Because their timer variable is not available to the script to format, we shouldn't use built-in WinRunner functions:

      declare_transaction ( "test" );
      x = start_transaction("test");
      y = end_transaction("test",PASS);

    My preferred way is to use the timer functions within the CSOLIB2 library. This example formats the milliseconds into longer HH:MM:SS:ms presentation.

      time_str_start = time_str(); # UNIX format "Tue Jun 11 11:45:05 2002"
      	wait(1); # 1=1000 ms # replace with whatever you're timing.
      time_str_end = time_str(); # UNIX format "Tue Jun 11 11:45:05 2002"
      timer1ms=86400002; #for debugging.
      if( tx > 8640000){ 
      	tx = tx-(t*8640000);
      if( tx > 360000){ 
      	tx = tx-(t*360000);
      if( tx > 6000){ 
      if( tx > 1000){ 
      	tx = tx-(t*1000);
      if( msg == "" ){ 
      	msg=timer1ms&" ms";
      	msg=msg&tx&"ms ("&timer1ms&" ms)";
      pause( "... took "&msg& " from "&time_str_start&" to "&time_str_end);

    Use of this sample assumes that you have loaded the libraries in the initialization section of your TSL script.

Go to Top of this page.
Previous topic this page
Next topic this page

Set screen Actual Results May Vary: Checklists and Checkpoints

    The purpose of testing is to find bugs by recognizing where actual results differ from expected results.

    TSL code such as the following is used to detect differences:

    win_check_gui("Login", SHARED_CL & "Login.ckl", "gui2", 1);

    This code compares expected results in the shared "Login.ckl" checklist file against the "gui2" actual results file.

    Note that expected results in checklist files have a file extension of .ckl. These files are stored in the "chklist" folder associated with each specific script or in the shared scope folder referenced by several scripts. This folder is designated from Settings, General Options, Folders tab.

    To create a checklist file

    First, click the script editor pointer to a blank line and not in the middle of another statement. This is because when you click "OK" from the "Create GUI Checkpoint" dialog, WinRunner automatically inserts code.

    Press F12 for the default equivalent to selecting Create, GUI Checkpoint, for Multiple objects. WinRunner automatically comes up with a checklist file named something like "list1.ckl", which you could rename when you save it as something else.

    To specify what will be checked

    Click the Add button from the "Create GUI Checkpoint" dialog window, left click with your mouse on the object being checked, then right click.

    On the right pane, WinRunner presents standard properties with default checks automatically checked for you.

    Check the names of properties you want compared.

    Remember: Only the properties you check will be stored in the checklist file. The properties you don't check will not be stored in the checklist file.

Note: The links to documents which used to be here were removed at the request of Mercury Interactive lawyers. I guess they don't want people to know about their software. God forbid that anyone actually can figure out how to use their product.

WinRunner Tutorial pdf Winrunner Tutorial, WinRunner User Guide 1095 page pdf User Guide, WinRunner Help Help, WinRunner Customization Guide pdf Customization Guide
TSL reference 480 page pdf TSL (Test Script Language) Reference, TSL Help Help, TSL Sample Help Sample code
Test Directory API Help Test Director API Help

Page numbers in online pdf files are different (have more pages) than page numbers in the paper document of the same title.

Go to Top of this page.
Previous topic this page
Next topic this page

Set screen New Checks

    To add default checks

    Use the gui_ver_set_default_checks against existing check names.

    Note that check names may not contain spaces, since the list of check names specified in this function are separated by spaces.

    To add check names not listed

    (such as "font size"), create a custom capture and comparison function.

    To add a check class

    (such as "pbTool"), create a custom capture and comparison function.

    To add expected results to a checklist file

    From the win_check_gui and obj_check_gui function stores results in an expected results file.

    To reference a checklist file

    The default_compare_func function is used for simple comparisons.

These are Customization Guide "custom.pdf" file.

Go to Top of this page.
Previous topic this page
Next topic this page

Set screen Run-time Control of Scripts

    A simple Yes or No will do:

    If a Yes/No question is needed to allow the tester to dynamically control script execution, don't look at WinRunner's Custom User Interface Functions .

    But consider a function not documented in the help file:

    rc = pause_test( "Do you eat meat?", "Y&es", "&No");
    if (rc == 0) {
      # Yes:
    else {   (rc == 1)
      # No:

    The ampersand in Yes and No specifies use of keyboard Alt-E for Yes or Alt-N for No.

    If there is a question mark in the first parameter string, a question bubble graphic displays. A period at the end of the text string results in a caution icon.

    Window MessageBox API ?

Customization Functions:

  • create browse file dialog
  • create custom dialog ( function to execute, dialog window title, button name, edit field label, check field label );
  • create input dialog
  • create list dialog
  • create password dialog ( Login field label, Password field label, username out, password out, encrypt password);

A "Cancel" button is automatically added to these dialogs.

Go to Top of this page.
Previous topic this page
Next topic this page

Set screen Multiple Windows

    A Bad Example

    In WinRunner 7, there is a bug in the identify script in the \samples\general folder under wherever you installed WinRunner (C:\Program Files\Mercury Interactive\WinRunner\)

    The logic to determining the common label using the Operating System is backward. The Windows NT version of Notepad is initiated with a title of "Untitled - Notepad". The Windows 95 version of Notepad is initiated with a title of "Notepad - (Untitled)". Only the Microsoft Gods know why this difference came about.

    Getting A Handle On The Window

    Anyway, its strategy is to capture the internal handle number (named hWnd) of each window by using the win_get_info() function to obtain a physical description.

    The gui_add function is then used to associate each handle to a logical name referenced by other WinRunner statements.

    Minimizing WinRunner Itself

    WinRunner can minimize itself by using the Win32API function library to get the internal handle than Windows uses for the active window (hWnd).

    load ( "win32api", 1, 1 );
    extern int CloseWindow(unsigned int);
    extern int OpenIcon(unsigned int);

    hWnd = GetForegroundWindow();
    win_activate ("Flight Reservation");

    # To see WR again:

    Load and a one and a two

    The load statement above converts the script into "internal form".

    The first 1 is to designate system module rather than a usermodule. A closed module is "invisible" to the tester. It is not displayed when it is loaded, cannot be stepped into, and is not stopped by a pause command.

    The second 1 is to close the script rather than leaving it open.

webpage article Read more about GetForegroundWindow() on MSDN.

Among Microsoft's User32.lib functions:
webpage article CloseWindow(hWnd) minimizes a window.
webpage article OpenIcon(hWnd) restores a minimized window to its previous size and position.

Go to Top of this page.
Previous topic this page
Next topic this page

Set screen Defining Special Object Classes

    Some applications have special objects of their own which WinRunner cannot recognize. Examples of this include the color palette object in PaintBrush and the numbers in Calculator.

    In recording mode, if WinRunner doesn't know how to read a special object, all it can do is recognize the screen coordinates of where a mouse was clicked and generate obj_mouse_click() and obj_mouse_drag() statements.

    An object's "MSW_Class" property specifies the object class.

    In replay mode, WinRunner doesn't know how to get attributes from the AUT unless it registers a custom attribute which depends on a DLL (Dynamic Load Library) module which WinRunner can exercise from an external verification function.

    In replay mode, WinRunner will not recognize an object if it is moved away from the x and y coordinates where they were found when they were recorded.

    set_record_attr specifies an MSW_id (Microsoft Window id). MSW_class ??

    Virtual objects

    Analog mode

Under the Tools menu, the GUI Map Configuration window lists the classes of objects. By default,

the standard object classes are: window, tab (menu), scroll (bar), toolbar, menu_item, list, static_text, combobox, edit (field), check_button, push_button, radio_button, spin (control)

In the GUI Map Configuration list of classes, user defined classes are always automatically preceded with the the letter "U" and appear below standard classes.

Go to Top of this page.
Previous topic this page
Next topic this page

Set this at top of window. Errors and Debugging

    Error Codes

    The most common error codes (you would do well to memorize) are:

      Error Code Named constant object
      -10002 E_NOT_FOUND window
      -10003 E_NOT_UNIQUE (in gui map)
      -10005 E_OUT_OF_RANGE  
      -10011 E_NOT_IN_MAPPING (GUI map)
      -10105 E_ITEM_NOT_FOUND within a list
      -10101 E_NOT_DISPLAYED  

    Reminder Constants such as E_OK have names defined in file hlerr.h which maps to a set of "internal constants" such as "MIC_E_OK" defined with actual values (such as 0) in header file mic.h (so named because MIC is an acronymn for "Mercury Interactive Corporation"). This is referenced in the mic_if.h file, all within the custom\mic_if folder where WinRunner is installed. The short names of error codes are defined there.


    Idea To save space/time selecting variables to watch, use the same private variable names within functions, such as i for iterator, n for element count, etc.

    Step Through

    Reminder Do not step through right clicks in code lines such as:

      list_select_item ("SomeContextMenu", menuitem, RIGHT);
      menu_select_item ("Rename");

    If you do, menu_select_item will not recognize the pop-up menu.

    Instead, set a stop after the item is selected in menu_select_item and execute "From Arrow" rather than one step at a time (with the default F6 key).

    Optional Execution of Scripts

    if( my_results_lvl>= 2 ) report_msg("Run done " & time_str() );

    The variable my_results_lvl controls how much information is sent to the results table.

      0 = No messages.

      1 = Error and warning messages only.

      2 = Run environment, count of records in files used, start/end time, plus the above.

      3 = Every data table record at each step plus all of the above.

    Level of Pausing

    The variable my_pause_lvl controls how often to pause.

      0 = Never.

      1 = At file level error conditions only.

      2 = At each error in the script.

      3 = At each data table record read and successfully processed as well as all the above.

    Sample code:

    tl_msg = "Row:"& my_table_Row &" Found:"& text &" Expected:"& my_exp_text &" Agent:"& my_agent_name ;

    if( my_pause_lvl>= 3 ) pause( tl_msg );

    Print to a window

    WinRunner has an undocumented command which prints a string to a separate window. Example:

    tl_msg = "Row:"& my_table_Row &" Found:"& text &" Expected:"& my_exp_text &" Agent:"& my_agent_name ;

    if( my_pause_lvl>= 3 ) pause( tl_msg );

Go to Top of this page.
Previous topic this page
Next topic this page

Set this at top of window. Sychronization

    public variable my_wait_time


Go to Top of this page.
Previous topic this page
Next topic this page

Set this at top of window. Comparisons

    Use compare_text to find the difference between two strings.

    Use file_compare to find the difference between two files.

    file_compare( "file1", "file2", "differences_file" );

    To view the results, open the WinRunner Report form (Tools> Reports) and double-click on the file_compare line in the test log. This opens the Win_Diff Utility to display results from the file comparison.

    To get a listing of files in a folder (formerly called a directory), use a CSOLIB function:

    my_dir = "C:\\CPSTests";
    my_folder = my_dir ; # the folder/directory
    out_file = my_dir & "\\dir.txt"; # for output
    file_open( out_file, FO_MODE_WRITE);
    get_directory_listing( my_folder, out_file );
    file_close( out_file );

Go to Top of this page.
Previous topic this page
Next topic this page

Set this at top of window. Exception Handling

    WinRunner provides these standard functions:

    • exception_off -- Deactivates handling for an exception.
    • exception_off_all -- Deactivates handling of all exceptions.
    • exception_on --- Enables detection and handling of a previously defined exception.

    Exceptions can be defined from Tools> Exception Handling. However, I prefer to hard-code define_...exception commands for better maintainability at the sacrifice of run speed.

    Trigger TSL function WRUN.INI key
    window define_popup_exception( XR_EXCP_POPUP
    object define_object_exception( XR_EXCP_OBJ
    Return Code define_tsl_exception( XR_EXCP_TSL

    In large applications with lots of different errors which can pop up, it many be handy to use a spreadsheet matrix (WR ddt table) to specify the exceptions which are expected from the exceptions which are not expected for each test case -- helpful for thorough testing of exception handling (a task usually too tedious for most developers and even many testers to manually perform diligently).

    Exception Condition Expected Testcase
    msg window Email address doesn't contain @ Yes Cust Profile Values Neg Test
    rc -10137 E_WAIT_INFO_TIMEOUT Yes DB hung neg test
    button red Yes Alert test


When a web exception handler is created, file Exception.inf -- the Exceptions description and management file -- is created in the WinRunner \arch folder.

The active value in this file must be equal to 1 if the Web Exception function is to be handled.

Go to Top of this page.
Previous topic this page
Next topic this page

Set screen Juggling Script Files

    Call begins the interpretation of script files.

    Reload places compiled function libraries into memory, ready fur use.

    There are two ways to compile a function library:

    • Instead of using the reload command, use the load command, which compiles every time before loading.
    • Open a script, and select File>Test Properties, and select "Compiled Module" radio button.

Go to Top of this page.
Previous topic this page
Next topic this page

    Set screen Including Files with Dynamically Compiling a DLL

    Unlike other C programs, WinRunner ignores "#include" compiler directives. I don't know why.

    But there is a (rather convoluted) way to dynamically supply TSL script code in a separate file — make calls to have WinRunner compile a dll which picks up that script code, then invoke that DLL.


Go to Top of this page.
Previous topic this page
Next topic this page

Portions ©Copyright 1996-2010 Wilson Mar. All rights reserved. | Privacy Policy |

How I may help

Send a message with your email client program

Your rating of this page:
Low High

Your first name:

Your family name:

Your location (city, country):

Your Email address: 

  Top of Page Go to top of page

Thank you!