Defining Compound Recovery Scenarios - WinRunner

A compound recovery scenario defines a crash or exception event and the operation(s) required to continue or restart the test and the associated applications. You define and modify compound recovery scenarios from the Compound tab of the Recovery Manager. The Recovery wizard guides you through the process of creating and modifying your scenario.

To create a compound recovery scenario

1. Choose Tools > Recovery Manager. The Recovery Manager opens.
2. Click the Compound tab.


3. Click New. The Recovery wizard opens to the Select Exception Event Type screen.




4. Select the exception event type that triggers the recovery mechanism.
   • Object event: a change in the property value of an object that causes an interruption in the WinRunner test.

For example, suppose that your application uses a green button to indicate that an electrical network is closed; the same button may turn red when the network is broken. Your test cannot continue while the network is broken.

• Popup event: a window that pops up during the test run and interrupts the test.

For example, suppose part of your test includes clicking on a Print button to send a generated graph to the printer, and a message box opens indicating that the printer is out of paper. Your test cannot continue until you close the message box.

• TSL event: a TSL return value that can cause an interruption in the test run.
• Crash event: an unexpected failure of an application during the test run.
  

Click Next.

• The Scenario Name screen opens.




Enter a name containing only alphanumeric characters and underscores (no spaces or special characters) and a description for your recovery scenario.

Click Next.

5. If you chose an object, pop-up or TSL event in step 4, the Define Exception Event screen opens. The options for defining the event vary based on the type of event you selected.

If you chose a crash event in step 4, there is no need to define the event.

Proceed to step 7

If you chose an object event in step 4, enter the following information:




• Window name: Indicates the name of the window containing the object that causes the exception. Enter the logical name of the window, or use the pointing hand next to the Object name box to click on the object you want to define for the object exception and WinRunner will automatically fill in the Window name and Object name.

If you want to define a window as the exception object, click on the window’s title bar, or enter the window’s logical name and leave the Object name box empty.

• Object name: Indicates the name of the object that causes the exception. Enter the logical name of the object, or use the pointing hand next to the Object name box to specify the object you want to define for the object exception and WinRunner will automatically fill in the Window name and Object name.
  
• Object property: The object property whose value you want to check. Select the object property in which an exception may occur. For example, if want to detect when a button changes from enabled to disabled, select the enabled property.
  
• Property value: The value that indicates that an exception has occurred. For example, if you want WinRunner to activate the recovery scenario when the button changes from enabled to disabled, type 0 in the field.
  

Click Next and proceed to step 7

If you chose a pop-up event in step 4, enter the following information:

• Window name: Indicates the name of the pop-up window that causes the exception. Enter the logical name of the window, or use the pointing hand to specify the window you want to define as a pop-up exception.

If the window is not already saved in the GUI Map and you use the pointing hand to identify the window, WinRunner automatically adds it to the active GUI Map. If the window is not already saved in the GUI Map and you type the name manually, WinRunner identifies the pop-up exception when a pop-up window opens with a title bar matching the name you entered.


Click Next and proceed to step 7

If you chose a TSL event in step 4, enter the following information:

• TSL function: Select the TSL function for which you want to define the exception event. Select a TSL function from the list. WinRunner detects the exception only when the selected TSL function returns the code selected in the Error code box.
  
• Error code: Select the TSL error code that triggers the exception mechanism. Select an error code from the list. WinRunner activates the recovery scenario when this return code is detected for the selected TSL function during a test run.

Click Next.

The Define Recovery Operations screen opens and displays the recovery operations WinRunner can perform when the exception occurs. Note that WinRunner performs the recovery operations you select according to the order displayed in the dialog box. Select any of the following options:

• Click button: Specifies the logical name of the button to click when the exception event occurs. Select one of the default button names, type the logical name of a button, or use the pointing hand to specify the button to click.
  
• Close active window: Instructs WinRunner to close the active (in focus) window when the exception event occurs.
  
• Execute a recovery function: Instructs WinRunner to run the specified function when the exception event occurs. You can specify an existing function or click Define recovery function to define a new function.
  
• Close processes: Instructs WinRunner to close the application processes that you specify in the Close Application Processes screen.
• Reboot the computer: Instructs WinRunner to reboot the computer before performing the post-recovery operations.

If you select Reboot the computer, consider the following:

• The reboot option is performed only after all other selected recovery actions have been performed.
• In order to assure a smooth reboot process, it is recommended to use the Execute a recovery function option and add statements to your function that save any unsaved files before the reboot. You should also confirm that your computer is set to login automatically.
  
