Tester

Software Testing

WinRunner

www.TSLScripting.com

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

Want script example Winrunner code? I suggest that you begin with source from Data/Keyword Driven Frameworks

Sound: Disapointed “Oh man” by Cheech Marin

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

Site Map  
About this site  

Related Topics:
WinRunner Functions 
Data Driven Testing 
Transition Testing 
Sample Test 
LoadRunner 

From a MS Powerpoint file containing narration: Click here to pop this graphic up to a new floating window

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.

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");
web_link_click("Introduction");

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

"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.

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.
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

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	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.
Text Items	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
Graphic/ Controls	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
Special Controls	calendar	A standard MSW calendar object.	CDateTimeCtrl or CMonthCalCtrl
	spin	A spin object.
	Generic	object - Any object not included in one of the classes described here.

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.

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.

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.

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");
wait(1);
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"
sync_timer();
start_timer(timer1);
	wait(1); # 1=1000 ms # replace with whatever you're timing.
timer1ms=end_timer(timer1);
time_str_end = time_str(); # UNIX format "Tue Jun 11 11:45:05 2002"
timer1ms=86400002; #for debugging.
msg="";
tx=timer1ms;
if( tx > 8640000){ 
	t=int(tx/8640000); 
	msg=t&"days:"; 
	tx = tx-(t*8640000);
	}
if( tx > 360000){ 
	t=int(tx/360000); 
	msg=t&"hours:"; 
	tx = tx-(t*360000);
	}
if( tx > 6000){ 
	t=int(tx/6000); 
	msg=msg&t&"min:"; 
	tx=tx-(t*6000);
	}
if( tx > 1000){ 
	t=int(tx/1000); 
	msg=msg&t&"s:"; 
	tx = tx-(t*1000);
	}
if( msg == "" ){ 
	msg=timer1ms&" ms";
}else{
	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.

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.

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.

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.

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();
CloseWindow(hWnd);
win_activate ("Flight Reservation");
....

# To see WR again:
OpenIcon(hWnd);


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.

Read more about GetForegroundWindow() on MSDN.

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

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.

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

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.

Watch

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

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

C Programming Tutorials Over the Internet

Steve Holmes' Classic from Glasgow

Marshall Brain's How Stuff Works focuses on common misunderstandings.

More detail on Solaris, etc.

Sychronization

public variable my_wait_time

.

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

James Foster's May 2004 "Building a 'Test Friendly' Application"

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.

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.

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.