Winrunner Commands (2)

1) How Winrunner executes test using context sensitive testing?

Context Sensitive testing enables you to test your application as the user sees it—in terms of GUI objects—such as windows, menus, buttons, and lists. Each objecthas a defined set of properties that determines its behavior and appearance.WinRunner learns these properties and uses them to identify and locate GUIobjects during a test run. WinRunner does not need to know the physical locationof a GUI object to identify it.

Before you can begin Context Sensitive testing, WinRunner must learn theproperties of each GUI object in your application. Use the RapidTest Script wizardto guide you through the learning process. It systematically opens each windowin your application and learns the properties of the GUI objects it contains.WinRunner also provides additional methods for learning the properties ofindividual objects.

As the user interface of your application changes, you can continue to use testsyou already developed. You simply add, delete, or edit object descriptions in theGUI map so WinRunner can continue to find the objects in your modifiedapplication.

2) How a Test Identifies GUI Objects?

WinRunner uses a logical name to identify an object: for example “Print” for a Printdialog box, or “OK” for an OK button. This short name connects WinRunner to theobject’s longer physical description. This detailed description (the logical nameand the physical description) ensures that each GUI object has its own uniqueidentification. The physical description contains a list of the object’s physicalproperties: the Print dialog box, for example, is identified as a window with thelabel “Print”.

Logical Name:

set_window ("Readme.doc - WordPad", 10);menu_select_item ("File;Print... Ctrl+P");set_window ("Print", 12);button_press ("OK");

Physical Description:

Readme.doc window: {class: window, label: "Readme.doc - WordPad"}File menu: {class:menu_item, label:File, parent:None}Print command: {class: menu_item, label: "Print... Ctrl+P", parent: File}Print window: {class:window, label:Print}OK button: {class:push_button, label:OK}

GUI Map editor process:

Learning the GUI with the RapidTest Script Wizard

The RapidTest Script wizard enables WinRunner to learn all windows and objectsin your application being tested at once. It systematically opens every window inthe application and learns the GUI objects it contains. WinRunner then instructsyou to save the information in a GUI map file. A GUI_load command that loads

this file is added to a startup test.

Note: The RapidTest Script wizard is not available for when working with theTerminal Emulator or WebTest add-ins. Therefore, if you are using these add-ins,do not complete this section or the following sections of this lesson. Instead,after you create and run tests in the other tutorial lessons, you must save yourtemporary GUI map file whenever you close WinRunner or close a test script youwant to save. A temporary GUI map file contains the information that WinRunnerlearns about GUI objects in your application.

Learning the GUI by Recording

Learning the GUI Using the GUI Map Editor

Saving the GUI Map

Loading the GUI Map File

WinRunner uses GUI map files to locate objects in the application being tested.You must load the appropriate GUI map files before you run tests on yourapplication being tested.You can load GUI map files in one of two ways:using the GUI_load function

from the GUI Map EditorYou can view a loaded GUI map file in the GUI Map Editor. A loaded file isindicated by the letter “L” and a number preceding the file name.

Winrunner Commands:

set window Specifies the window to receive input, according to the window's logical name.set window Specifies a window to receive input, according to the window's physical description.win activate Activates a window.win check bitmap Compares a current window bitmap to an expected bitmap.win check gui Compares current GUI data to expected GUI data.

win check info Checks the requested window property.win click help Clicks the help button in a window title bar.win click on text Clicks on text in a window.win close Closes a window.win drag Drags an object from a source window.win drop Drops an object on a target window.

win exists Checks whether a window is displayed.

win find textReturns the location of a string in a window.win get desc Returns the physical description of a window.win get info Returns the value of a window property.win get text Reads text from a window.win highlightHighlights a window.win max Maximizes a window.win min Minimizes a window to an icon.

win mouse click Clicks in a window.win mouse dbl click Double-clicks in a window.win mouse drag Drags the mouse in a window.win mouse move Moves the mouse in a window.win move Moves a window to a new absolute location.win move locator text Moves the mouse to a string in a window.win open Opens a window.

win resize Resizes a window.win restore Restores a window from a minimized or maximized state to its previous size.win type Sends keyboard input to a window.win wait bitmap Waits for a window bitmap.win wait info Waits for the value of a window property.

===============================================================

activates a window.

win_activate ( window );

window The logical name of the window.

The win_activate function makes the specified window the active window by bringing it into focus and raising it to the top of the display (equivalent to clicking on the window banner). All subsequent input is submitted to this window.

activates a window.

===============================================================

_set_window ( desc, time );

