QAA
API

Subsystem
list

Top
level

The Recovery System

If you are unfamiliar with the Recovery System, you should first read the Introduction.

Classes

(Indentation shows inheritance heirarchy.)

RECbase - abstract base class for all recovery objects RECchildWin - simple recovery for QChildWin RECgroup - recovery object that contains other recovery objects RECapplication - recovery object for an application RECunwantedWindows - recovery object that closes unwanted windows RECquitOnError - recovery object that terminates the script on errors

Data Types

`RECobject`	recovery object type, for defining variables & arguments
`RECphase`	recovery phase (TestcaseEnter, ScriptExit, etc.)
`RECwindowUid`	unique window identifier

Routines

`RECobject`	`RECsetActive`	`(RECobject)`
`RECobject`	`RECgetActive`	`( )`
`void`	`RECstubTestcase`	`(string sExplanation)`
`void`	`RECstubNextTestcase`	`(string sExplanation)`
`void`	`RECquitOnTestcaseFailure`	`(boolean bQuitOnFailure)`

Variables

RECobject grRECinitial;

RECobject

Use this data type to declare variables and arguments which are recovery objects.

RECphase

This enumeration identifies the recovery phase.

type RECphase is enum 
{ eREC_SCRIPT_ENTER, eREC_TESTCASE_ENTER, eREC_TESTCASE_EXIT, eREC_SCRIPT_EXIT };

RECwindowUid

A value of this data type uniquely identifies an application window. Two different 4Test declarations for the same window will always have the same RECwindowUid value.

If you need or want to know why this data type is necessary, look here.

RECsetActive

This routine sets the currently active recovery object; that is, the one that will actually be used during the four recovery phases.

Only one recovery object can be active at a time. Typically, the currently active recovery object will be of class RECgroup, so that, in effect, many recovery objects can be active at once.

You should specify the initial active recovery object (for use during ScriptEnter) by defining grRECinitial.

Declaration

RECobject RECsetActive (RECobject uNewRecObj);

Inputs

uNewRecObj: The new active recovery object, or NULL for none.

Outputs

Returns: The previous active recovery object, or NULL if there wasn't one.

RECgetActive

This routine returns the currently active recovery object; that is, the one that is actually being used during the four recovery phases.

Declaration

RECobject RECgetActive ( );

Inputs

(none)

Outputs

Returns: The currently active recovery object, or NULL if there isn't one.

RECstubTestcase

Sometimes it's necessary to temporarily stub out a testcase that causes catastrophic failure, so that the rest of a test script or suite can execute. If you need to stub out a testcase, call this routine at the top of the testcase. This will stub out all invocations of the testcase. If you want to stub out one or more (but not all) invocations of a testcase, use RECstubNextTestcase instead.

This routine raises an exception, which results in the testcase failing, without executing the rest of the testcase.

Declaration

void RECstubTestcase (string sExplanation);

Inputs

sExplanation: A description of why the testcase is stubbed out. Include a bug number if possible.

Outputs

(none)

Example of Usage

testcase MyDeadlyTestcase ()
{
    RECstubTestcase();  // so we don't lose more executioners

    // the body of the testcase
}

RECstubNextTestcase

Sometimes it's necessary to temporarily stub out a testcase that causes catastrophic failure, so that the rest of a test script or suite can execute. If you need to stub out an invocation of a testcase, call this routine immediately before calling the testcase. It will cause the testcase to fail without actually executing the body of the testcase. If you need to stub out all invocations of a testcase, use RECstubTestcase instead.

Declaration

void RECstubNextTestcase (string sExplanation);

Inputs

sExplanation: A description of why the testcase is stubbed out. Include a bug number if possible.

Outputs

(none)

Example of Usage

// In this example, the second testcase will not be executed, but the others will.
main ()
{
    // do setup
    tcMyFirstTestcase();

    RECstubNextTestcase();  // because it causes the drive to melt down
    tcMySecondTestcase();

    tcMyThirdTestcase();
}

RECquitOnTestcaseFailure

In some tests such as workflow tests, each testcase assumes that the preceding testcases completed successfully. In such a test, it doesn't make sense to continue once an error occurs, as the likelihood of secondary errors approaches certainty. You can use this routine to tell the recovery system to terminate the script after the first failed testcase.

Declaration

void RECquitOnTestcaseFailure (boolean bQuit);

Inputs

bQuit: If TRUE, the next testcase that fails will terminate the script.
If FALSE, testcase failures will not automatically terminate the script.

Outputs

(none)

grRECinitial

This global variable specifies the initial active recovery object; that is, the one that will be used during ScriptEnter, as well as afterward (unless changed by a call to RECsetActive). You (the script writer) must define this global variable somewhere in your script. If you don't, then no recovery object will be active during ScriptEnter, nor for any testcases, until one is specified by a call to RECsetActive.

Changing the value of this variable after ScriptEnter has run will have no effect. To change the active recovery object at runtime, use RECsetActive.

Example of Usage

RECobject grRECinitial = grMCrecDefault;

main ()
{
    // blah, blah ...
}

Miscellaneous Notes

ForgeLicenseAgreement will no longer be handled by the recovery system. The script user will be expected to take care of this when a build is first installed. If necessary, we can produce a separate QAP script to forge the license agreement.

This page is maintained by (REMOVED).
Last updated 3 March 1999.