The Recovery System: Introduction and Overview

This page provides an introduction to the Recovery System provided by the Test Automation core team. It is based on QA Partner's built-in recovery system, and provides automatic recovery from errors that occur during the execution of a test script.

Introduction
How QA Partner's Recovery System Works
Defining Recovery Behaviour
How to Use Recovery Objects
Defining Testcases
What Actually Happens During Recovery

Introduction

The purpose of a recovery system is to provide automatic recovery from certain types of application errors. The name should really be "Error Recovery System", but for mainly historical reasons we call it simply "Recovery System". The recovery ststem relieves the script writer from the burden of having to explicitly handle every possible type of failure. It also provides the ability to continue the execution of a script after a testcase fails, even if it fails catastrophically.

In general terms, a recovery system should do the following:

Start the application if the application is not already running.
Perform necessary initializations that must occur before other test code can be run.
Make sure that certain windows are open, and unneeded windows are closed.
Restore certain windows to a known "base state".
Dismisses any error dialogs which may be left open at the end of a testcase.

How QA Partner's Recovery System works

The recovery system works by defining the following special QA Partner functions:

ScriptEnter() is called at the beginning of each test script.
ScriptExit() is called at the end of each test script.
TestCaseEnter() is called at the beginning of each testcase.
TestCaseExit() is called at the end of each testcase.

These functions are provided for you; a test script should never redefine them.

Note that all of these functions are called automatically, behind your back. You do not need to -- in fact, you must not -- call them explicitly in your code. Note also that TestCaseExit is called regardless of whether the testcase exited normally or because an exception was raised. Likewise, ScriptExit is called regardless of whether the script exited normally or because an exception was raised.

Defining Recovery Behaviour

Recovery behaviour (what happens during recovery) is defined by Recovery Objects that derive from the base class RECbase. Each recovery object is responsible for ensuring that a well-defined part of the system is in a known state, called the "base state", which the script expects the system to be in. The part of the system for which a recovery object is responsible is called the "recovery target". Most recovery targets are windows; each window in the application under test will typically have its own recovery object. In addition, there will usually be a recovery object for the entire application under test, usually derived from RECapplication.

The documentation for the recovery object classes is primarily focussed on how to override them to create new recovery classes. Script writers will often create new recovery classes and objects, but will typically not invoke recovery objects very much.

How to Use Recovery Objects

In your script, you must specify what recovery object(s) are to be used. The mere existence of a recovery object does not imply that it will have any effect during script execution.

The recovery system keeps track of a single recovery object, known as the "active recovery object", which is used during the four recovery phases (ScriptEnter, TestcaseEnter, TestcaseExit, and ScriptExit). You can change the active recovery object at any time by calling RECsetActive.

While there can be only one active recovery object at a time, it will typically be derived from the RECgroup class, which contains other recovery objects. Therefore, you can effectively have as many active recovery objects as you need.

There is one special case for defining the active recovery object: since ScriptEnter is called before main, you must specify the initial recovery object by defining grRECinitial.

How Recovery Objects are Called

While the script writer is responsible for defining which recovery objects are to be used, the script will typically never explicitly invoke a recovery object. This happens automatically during the four recovery phases. For more information, see RECbase.

Defining Testcases

The recovery system requires that all testcases conform to certain specifications:

Near the top of the body of the testcase, there must be a call to CUtestcaseFeature that specifies the functional area that the testcase is testing. This requirement is enforced at run time.

CUbeginFeatureTest and CUendFeatureTest may be called outside a testcase to partially specify a feature, in which case the CUfeature passed to the testcase is relative to the current feature block.

CUbeginFeatureTest and CUendFeatureTest may not be called from inside a testcase. There must be a one-to-one correspondence between testcases and testpoints. This requirement is enforced at run time.

If the testcase takes parameters, then it must log information that distinguishes between different invocations of the testcase. This is accomplished by placing a call to CUdisambiguateTC near the top of the body of the testcase.

At some appropriate point inside the testcase, it must set the test phase to eCU_TEST_EXECUTE by calling CUlogTestPhase. This should happen after the testcase performs any setup (if any), immediately before it begins the "real" part of the test. If the testcase performs explicit cleanup or verification, it must set the test phase to eCU_TEST_CLEANUP and/or eCU_TEST_VERIFY. Testcases may modify the currently active recovery object, but this practice should be avoided.

What Actually Happens During Recovery

This section describes in detail what happens during each of the four recovery phases. Some of what happens is not directly related to error recovery, but is handled here because it's the best place to do it.

ScriptEnter

Print the name of the script and the name of its documentation file.
Read script parameters and log them to the results file.
Seed the random number generator.
Call grRECinitial.BeHappy(eREC_SCRIPT_ENTER). If it fails, terminate the script.
Keep track of how much time is spent in the recovery system.
TestcaseEnter
1. Make sure first argument is a CUfeature, push it onto the feature stack, and set the test phase to Setup.
2. Handle RECstubNextTestcase.
3. Call RECgetActive().IsHappy(eREC_TESTCASE_ENTER, TRUE).
4. If IsHappy returns FALSE, call RECgetActive().BeHappy(eREC_TESTCASE_ENTER). If BeHappy fails, terminate the script.
5. Call the current AppState (a QA Partner feature that we don't use much, if at all).
6. Remember the current log block state.
7. Keep track of how much time is spent in the recovery system.
  TestcaseExit
  1. Log exception, if any, including a screen shot if requested.
  2. If testcase was successful (so far), make sure there was an Execute phase.
  3. If an exception was raised, restore the log block state.
  4. If the current test phase is not Cleanup, set it to Verify.
  5. Call RECgetActive().IsHappy(eREC_TESTCASE_EXIT). If the testcase was (so far) successful, pass TRUE for logFirstFailure; otherwise pass FALSE.
  6. If IsHappy returns FALSE, call RECgetActive().BeHappy(eREC_TESTCASE_EXIT). If BeHappy fails, terminate the script.
  7. Pop the feature off the feature stack.
  8. Keep track of how much time is spent in the recovery system.
    ScriptExit
    1. Log exception, if any, including a screen shot if requested.
    2. Call RECgetActive().BeHappy(eREC_SCRIPT_EXIT).
    3. Report unused script parameters.
    4. Keep track of how much time is spent in the recovery system.
      
      This page is maintained by (REMOVED).
      Last updated 19 February 1999.