desc The physical description of the window.

time The time is added to the timeout test option to give the maximum interval, in seconds, before the next statement is executed. (WinRunner) or XR_TIMEOUT configuration parameter (XRunner)

The _set_window function performs the application part of the set_window function, by setting the active window in the application under test. (The GUI part is performed by GUI_set_window.)

Note that while set_window receives the window's logical name, _set_window receives its physical description.

===============================================================

compares a window bitmap to an expected bitmap.

win_check_bitmap ( window, bitmap, time [, x, y, width, height ] );

window The logical name of the window.bitmap A string expression that identifies the captured bitmap.time The interval marking the maximum delay between the previous input event and the capture of the current bitmap, in seconds. This interval is added to the timeout test option (WinRunner) or XR_TIMEOUT configuration parameter (XRunner) before the next statement is executed.x, y For an area bitmap: the coordinates or the upper left corner, relative to the window in which the selected area is located.

width, height For an area bitmap: the size of the selected area, in pixels.

The win_check_bitmap function captures and compares bitmaps of a window or window area. During test creation, the specified window or area is captured and stored. During a test run, the current bitmap is compared to the one stored in the database. If they are different, the actual bitmap is captured.

This function is generated during the recording of a test. Since the test is waiting for a result, the test should be run in update mode. For more information regarding the update mode, refer to the "Running Tests" chapter in your User's Guide.

When an area of the window is captured, the additional parameters x, y, width and height define the area's location and dimensions.

The analog version of win_check_bitmap is check window.

===============================================================

compares a window bitmap to an expected bitmap.

win_check_bitmap ( window, bitmap, time [, x, y, width, height ] );

window The logical name of the window.bitmap A string expression that identifies the captured bitmap.time The interval marking the maximum delay between the previous input event and the capture of the current bitmap, in seconds. This interval is added to the timeout test option (WinRunner) or XR_TIMEOUT configuration parameter (XRunner) before the next statement is executed.x, y For an area bitmap: the coordinates or the upper left corner, relative to the window in which the selected area is located.

width, height For an area bitmap: the size of the selected area, in pixels.

The win_check_bitmap function captures and compares bitmaps of a window or window area. During test creation, the specified window or area is captured and stored. During a test run, the current bitmap is compared to the one stored in the database. If they are different, the actual bitmap is captured.


When an area of the window is captured, the additional parameters x, y, width and height define the area's location and dimensions.

The analog version of win_check_bitmap is check window.

===============================================================

compares current GUI data to expected GUI data for a window.

win_check_gui ( window, checklist, expected_results_file, time );

window The logical name of the window.checklist The name of the checklist specifying the checks to perform.expected_results_fileThe name of the file storing the expected GUI data. time The time is added to the timeout test option to give the maximum interval between the previous input even and the screen capture. (WinRunner) or XR_TIMEOUT configuration parameter (XRunner)

The win_check_gui function captures and compares GUI data for a window. During test creation, the specified GUI data is captured and stored. When you run a test, the current GUI data is compared to the data stored in expected_results_file, according to a checklist specifying the information to be checked. A file containing the actual results is also generated. For more details on using win_check_gui, refer to the “Checking GUI Objects” chapter in your User's Guide.

===============================================================

compares current GUI data to expected GUI data for a window.

win_check_gui ( window, checklist, expected_results_file, time );

window The logical name of the window.checklist The name of the checklist specifying the checks to perform.expected_results_fileThe name of the file storing the expected GUI data. time The time is added to the timeout test option to give the maximum interval between the previous input even and the screen capture. (WinRunner) or XR_TIMEOUT configuration parameter (XRunner)

The win_check_gui function captures and compares GUI data for a window. During test creation, the specified GUI data is captured and stored. When you run a test, the current GUI data is compared to the data stored in expected_results_file, according to a checklist specifying the information to be checked. A file containing the actual results is also generated. For more details on using win_check_gui, refer to the “Checking GUI Objects” chapter in your User's Guide.

===============================================================

checks the requested window property.

win_check_info ( window, property, property_value );

window The logical name of the window.property The property to check.property_value The expected value of the property.

The win_check_info function checks that the current value of the specified property matches the property_value.===============================================================

clicks the help button in a window title bar.

win_click_help ( window );


The win_click_help function click's the help button in the specified window's title bar.

===============================================================

searches for text in a window.

win_click_on_text (window, string [ ,search_area ] [ , string_def [ , mouse_button ] ]);

