Deriving from CTestStep

Test servers contain one or more test steps derived from CTestStep.

A test step implementation is split into preamble, main code and postamble stages, executed in that order. A test step is created by deriving (from CTestStep) a test step class which implements the pure virtual function doTestStepL() and, optionally, overrides the doTestStepPreamble() and doTestStepPostamble() virtual functions. The CTestServer base class code calls these virtual functions to execute the test step.

The doTestStepPreamble() and doTestStepPostamble() functions can be used for implementing any setup and operations such as allocating and freeing memory for objects that will be used for the test step execution.

The conventional way to do this is to provide a definition file for one or more test steps in a header file xxxStep.h and an implementation in xxxStep.cpp.

An example test step definition file is as follows:

class CSampleStep1 : public CTestStep
    {
public:
    CSampleStep1();
    ~CSampleStep1();
    virtual TVerdict doTestStepPreambleL(); // virtual
    virtual TVerdict doTestStepL(); // Pure virtual
    virtual TVerdict doTestStepPostambleL(); // virtual
private:
    };
// String for the server create test step code
_LIT(KSampleStep1,"SampleStep1");

Test result values

The overall result of the test step is picked up by the test server base class when it reads the CTestStep base class iTestStepResult member. The last call to SetTestStepResult() determines the result of the test step. SetTestStepResult() is an API provided by the base class CTestStep and is used for setting the result values for each test step to one of the Tverdict values. The return value is left in for compatibility with ScheduleTest. If a test step leaves or panics, the test step thread exits and continues to execute the next script line.

Notes:

  • CTestStep is derived from CBase therefore, iTestStepResult will be initialised to 0 (EPass).

  • The test step result can be set to one of the Result Codes.

Test error values

Test error values are used to check whether APIs return the correct error codes by specifying the expected error code. An error value returned by an API can be set by a test step. This error value is stored in the CTestStep member variable iTestStepError. To set the error value in the iTestStepError variable, SetTestStepError() must be called from the test step. You can retrieve the error value set using TestStepError(). This error value is used only when the !Error parameter is used in the RUN_TEST_STEP command. TEF compares the expected value specified for the !Error parameter with the actual value set by SetTestStepError() to determine the test result.

Note: CTestStep is derived from CBase therefore iTestStepError will be initialised to zero (KErrNone). If SetTestStepError() is called with a negative value, iTestStepResult will automatically be set to EFail.

The following example test step implementation shows how to set an error:

TVerdict CSampleStep1::doTestStepL()
    {

        TRAP(err, openFileL()); // Consider that err returned is -1 (file not found)
        //and openFileL() is a function call to open a file.

  SetTestStepError(err);
    
    return TestStepResult();
    }

This step can be called from a script RUN_TEST_STEP command as illustrated in the following code:

RUN_TEST_STEP !Error=-1 100 SampleServer SampleStep1 c:\sample\sample.ini SectionOne

In this command, the expected error is set to -1. The test harness must be trapped for the particular step execution, and the SetTestStepError() function must be used to set the trapped error. If the actual error trapped, and the expected error provided in the script line are the same, then the step result is set to Pass, otherwise it will be logged as a Fail.

Logging MACROs

The following three logging MACROs are provided for use within a test step:

  • INFO_PRINTF

  • WARN_PRINTF

  • ERR_PRINTF

Important: These logging MACROs can be used only after the initialisation of a test step.

Each MACRO has seven variants for different number of parameters. They behave similar to printf using multiple argument lists. The output is logged to the HTML/XML log files.

The following example code describes the process of logging MACROs:

TInt    theInt = 100;

_LIT( KParamString, "Int = %d" );

// Information Logging
INFO_PRINTF2( KParamString, theInt);

// Warning Logging
WARN_PRINTF2( KParamString, theInt);

// Error Logging
ERR_PRINTF2( KParamString, theInt);