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);