window The logical name of the window.string The text to locate. To specify a literal, case sensitive string, enclose the string in quotation marks. Alternatively, you can specify the name of a string variable. The value of the string variable can include a regular expression (the regular expression need not begin with an exclamation mark). For more information regarding regular expressions, refer to the "Using Regular Expressions" chapter in your User's Guide.

search_area The region of the object to search, relative to the window. This area is defined as a pair of coordinates, with x1,y1,x2,y2 specifying any two diagonally opposite corners of the rectangular search region. If this parameter is not defined, then the entire window specified is considered the search area.string_def Defines how the text search is performed. If no string_def is specified, (0 or FALSE, the default parameter), the interpreter searches for a complete word only. If 1, or TRUE, is specified, the search is not restricted to a single, complete word.

mouse_button Specifies the mouse button that clicks on the text string. The value can be LEFT, MIDDLE, or RIGHT. If no button is specified, the default is the left button.

The win_click_on_text function searches for a specified text string in the indicated window or in an area of the window. It then moves the screen pointer to the center of the text string and clicks on the string.

Before using win_click_on_text, make sure the fonts used by your AUT have been learned. This step is always required for XRunner, and may be required for WinRunner. For more information on learning fonts, refer to the “Checking Text” chapter in your User's Guide. Note that when win_click_on_text is used with a learned font, then WinRunner searches for a single, complete word only. This means that any regular expression used in the string parameter must not contain blank spaces, and only the default value of the string_def parameter, FALSE, is in effect.

The analog version of this function is click_on_text.

===============================================================

closes a window.

win_close ( window );


The win_close function closes the specified window.

drags an object from a source window.

win_drag (source_window, x, y [, mouse_button ] );source_window The logical name of the window.x,y The coordinates of the mouse pointer when clicked on the source window, relative to the upper left corner of the client area of the source window expressed in pixels.mouse_button A constant that specifies the mouse button to hold down while dragging. The value can be LEFT, MIDDLE, or RIGHT. If no button is specified, the default is the button that performs the select function.

The win_drag function is used in combination with win_drop, obj_drop, or list_drop_on_item, to move data between GUI objects. A win_drag statement is recorded when the mouse pointer is over the source window, prior to being dragged and after the mouse button is pressed.

===============================================================

drops an object onto a target window.

win_drop ( target_window, x, y );target_window The logical name of the window.x,y The coordinates of the mouse pointer when released over the target window, relative to the upper left corner of the client area of the target window, expressed in pixels.

The win_drop function is used in combination with win_drag, obj_drag, or list_drag_item, to move data between GUI objects. A win_drop statement is recorded when the mouse pointer is over the target window, prior to release.

checks whether a window is displayed on the screen.

win_exists ( window [, time ] );

window The logical name of the window.time The time is added to the timeout test option to give the maximum interval, in seconds, before the next statement is executed. (WinRunner) or XR_TIMEOUT configuration parameter (XRunner)

The win_exists function checks whether the specified window appears on the screen. Use the time parameter to control test synchronization. Note that the timeout does not affect the function if no time is specified.

returns the location of a string within a window.

win_find_text ( window, string, result_array [, search_area] [, string_def ]);

window The logical name of the window to search.string The text to locate. To specify a literal, case sensitive string, enclose the string in quotation marks. Alternatively, you can specify the name of a string variable. The value of the string variable can include a regular expression. The regular expression should not include an exclamation mark (!), however, which is treated as a literal character. For more information regarding Regular Expressions, refer to the "Using Regular Expressions" chapter in your User's Guide.

result_array The name of the output variable that stores the location of the string as a four-element array. search_area The region of the object to search, relative to the window. This area is defined as a pair of coordinates, with x1,y1,x2,y2 specifying any two diagonally opposite corners of the rectangular search region. If this parameter is not defined, then the entire window is considered the search area.string_def Defines how the text search is performed. If no string_def is specified, (0 or FALSE, the default parameter), the interpreter searches for a complete word only. If 1, or TRUE, is specified, the search is not restricted to a single, complete word.

The win_find_text function searches for a specified text string in the specified window or area of the window and stores the location of the string in an output variable.

Before using win_find_text, make sure that the fonts used by your AUT have been learned. This step is always required for XRunner, and may be required for WinRunner. For more information on learning fonts, refer to the “Checking Text” chapter in your User's Guide. Note that when win_find_text is used with a learned font, then WinRunner searches for a single, complete word only. This means that any regular expression used in string must not contain blank spaces, and only the default value of string_def, FALSE, is in effect.

The Analog version of this function is find_text.

===============================================================

returns the physical description of a window.

