Test Pragmas

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: 
    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 is 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:
  // 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