MC
QAA

Subsystem
list

Top
level

Assertions

Assertions are a means of checking program correctness. Tell me more.

The Routines

void Assert (boolean bCondition, string sExplanation optional)
void AssertInRange (anytype aValue, anytype aMin, anytype aMax)
void AssertNotReached (string sExplanation optional)

void Ensure (boolean bCondition, string sExplanation optional)
void EnsureInRange (anytype aValue, anytype aMin, anytype aMax)

void Require (boolean bCondition, string sExplanation optional)
void RequireInRange (anytype aValue, anytype aMin, anytype aMax)

void RequireSetup (boolean bCondition, string sExplanation)

What's an Assertion?

Assertions are a means of checking program correctness. They are not a means of checking for user error (that's robustness, two doors down.).

Kinds of Assertions

There are three kinds of assertions: Requires, Asserts, and Ensures. They all behave the same way, but indicate a different type of programming error.

Requires

Requires are used to enforce the validity of the inputs to a routine or method. As such, they form the executable part of that routine's input specification. In the real world, where there is no time to write specs, the Requires are often part of the specification.

When a Require fails, it indicates that the caller has violated the rules of usage for the routine. In short, a Require means: the routine will make sure these things are true before any work will get done.

Use Requires to specifiy the restrictions on the inputs to a function. For example, if a function took in an unsigned integer called count that was assumed to be at least MAX_VALUE, use Require(count>=MAX_VALUE). Require is also used to validate the state of the structure/file scope/abstraction in as much as the caller has visibility to that state. For example, if there was a function, called ReadyForInput, that is visible to the caller, and a function assumed that the state was ReadyForInput, the function should have a Require(ReadyForInput()) at the top of the body. Requires should be the first executable statements of a function.

Ensures

Ensures are used to verify that the outputs of a routine or method conform to the interface specifications for that routine or method. In a pinch (i.e. reality check), the Ensures themselves serve as part of a routine's specification.

When an Ensure fails, it indicates that the routine (not the caller) is at fault, and has not kept its promises. In short, an Ensure means: The routine promises that these things will be true on exit.

Use Ensure to indicate what the state or value of the function outputs. In C, there is no language defined way to refer to the value returned by a function. A useful convention is that the variable be named "returned". In this way, an Ensure, such as Ensure(foo != 0) becomes Ensure(returned != 0), and this implies that the function will never return a 0 value.

Asserts

Asserts are used within the body of a routine to verify internal states. They have nothing to do with the interface specifications. When an Assert fails, it indicates a problem within the routine.

Use Asserts to specify what the state of the structure/file scope/abstraction should be at a given point/line in a function. For example, after searching for a menu item, it is assumed to be between 1 and the number of items in the menu, use Assert((iItem >= 1) && (iItem <= iItemCount)).

Additional Resources

The C++ Programming Language (Second Edition), Bjarne Stroustrup, Addison-Wesley Publishing Company, 1991 ISBN 0-201-53992-6 (page 419)
Object-oriented Software Construction, Bertrand Meyer, Prentice Hall, Inc., 1988, ISBN 0-13-629031-0 (chapter 7)
Assert2.h, Assert2.c, Assert2.txt in /SourceTree/core/error

Assert

Raises an exception if the argument does not evaluate to TRUE.

If Assert raises an exception, it indicates a programming error in the QAP test code, not a user error or an application error.

Assert should not be used to validate the inputs or outputs of a subroutine or method. To validate inputs, use Require. To validate outputs, use Ensure.

Declaration

void Assert (boolean bCondition, string sExplanation optional);

Inputs

bCondition: If this is not TRUE, Assert will fail by raising an exception.
sExplanation: An optional string describing the reason for the assertion. This string will be displayed if the assertion fails.

AssertInRange

Raises an exception if a given value does not fall within a given range.

If AssertInRange raises an exception, it indicates a programming error in the QAP test code, not a user error or an application error.

AssertInRange should not be used to validate the inputs or outputs of a subroutine or method. To validate inputs, use RequireInRange. To validate outputs, use EnsureInRange.

Declaration

void AssertInRange (anytype aValue, anytype aMin, anytype aMax)

Inputs

aValue: The value to be tested.
aMin: The minimum value. If aValue is less than aMin, AssertInRange raises an exception.
aMax: The maximum value. If aValue is greater than aMax, AssertInRange raises an exception.

Require

Raises an exception if the argument does not evaluate to TRUE.

If Require raises an exception, it indicates a programming error in the QAP test code, not a user error or an application error.

Require should only be used to validate the inputs to a subroutine or method. Therefore, if a call to Require fails, it indicates that whoever called the enclosing subroutine did so incorrectly.

Declaration

void Require (boolean bCondition, string sExplanation optional);

Inputs

bCondition: If this is not TRUE, Require will fail by raising an exception.
sExplanation: An optional string describing the reason for the assertion. This string will be displayed if the assertion fails.

Example of Usage

void DoSomethingWithTwoLists (list of string lsFirst, list of string lsSecond)
{
    // make sure the two lists have the same number of elements
    Require(ListItems(lsFirst) == ListItems(lsSecond), 
                                 "lists are different lengths");

    ...
}

RequireInRange

Raises an exception if a given value does not fall within a given range.

If RequireInRange raises an exception, it indicates a programming error in the QAP test code, not a user error or an application error.

RequireInRange should only be used to validate the inputs to a subroutine or method. Therefore, if a call to RequireInRange fails, it indicates that whoever called the enclosing subroutine did so incorrectly.

Declaration

void RequireInRange (anytype aValue, anytype aMin, anytype aMax)

Inputs

aValue: The value to be tested.
aMin: The minimum value. If aValue is less than aMin, RequireInRange raises an exception.
aMax: The maximum value. If aValue is greater than aMax, RequireInRange raises an exception.

Example of Usage

string GetNthCharacterInString (string sString, integer iIndex)
{
    RequireInRange(iIndex, 1, Length(sString));

    ...
}

Ensure

Raises an exception if the argument does not evaluate to TRUE.

If Ensure raises an exception, it indicates a programming error in the QAP test code, not a user error or an application error.

Ensure should only be used to validate the outputs of a subroutine or method. Therefore, if a call to Ensure fails, it indicates that the subroutine in which the Ensure appears has a bug.

Declaration

void Ensure (boolean bCondition, string sExplanation optional);

Inputs

bCondition: If this is not TRUE, Ensure will fail by raising an exception.
sExplanation: An optional string describing the reason for the assertion. This string will be displayed if the assertion fails.

Example of Usage

string MangleString (string sString)
{
    string sReturn;

    ...  

    // make sure the string isn't empty
    Ensure(Length(sReturn) > 0, "string is empty");
}

EnsureInRange

Raises an exception if a given value does not fall within a given range.

If EnsureInRange raises an exception, it indicates a programming error in the QAP test code, not a user error or an application error.

EnsureInRange should only be used to validate the outputs of a subroutine or method. Therefore, if a call to EnsureInRange fails, it indicates that the subroutine in which the EnsureInRange appears has a bug.

Declaration

void EnsureInRange (anytype aValue, anytype aMin, anytype aMax)

Inputs

aValue: The value to be tested.
aMin: The minimum value. If aValue is less than aMin, EnsureInRange raises an exception.
aMax: The maximum value. If aValue is greater than aMax, EnsureInRange raises an exception.

Example of Usage

integer FindStringInList (string sString, list of string lsList)
{
    integer i, n;

    n = ListSize(lsList);

    for (i = 1; i < n; i++)
    {
        if (sString == lsList[i])
        {
            EnsureInRange(i, 1, n);
            return i;
        }
    }

    raise 1, "string not found in list";
}

AssertNotReached

This routine unconditionally raises an exception.

Use AssertNotReached at points in your code that should never be executed, such as dangling "else" clauses or Default clauses in switch statements.

The execution of AssertNotReached (and the resulting exception) indicates a programming error in the test code, not a user error or an application error.

Declaration

void AssertNotReached (string sExplanation optional);

Inputs

sExplanation: An optional string describing the reason for the assertion. This string will be displayed when the routine executes.

Example of Usage

void DoSomething (COLOR uColor)
{
    switch (uColor)
    {
        case eCOLOR_RED:    DoSomethingWithRed();    break;
        case eCOLOR_GREEN:  DoSomethingWithGreen();  break;
        case eCOLOR_BLUE:   DoSomethingWithBlue();   break;
        case eCOLOR_YELLOW: DoSomethingWithYellow(); break;
        default: AssertNotReached();
    }
}

RequireSetup

Raises an exception if the argument does not evaluate to TRUE. When the exception is displayed in the results file, it will say something like "Script Setup Error" to indicate that the person executing the test script did not properly set up the system so that the test could run.

This routine should only be used to validate script setup, such as making sure test data is provided, the proper hardware is installed, or the contents of MClocal.inc are correct. It is different from other assertions in that it indicates an error made by the user of the script, rather than the script writer.

Declaration

void RequireSetup (boolean bCondition, string sExplanation);

Inputs

bCondition: If this is not TRUE, RequireSetup will fail by raising an exception.
sExplanation: A string describing the reason for the assertion. This string will be displayed if the condition is not met.

This page maintained by (REMOVED).

Last updated 20 February 1998.