win_get_desc ( window, obligatory, optional, selector, out_desc );

window The logical name of the window.obligatory The list of obligatory properties (separated by spaces).optional The list of optional properties (separated by spaces).selector The type of selector used for this object class (location or index).out_desc The output variable that stores the description of the window.

The win_get_desc function returns the physical description of a window. This includes a list of obligatory and optional properties and the type of selector used. This information is stored in out_desc. Note that if obligatory, optional, and selector are null strings, win_get_desc returns the current learning configuration for the object.===============================================================

returns the value of a window property.

win_get_info ( window, property, out_value );

window The logical name of the window.property Any of the properties listed in the User's Guide.out_value The variable that stores the value of the specified property.

The win_get_info functions retrieves the value of the specified property and stores it in out_value.===============================================================

reads text from the indicated area of a window.

win_get_text ( window, out_text [, x1, y1, x1, y2] );

window The window from which text is read.out_text The output variable that holds the captured text.x1,y1,x2,y2 An optional parameter that defines the location from which to read text relative to the specified window in pixels. The coordinate pairs can designate any two diagonally opposite corners of a rectangle. The interpreter searches for the text in the area defined by the rectangle.

The win_get_text function reads text from the specified window, or area of the window.

Before using win_get_text, make sure that the fonts used by your AUT have been learned, if necessary. For more information, refer to the “Checking Text” chapter in your User's Guide.

If Learn Fonts has been performed, win_get_text can read only one line of text. If the enclosed area contains more than one line of text, then the line beginning

furthest to the left is read. If more than one line begins at the same point on the left, the bottommost line is read. The maximum number of characters that can be captured in one win_get_text statement is 2048.

The Analog version of this function is get_text.

===============================================================

highlights the specified window.

win_highlight ( window [, flashes ] );

window The logical name of the window.flashesThe number of times the window flashes on screen.

The win_highlight function highlights the specified window. The flashes option sets the number of times the window flashes on the screen.===============================================================

maximizes a window to fill the entire screen.

win_max ( window );


The win_max function maximizes the specified window to fill the entire screen.===============================================================

minimizes a window to an icon.

win_min ( window );


The win_min function minimizes the specified window to an icon.

===============================================================

performs a mouse click within a window.

win_mouse_click ( window, x, y [, mouse_button ] [, modifier] );

window The logical name of the window.x, y The position of the mouse click expressed as x and y (pixel) coordinates. Coordinates are relative to the upper left corner of the client area of the window, and not to the screen.

mouse_button A constant specifying the mouse button to click. The value can be LEFT, MIDDLE, or RIGHT. If no mouse_button is specified, the default is the button performing the select function.modifier A constant specifying the modifier key used with the mouse button. The value can be CONTROL, SHIFT, or CONTROL_SHIFT. If no modifier is specified, the default is no modifier. (XRunner only)

The win_mouse_click function performs a mouse click at the coordinates inside the selected window. The mouse_button option lets you specify which mouse button to click. The modifier option allows the user to add a modifier key.===============================================================

erforms a double-click within a window.

win_mouse_dbl_click ( window, x, y [, mouse_button ] [, modifier ] );

window The logical name of the window.x, y The position of the double-click expressed as x and y (pixel) coordinates. Coordinates are relative to the upper left corner of the client area of the window, and not to the screen.mouse_button A constant specifying the mouse button to click. The value can be LEFT, MIDDLE, or RIGHT. If no mouse_button is specified, the default is the button performing the select function.modifier A constant specifying the modifier key used with the mouse button. The value can be CONTROL, SHIFT, or CONTROL_SHIFT. If no modifier is specified, the default is no modifier. (XRunner only)

The win_mouse_dbl_click function performs a mouse double-click at the coordinates inside the selected window. The mouse_button option lets you specify which mouse button to click.

===============================================================

performs a mouse drag within a window.

win_mouse_drag ( window, start_x, start_y, end_x, end_y [, mouse_button] [,modifier] );

window The logical name of the window.start_x, start_y The x, y coordinates of the start point of the mouse drag in pixels. Coordinates are relative to the upper left corner of the client area of the window, and not to the screen.end_x, end_y The x, y coordinates of the end point of the mouse drag in pixels. Coordinates are relative to the upper left corner of the client area of the window, and not to the screen.

mouse_button A constant specifying the mouse button to click (LEFT, MIDDLE, RIGHT). If no mouse_button is specified, the default is the one performing the selection.

