Test Pragmas

From STRIDE Wiki
Jump to: navigation, search

Test Unit pragmas are a set of compiler directives that allow annotations within C and C++ source files that are meaningful to the Stride Build Tools but ignored by standard C/C++ compilers. During the build process the Build Tools generates an Intercept Module that provides harnessing for the tests. Refer to the following header file that contains the scl_test_class pragma.

Header file

#include <srtest.h>
 
class MyTest : public stride::srTest {
public: 
    void CheckFoo();
    void CheckBoo();
};
#pragma scl_test_class(MyTest)


scl_test_class

The scl_test_class pragma is used to declare a C++ class as a Test Unit.

Syntax

#pragma scl_test_class(class-name)
Parameters Type Description
class-name Identifier The name of the test unit. This must be the name of an existing C++ class or a struct.

Notes

  • This pragma requires the compilation language to be C++. If the compilation language is not C++ and this pragma is encountered, then an error is issued and this pragma is ignored.
  • The test class identified:
    • must have single public constructor - default or explicit.
    • must not be a templated class
    • must not be a nested class
    • must not be a pure virtual class
    • must have one or more member functions that is suitable as a test method. For a member function to be a test method it:
      • must be declared within the test class (a method that is inherited from a base class cannot be a test method)
      • must be declared with public access
      • must have a return type of bool, an integral type (signed or unsigned long, int, short, char) or void.
      • must have an empty parameter list - declared as f() or f(void).
      • must not be a templatized function
      • must not be an overloaded operator
      • must not be a static member.
  • Optionally if desired a set of setup/teardown fixtures could be applied.
  • Optionally if desired the public constructor may have arguments (they must all be of C-string and numeric types).

Examples

#include <srtest.h>
 
class MyOtherTest : public stride::srTest
{
public:
  // Declaring a constructor for an scl_test_class is optional, but
  // if a constructor is declared all arguments must be of plain old data (POD) type.
  MyOtherTest(int i, const char* s);
 
  void CheckItOut();
};
#ifdef _SCL    
#pragma scl_test_class(MyOtherTest)
#endif


scl_test_cclass

The scl_test_cclass pragma is used to declare a "C" language struct (class) to be captured as a Test Unit.

Syntax

#pragma scl_test_cclass(cclass-name, init-function-name { , deinit-function-name })
Parameters Type Description
cclass-name Identifier The name of the test unit. This is must be the name of an existing struct in C/C++ or a class in C++.
init-function-name Identifier The initialization function name. This is synonymous with a class constructor. There must be a prior user-declared function with this name. The first parameter must be a pointer to cclass-name. Additional parameters are left up to the user's implementation.
deinit-function-name (optional) Identifier The deinitialization function name. This is synonymous with a class destructor. If declared, there must be a user-declared function with this name. The first parameter must be a pointer to cclass-name. Additional parameters are left up to the user's implementation.

Notes

  • The cclass-name identified:
    • may not appear as a specifier of a prior pragma.
    • must be a struct in C.
    • must be either a struct or class in C++.
    • must be POD type.
    • must not be a template class.
    • must not be a nested class.
    • must contain at least one member function pointer with a prototype that:
      • returns integral type: void, int, or bool (bool accepted only for C++).
      • has a first parameter that is a pointer to cclass-name.
  • The init-function-name identified:
    • must be declared prior to this pragma's declaration.
    • must not have been used in any prior or subsequent SCL pragma.
    • must have its first parameter declared as a pointer to the identified cclass.
    • optionally if desired it may have additional parameters (they must all be of C-string and numeric types).
  • The deinit-function-name:
    • is optional.
    • must be declared prior to this pragma's declaration if it appears in pragma.
    • must not have been used in any prior or subsequent SCL pragma.
    • must have its first parameter declared as a pointer to the identified class.
  • Optionally if desired a set of setup/teardown fixtures could be applied.

Examples

#include <srtest.h>
 