• If you choose the reboot option, you cannot set post-recovery operations.
• Before WinRunner reboots the computer during a recovery scenario, you get a timed warning message that gives you a chance to cancel the reboot operation.
• If the reboot operation is performed, WinRunner starts running the test from the beginning of the test, or from the beginning of the call chain if the test that caused the exception was called by another test. For example, if test A calls test B, test B calls test C, and a recovery scenario including a reboot recovery operation is triggered when test C runs, WinRunner begins running test A from the beginning after the reboot is performed.
• If you choose to cancel the reboot operation, WinRunner attempts to continue the test from the point that the exception occurred.
• If you opened WinRunner using command line options before the reboot occurred, WinRunner applies the same command line options when it opens after the reboot operation, except for: -t, -exp, and -verify. Instead, WinRunner uses the test, expected values and results folder for the test it runs after the reboot.
  

Click Next.

If you selected Close processes, proceed to step 8.

If you did not select Close processes or Reboot the computer, proceed to step 9.

If you selected Reboot the computer, but not Close processes, proceed to step 10.

6. The Close Application Processes screen opens.



Specify the application processes that you want WinRunner to close when the exception event occurs. When WinRunner runs the recovery scenario, it ignores listed application processes that are already closed (no error occurs).

To add an application to the list, double-click the next blank space on the list and type or browse to enter the application name, or click Select Process to open the Processes list. The Processes list contains a list of processes that are currently running.




To add a process from this list to the Close Application Processes list, select the process and click OK.


Click Next. If you selected Reboot the computer in the previous step, proceed to step 10. Otherwise, proceed to step 9.

7. The Post-Recovery Operations screen opens.

Choose from the following options:

• Execute function: Instructs WinRunner to run the specified function when the recovery operations are complete. You can specify an existing function or click Define new function to define a new function. For more information on defining post-recovery functions, see “Defining Recovery Scenario Functions”
  

The post-recovery function can be useful for reopening applications that were closed during the recovery process and/or setting applications to the desired state.

• Execution point: Instructs WinRunner on how to proceed after the recovery operation(s) and the post-recovery function (if applicable) have been performed. Choose one of the following:
• Continue test run from current position: WinRunner continues to run the current test from the location at which the exception occurred.
• Restart test run: WinRunner runs the current test again from the beginning.
• Stop current test (run next test in batch if applicable): WinRunner stops the current test run. If the test where the exception event occurred was called from a batch test, WinRunner continues running the batch test from the next line in the test.
• Stop all test execution: WinRunner stops the test (and batch) run.

Click Next.

8. The Finished screen opens.

Determine whether you want your recovery scenario to be activated by default when WinRunner opens:
• Select Activate by default to instruct WinRunner to automatically activate the recovery scenario by default when WinRunner opens, even if the scenario was set as inactive at the end of the previous WinRunner session.

• Clear Activate by default if you do not want WinRunner to automatically activate the recovery scenario by default when WinRunner opens. Note that if you clear this check box, your recovery scenario will not be activated unless you activate it manually by toggling the check box in the Recovery Manager dialog box.

Click Finish. The recovery scenario is added to the Compound tab of the Recovery Manager dialog box. If you selected Activate by default (and any required objects are found in the loaded GUI map file(s)), the recovery scenario is activated. Otherwise the recovery scenario remains inactive.

Defining Recovery Scenario Functions

You can define recovery functions that instruct WinRunner to respond to an exception event in a way that meets your specific testing needs. You can also define post-recovery functions for compound recovery scenarios. These functions can be useful to re-open applications that may have closed when the exception occurred or during the recovery process, and to set applications to the desired state.

You use the Recovery Function or Post-Recovery Function dialog box that opens from the Recovery wizard to define new recovery and post-recovery functions. The dialog box displays the syntax and a function prototype for the selected exception type.

Once you have defined a recovery function, you can save it in the recovery compiled module, paste it into the current test, or copy it to the clipboard.

To define a recovery or post-recovery function:

1. Click Define recovery function from the Define Recovery Operations screen, or click Define new function from the Define Post-Recovery Operations screen. The Define Recovery (or Post-Recovery) Function screen opens.



2. The first three lines display the function type (always public function), the function name and the function arguments. Replace the text: func_name with the name of your new function.
3. In the implementation box, enter the function content.
4. Choose how you want to store the function:
   • Copy to clipboard: copies the function to the clipboard.
   • Paste to current test: pastes the function at the cursor position of the current test.
   • Save in the recovery compiled module: saves the function in the recovery compiled module.
5. Click OK to return to the Recovery wizard.