modifier A constant specifying the modifier key used with the mouse button. The value can be CONTROL, SHIFT, or CONTROL_SHIFT. If no modifier is specified, the default is no modifier. This parameter is available for XRunner only.

The win_mouse_drag function performs a mouse drag inside a window from the start coordinates to the end coordinates. Note that the coordinates are relative to the upper left corner of the window, not the screen.

moves the mouse pointer to the designated position within a window.

win_mouse_move ( window, x, y );

window The logical name of the window.x, y The position of the mouse pointer, expressed as x and y (pixel) coordinates. The coordinates are relative to the upper left corner of the client area of the window, and not to the screen.

The win_mouse_move function moves the mouse pointer to the specified coordinates inside a window.===============================================================

moves a window to a new absolute location.

win_move ( window, x, y );

window The logical name of the window.x, y The x and y coordinates are relative to the upper left corner of the screen.The win_move function moves a window to a new absolute location.

===============================================================

moves the mouse pointer to a string in a window.

win_move_locator_text ( window, string [ ,search_area ] [ ,string_def ] );

window The logical name of the window.string The text to locate. To specify a literal, case sensitive string, enclose the string in quotation marks. Alternatively, you can specify the name of a string variable. The value of the string variable can include a regular expression (the regular expression need not begin with an exclamation mark).search_area The region of the object to search, relative to the window. This area is defined as a pair of coordinates, with x1,y1,x2,y2 specifying any two diagonally

opposite corners of the rectangular search region. If this parameter is not defined, then the entire window specified is considered the search area.

string_def Defines how the text search is performed. If no string_def is specified, (0 or FALSE, the default parameter), the interpreter searches for a complete word only. If 1, or TRUE, is specified, the search is not restricted to a single, complete word.

The win_move_locator_text function searches for a specified text string in the indicated window, or in an area of the window. It then moves the screen pointer to the center of the text string.

This function is identical to obj_move_locator_text, except that it operates on a window. For an example of how the function can be used, refer to obj_move_locator_text.

Before using win_move_locator_text, make sure that the fonts used by your AUT have been learned. This step is always required for XRunner, and may be required for WinRunner. For more information on learning fonts, refer to the “Checking Text” chapter in your User's Guide. Note that when win_move_locator_text is used with a learned font, then WinRunner searches for a single, complete word only. This means that any regular expression used in the string parameter must not contain blank spaces, and only the default value of the string_def parameter, FALSE, is in effect.

The Analog version of this function is move_locator_text.

===============================================================

opens an application window.

win_open ( window );


The win_open function opens a window in the application under test (AUT). If necessary, other windows in the application open or close in order to provide access to the specified window. The function works only if the window in the AUT is already in the GUI map.===============================================================

resizes a window.

win_resize ( window, width, height );

window The logical name of the window.width The new width of the window, in pixels.height The new height of the window, in pixels.

The win_resize function changes the size of the window.===============================================================

restores a window to its previous size.

win_restore ( window );


The win_restore function restores a window from an iconized or maximized state to its original size.===============================================================

sends keyboard input to a window.

win_type ( window, keyboard_input );

window The logical name of the window.keyboard_input A string expression that represents keystrokes.The win_type function specifies the window to which the keyboard_input is sent.===============================================================

waits for a window bitmap.

win_wait_bitmap ( window, bitmap, time [, x, y, width, height] );

window The logical name of the window.bitmap A string expression identifying the captured bitmap.time The time is added to the timeout test option to give the maximum interval between the previous input event and the screen capture (WinRunner) or XR_TIMEOUT configuration parameter (XRunner) x, y For an area bitmap: the coordinates of the upper left corner, relative to the window in which the selected region is located in pixels.

width, height For an area bitmap: the size of the selected region, in pixels.

The win_wait_bitmap function synchronizes test execution. It ensures that a window comes up on the screen and is completely redrawn before test execution continues. By using win_wait_bitmap, you can make sure that events are not input to a window before it is ready.

The win_wait_bitmap function takes three parameters when the bitmap to be waited for is an entire window bitmap. When the bitmap is of a selected area, the additional parameters, x, y, width and height define the location and dimensions of the area.


For an Analog version of the win_wait_bitmap, see wait window.

===============================================================

waits for the value of a window property.

win_wait_info ( window, property, value, time );

window The logical name of the window.property Any of the properties listed in the User's Guide. value The property value for which the function waits. time The interval, in seconds, before the next statement is executed.

The win_wait_info function waits for a window property to attain the specified value and then continues the test run. If the specified value is not attained, the function waits until the time expires before continuing the test.

Documents

Winrunner Commands (2)