typedef struct CClass_Basic_Simple {
  int   (*pf_TestMethod)(struct CClass_Basic_Simple* pcc);
} CClass_Basic_Simple;
 
#ifdef __cplusplus
extern "C" {
#endif
void CClass_Basic_Simple_init(struct CClass_Basic_Simple* pcc);
#ifdef __cplusplus
}
#endif
 
#ifdef _SCL
#pragma scl_test_cclass(CClass_Basic_Simple, CClass_Basic_Simple_init)
#endif


scl_test_flist

The scl_test_flist pragma is used to declare a list of external functions as a Test Unit.

Syntax

#pragma scl_test_flist(test-unit-name, function-1, function-2..n)
Parameters Type Description
test-unit-name String The name of the test unit. A special identifier with that name will be synthesized into which the list of external functions will be assembled.

Note: this string may not contain a space.

function-1 Identifier Name of the first external function to be captured.
function-2..n [Optional] Identifier Optional names of second and subsequent external functions to be captured.

Notes

  • The external functions must meet the following conditions:
    • Their parameter lists must be empty (void).
    • They cannot be overloaded.
    • They cannot be overloaded operators.
    • They may not be template functions.
    • They may throw exceptions when compiled in CPP mode.
    • They cannot have been previously captured with the scl_function pragram or the scl_test_flist pragma.
    • They cannot be public static class methods.
    • They must return a pass/fail result. The return type may be declared void or an integer type (bool is acceptable in C++ mode). If void is the return type, any calls to the test function default to successful.
  • Once an external function has been captured with scl_test_flist, that function may not then be captured again with the scl_function pragma, or the scl_test_flist pragma, or used with any other qualification pragmas.
  • Use of this pragma requires an include of srtest.h.
  • The test-unit-name may not have been specified with a prior scl_test_flist pragma.
  • The test-unit-name may not be the name of an existing routine.
  • Optionally if desired a set of setup/teardown fixtures could be applied.

Examples

#include <srtest.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
int test1();
int test2();
 
#ifdef __cplusplus
}
#endif
 
#ifdef _SCL
#pragma scl_test_flist("Foo", test1, test2)
#endif


scl_test_setup

The scl_test_setup pragma declares a member method to be a setup fixture for an existing Test Unit. The setup method will be called before the execution of each test method.

Syntax

#pragma scl_test_setup(test-unit-name, function-name)
Parameters Type Description
test-unit-name Identifier Name of a captured test unit.
function-name Identifier Name of a member function of the test unit to be used as a setup fixture.

Notes

  • This pragma identifies the setup fixture of an existing test unit, i.e. either a class with scl_test_class applied to it, a set of functions with scl_test_flist applied to it, or a C struct with scl_test_cclass applied to it.
  • There may be only one setup fixture per test unit.

Example

#include <srtest.h>
 
class MyTest {
public:
  void FooSetup();
  void CheckFoo();
};
 
#ifdef _SCL
#pragma scl_test_class(MyTest)
#pragma scl_test_setup(MyTest, FooSetup)
#endif


scl_test_teardown

The scl_test_teardown pragma declares a member method to be a teardown fixture for an existing Test Unit. The teardown method will be called after the execution of each test method.

Syntax

#pragma scl_test_teardown(test-unit-name, function-name)
Parameters Type Description
test-unit-name Identifier Name of a captured test unit.
function-name Identifier Name of a member function of the test unit to be used as a teardown fixture.

Notes

  • This pragma identifies the setup fixture of an existing test unit, i.e. either a class with scl_test_class applied to it, a set of functions with scl_test_flist applied to it, or a C struct with scl_test_cclass applied to it.
  • There may be only one teardown fixture per test unit.

Example

class MyTest {
public:
  void FooSetup();
  void FooTeardown();
  void CheckFoo();
};
 
#ifdef _SCL
#pragma scl_test_class(MyTest)
#pragma scl_test_setup(MyTest, FooSetup)
#pragma scl_test_teardown(MyTest, FooTeardown)
#endif