Defines, Structures, Typedefs, Functions. More...

Files
file	clTcUtilsApi.h
	Header file for ASP Test Lifecycle Control (TLC) APIs.
file	clTestApi.h
	OpenClovis Test Infrastructure.

Classes
struct	ClTcParamListT
	List to store all the parsed runtime configuration paramaters, by TLC. More...
struct	ClTcParamT
	Basic structure to store the parsed runtime configuration paramater, by TLC. More...
union	ClTcParamValU
	Union to store parsed runtime configuration paramater value, by TLC. More...

Macros
#define	clTest(string, predicate, errorPrintf)
	Run an individual test.
#define	clTestCase(name, test)
	Run a test case.
#define	clTestCaseEnd(synopsis)
	Stop this test case.
#define	clTestCaseMalfunction(reason, predicate, execOnFailure)
	Indicate that this test case cannot be completed, if the predicate fails.
#define	clTestCaseNumErrors() clCurTc.failed
	Returns the number of errored (failed) tests run so far in this test case.
#define	clTestCaseNumMalfunctions() clCurTc.malfunction
	Return the number of malfunctioned tests in this test case (so far).
#define	clTestCaseNumPasses() clCurTc.passed
	Return the number of successful (passed) test run so far in this test case.
#define	clTestCaseStart(testname)
	Start a Test Case.
#define	clTestExecOnFailure(string, predicate, errorPrintf, execOnFailure)
	Run an individual test, and run some special code if it fails.
#define	clTestFailed(__string) clTestFailedAt(__FILE__, __LINE__,__string)
	Indicate that a test failed.
#define	clTestFailedAt(__file, __line, __string)
	Just like clTestFailed, but allows the caller to specify the file and line.
#define	clTestGroupFinalize() clTestGroupFinalizeImpl()
	Stop the Test infrastructure.
#define	clTestGroupInitialize(name) clTestPrint(name)
	Start up the Test infrastructure.
#define	clTestGroupMalfunction(reason, predicate, execOnFailure)
	Indicate that the Test Group cannot execute, if an expression evaluates to False.
#define	clTestPrint(x) clTestPrintAt(__FILE__, __LINE__, __FUNCTION__, x)
	Print something to the test console.
#define	clTestPrintAt(__file, __line, __function, x)
	Just like clTestPrint, but allows the caller to specify the file and line.
#define	clTestSuccess(__string) clTestSuccessAt(__FILE__, __LINE__, __string)
	Indicate that a test passed.
#define	clTestSuccessAt(__file, __line, __string)
	Just like clTestSuccess, but allows the caller to specify the file and line.
#define	TC_MAX_STR_LENGTH 256
	Default size of all strings used within the TLC infrastructure.

Typedefs
typedef struct ClTcParamListT	ClTcParamListT
	List to store all the parsed runtime configuration paramaters, by TLC.
typedef struct ClTcParamT	ClTcParamT
	Basic structure to store the parsed runtime configuration paramater, by TLC.
typedef enum ClTcParamTypeE	ClTcParamTypeE
	Current paramater types supported by TLC.
typedef union ClTcParamValU	ClTcParamValU
	Union to store parsed runtime configuration paramater value, by TLC.

Enumerations
enum	ClTcParamTypeE
	Current paramater types supported by TLC. More...

Functions
int	clTcActivate (ClAmsCSIDescriptorT *csi_desc, ClAmsHAStateT ha_state)
	API called to start the test case registered by the user in clTcInitialze.
void	clTcFinalize (void)
	Stop the Test Lifecyle Control (TLC) control loop.
int	clTcInitialize (const ClCharT subsystem, const ClCharT test_name, int(func_to_register)(ClTcParamListT param_list))
	Initialize Test Lifecycle Control (TLC) infrastructure and register test case start function.
int	clTcParseConfigFile (ClCharT file_path, ClCharT file_name, ClCharT subsystem_name, ClCharT test_case_name, ClTcParamListT *param_list)
	Parse a file containing runtime paramaters for a test case.
int	clTcParseWorkLoad (ClAmsCSIDescriptorT csi_desc, ClCharT subsystem_name, ClCharT test_case_name, ClTcParamListT param_list)
	Wrapper function for clTcParsConfigFile, called with the AMF CSI descriptor.
void	clTcPrintParams (void)
	Print utility that prints the parsed runtime configuration parameters.
void	clTcRun (void)
	API called to activate Test Lifecycle Control (TLC) control loop.

Detailed Description

Defines, Structures, Typedefs, Functions.

Macro Definition Documentation

#define clTest	(	string,
		predicate,
		errorPrintf
	)

Value:

do{ \
    char __id[ClTestMaxNameLen]; \
    char __error[ClTestMaxNameLen]=""; \
    int __ok = predicate; \
    snprintf(__id, ClTestMaxNameLen, \
             this_error_indicates_missing_parens_around_string string); \
    if (!__ok) \
        snprintf(__error, ClTestMaxNameLen, \
            this_error_indicates_missing_parens_around_string errorPrintf); \
    clTestImpl(__FILE__, __LINE__, __FUNCTION__, __id, __error, __ok); \
} while(0)

Run an individual test.

Parameters

string	A parenthesized printf-style string that identifies this test
predicate	An expression that evaluates to True if the test succeeded, False if it failed.
errorPrintf	A parenthesized printf-style string that you would like printed if the predicate fails. There is no need to print "failed!", etc since this function will do that for you.

Description:: This call runs a test contained in the "predicate" parameter.

Examples:: clTest(("Foo basic"), Foo(ptr)==CL_OK,(" ")) clTest(("Foo with NULL arg"), ((rc = Foo(NULL))==CL_ERR_NULL_POINTER),("rc = %d", rc))

See Also: clTestExecOnFailure()

#define clTestCase	(	name,
		test
	)

Value:

do { \
    clTestCaseStart(name); \
    clCurTc.malfPops = 0; \
    test; \
    clTestCaseEnd((" ")); \
} while (0)

Run a test case.

Parameters

name	A parenthesized printf-style string describing the test case
test	The test case code. Most likely a function call.

Description:: A test case is a grouping of individual tests into a logical unit. Test cases can be nested, this function can be called inside the 'test'. This function is syntatic sugar for: "clTestCaseStart(name); test; clTestCaseEnd();" It is included because it is good practice to isolate your test cases into their own functions. This macro makes it easy to run a test case that is implemented as a function.

See Also: clTestCaseStart(), clTestCaseEnd()

#define clTestCaseEnd ( synopsis )

Value:

do { \
    clTestPrint(("Test case completed [%s]. " \
                 "Subcases: [%d] passed, [%d] failed, [%d] malfunction.\n" \
                 "Synopsis:\n", \
                 clCurTc.name, clCurTc.passed, \
                 clCurTc.failed, clCurTc.malfunction)); \
    clTestPrint(synopsis); \
    clTestPrintIndent-=2; \
    int malf=clCurTc.malfunction; \
    int fail = clCurTc.failed; \
    clPopTestCase(&clCurTc); \
    if (fail) \
        clCurTc.failed++; \
    else if (malf) \
        clCurTc.malfunction++; \
    else \
        clCurTc.passed++; \
} while(0)

Stop this test case.

Parameters

synopsis A parenthesized printf-style string that you would like printed and stored with the results of this test case run. Do not print counts of the number of passed, failed, or malfunctioned tests; The function already does that.

Description:: A test case is a grouping of individual tests into a logical unit. This function ends this logical unit and prints the results.

See Also: clTestCase(), clTestCaseStart()

#define clTestCaseMalfunction	(	reason,
		predicate,
		execOnFailure
	)

Value:

do { \
    if (!(predicate)) { \
        clTestPrint(("Test case malfunction [%s]. " \
                     "Subtests: [%d] Passed, [%d] Failed.\n" \
                     "Malfunction reason:\n", \
                     clCurTc.name, clCurTc.passed, clCurTc.failed)); \
        clTestPrint(reason); \
        if (clCurTc.malfPops) clPopTestCase(&clCurTc); \
        clCurTc.malfunction++; \
        execOnFailure; \
    }  \
} while(0)

Indicate that this test case cannot be completed, if the predicate fails.

Parameters

reason	A parenthesized printf-style string describing why it cannot be completed.
predicate	If this expression evaluates to true, it is a malfunction, otherwise it is not.
execOnFailure	Run this code if there is a malfunction.

Description:: This function is used to indicate that a set of tests have neither succeeded or failed – some condition required to execute the test was not met. This function "Ends" the TestCase, so after calling this function you should not call clTestCaseEnd()

See Also: clTestCase(), clTestCaseStart(), clTestCaseEnd()

#define clTestCaseNumErrors ( ) clCurTc.failed

Returns the number of errored (failed) tests run so far in this test case.

Returns: The number of errored (failed) tests run so far in this test case.

See Also: clTestCase(), clTestCaseStart(), clTestCaseNumErrors(), clTestCaseNumMalfunctions(), clTestCaseNumPasses()

#define clTestCaseNumMalfunctions ( ) clCurTc.malfunction

Return the number of malfunctioned tests in this test case (so far).

Returns: The number of malfunctioned tests in this test case (so far).

See Also: clTestCase(), clTestCaseStart(), clTestCaseNumErrors(), clTestCaseNumMalfunctions(), clTestCaseNumPasses()

#define clTestCaseNumPasses ( ) clCurTc.passed

Return the number of successful (passed) test run so far in this test case.

Returns: The number of successful (passed) test run so far in this test case.

See Also: clTestCase(), clTestCaseStart(), clTestCaseNumErrors(), clTestCaseNumMalfunctions(), clTestCaseNumPasses()

#define clTestCaseStart ( testname )

Value:

do { \
    clTestPrintIndent+=2; \
    clPushTestCase(&clCurTc); \
    clCurTc.passed=0; \
    clCurTc.failed=0; \
    clCurTc.malfunction=0; \
    clCurTc.malfPops = 1; \
    snprintf(clCurTc.name, ClTestCaseMaxNameLen, \
        this_error_indicates_missing_parens_around_string testname); \
    clTestPrint(("Test case started [%s]:\n", clCurTc.name)); \
} while(0)

Start a Test Case.

Parameters

testname A parenthesized printf-style string describing the test case

Description:: A test case is a grouping of individual tests into a logical unit. Test cases can be nested by calling this function multiple times with no intervening call to ClTestCaseEnd()

See Also: clTestCase(), clTestCaseEnd()

#define clTestExecOnFailure	(	string,
		predicate,
		errorPrintf,
		execOnFailure
	)

Value:

do { \
    clTestPrint(string); \
    { \
        int result = (predicate); \
        if (result) { \
            clCurTc.passed++; \
            clTestPrint((": Ok\n")); \
        } else { \
            clCurTc.failed++; \
            clTestPrint((": %s:%d: Test (" #predicate ") failed.  ", \
                         __FILE__, __LINE__)); \
            clTestPrint(errorPrintf); \
            clTestPrint(("\n")); \
            execOnFailure; \
        } \
    } \
} while(0)

Run an individual test, and run some special code if it fails.

Parameters

string	A parenthesized printf-style string that identifies this test
predicate	An expression that evaluates to True if the test succeeded, False if it failed.
errorPrintf	A parenthesized printf-style string that you would like printed if the predicate fails. There is no need to print "failed!", etc since this function will do that for you.
execOnFailure	Run this code if the predicate is false.

Description:: This function is equivalent to clTest, except that you can pass some code to run if there is a failure.

Examples:: clTestExecOnFailure(("Foo basic"), Foo(ptr)==CL_OK,(" "),{ emailMe(); return; }) clTest(("Foo with NULL arg"), ((rc = Foo(NULL))==CL_ERR_NULL_POINTER),("rc = %d", rc))

See Also: clTest()

#define clTestFailed ( __string ) clTestFailedAt(__FILE__, __LINE__,__string)

Indicate that a test failed.

Parameters

__string A parenthesized printf-style string that identifies this test

Description:: Sometimes deciding whether a test passed or failed requires some complex logic. Other times you have to write an if() statement anyway. This call simply indicates that the test identified by the 'string' failed. Do not put words like "failed", "didn't work" etc. in the string. The library will do that for you.

Examples:: rc = Foo() if (rc != CL_OK) clTestFailed(("Foo"));

See Also: clTestSuccess()

#define clTestFailedAt	(	__file,
		__line,
		__string
	)

Value:

do { \
    clCurTc.failed++; \
    clTestPrint((": %s:%d: Test failed.  ", __file, __line)); \
    clTestPrint(__string); \
    clTestPrint(("\n")); \
} while(0)

Just like clTestFailed, but allows the caller to specify the file and line.

Description:: clTestFailed is the preferred API. Use this API when you want to wrap this in your own helper function. In this way the file and line can reflect the file/line of your test, not that of the helper function.

See Also: clTestFailed()

#define clTestGroupFinalize ( ) clTestGroupFinalizeImpl()

Stop the Test infrastructure.

Returns: The number of test cases that failed.

Description:: This function stops the test infrastructure. It is critically important to call this function so that the automation environment knows to stop your Service Group.

See Also: clTestGroupInitialize()

#define clTestGroupInitialize ( name ) clTestPrint(name)

Start up the Test infrastructure.

Parameters

name	Identifies the test Service Group. Must be formatted in printf style i.e. ("name"). If you have more then one program in your SG, then give them different names with the same prefix.

Returns: nothing

Description:: This function call starts up the test infrastructure in your program, and tells the Test Automation Environment that this Service Group has started. You should only call it once during your program's initialization.

Example:: clTestGroupInitialize(("My Unit Test"))

See Also: clTestGroupFinalize()

#define clTestGroupMalfunction	(	reason,
		predicate,
		execOnFailure
	)

Value:

do { \
    if (!(predicate)) { \
        clTestPrint(reason); \
        clTestPrint(("Test Malfunction.")); \
        (void) clTestGroupFinalize(); \
        execOnFailure; \
    } \
} while(0)

Indicate that the Test Group cannot execute, if an expression evaluates to False.

Parameters

reason	A parenthesized printf-style string describing why the test group cannot be run.
predicate	If this expression evaluates to true, it is a malfunction, otherwise it is not.
execOnFailure	Run this code if there is a malfunction.

Returns

Return values

\retval

Description:: This function is used to indicate that a set of tests have neither succeeded or failed – some condition required to execute the test was not met. This function "Finalizes" the TestGroup, so after calling this function, you must NOT use any clTest APIs

#define clTestPrint ( x ) clTestPrintAt(__FILE__, __LINE__, __FUNCTION__, x)

Print something to the test console.

Parameters

x	A parenthesized printf-style string that should be printed

Description:: This function prints to the test console. Do not use for general purpose logging, but only for items that are specific to testing. Also, it is much better to use the strings within the other API calls because they are associated with a particular test or test case. Frankly, I can't think of any reason to use this function, but it is here to provide for the unanticipated.

#define clTestPrintAt	(	__file,
		__line,
		__function,
		x
	)

Value:

do { \
    char __tempstr[2048]; \
    snprintf(__tempstr,2048, \
             this_error_indicates_missing_parens_around_string x); \
    clTestPrintImpl(__file, __line, __function,__tempstr); \
    CL_DEBUG_PRINT(clTestLogLevel, x); \
} while(0)

Just like clTestPrint, but allows the caller to specify the file and line.

Description:: clTestPrint is the preferred API. Use this API when you want to wrap this in your own helper function. In this way the file and line can reflect the file/line of your test, not that of the helper function.

See Also: clTestPrint()

#define clTestSuccess ( __string ) clTestSuccessAt(__FILE__, __LINE__, __string)

Indicate that a test passed.

Parameters

__string A parenthesized printf-style string that identifies this test

Description:: Sometimes deciding whether a test passed or failed requires some complex logic. Other times you have to write an if() statement anyway. This call simply indicates that the test identified by the 'string' succeeded. Do not put words like "success", "worked", "ok" etc. in the string. The library will do that for you.

Examples:: rc = Foo() if (rc != CL_OK) clTestSuccess(("Foo"));

See Also: clTestFailed()

#define clTestSuccessAt	(	__file,
		__line,
		__string
	)

Value:

{ \
    clCurTc.passed++; \
    clTestPrintAt(__file,__line, __FUNCTION__, __string); \
    clTestPrintAt(__file,__line, __FUNCTION__, (": Ok\n")); \
} while (0)

Just like clTestSuccess, but allows the caller to specify the file and line.

Description:: clTestSuccess is the preferred API. Use this API when you want to wrap this in your own helper function. In this way the file and line can reflect the file/line of your test, not that of the helper function.

See Also: clTestSuccess()

Typedef Documentation

typedef struct ClTcParamListT ClTcParamListT

List to store all the parsed runtime configuration paramaters, by TLC.

The parsing routines will allocate an array of type ClTcParamT and store the parsed values into it.

typedef struct ClTcParamT ClTcParamT

Basic structure to store the parsed runtime configuration paramater, by TLC.

The XML file that defines the runtime configuration parameters is parsed into this structure that defines the parameter name its type and the value. The interger id field is used as a short cut instead of strcmp within your code, you can use a switch() statement

typedef enum ClTcParamTypeE ClTcParamTypeE

Current paramater types supported by TLC.

Each test case can define the runtime configuration parameters in an XML file, current limited to strings, integers and float types.

typedef union ClTcParamValU ClTcParamValU

Union to store parsed runtime configuration paramater value, by TLC.

The XML file that defines the runtime configuration parameters is parsed into the union and the type set to indicate what type of parameter is stored.

Enumeration Type Documentation

enum ClTcParamTypeE

Current paramater types supported by TLC.

Each test case can define the runtime configuration parameters in an XML file, current limited to strings, integers and float types.

Function Documentation

int clTcActivate	(	ClAmsCSIDescriptorT *	csi_desc,
		ClAmsHAStateT	ha_state
	)

API called to start the test case registered by the user in clTcInitialze.

Header File:: clTcUtils.h

Parameters

csi_desc	Pointer to ClAmsCSIDescriptorT structure sent by AMF during a HA state change. This is expected to contain the configuration file name and location.
ha_state	Variable of type ClAmsHAStateT, used to store ha state, not needed by TLC but may be needed by application

Returns: None

Return values

CL_OK	if successfull
return	codes from clTcParseWorkLoad()

Description:: When the user application receives a 'ha state' change to Active it is expected that clTcActivate() is invoked in order to run the test case. The routine that actuall implements the test case is registered with clTcInitialize(). The CSI descriptor contains two attributes that describe the config file name and location so that its contents can be parsed and the parameter list popualated with its contents. If there is a failure in parsing the contents of the file then the user specified test routine will not be invoked. However if there is a failure in interpreting the CSI descriptor it is assumed the test runs without any arguments

Library File:: libClTcUtils.a

See Also: bar()

void clTcFinalize ( void )

Stop the Test Lifecyle Control (TLC) control loop.

Header File:: clTcUtils.h

Parameters

None

Returns: None

Return values

None

Description:: Set the exit_flag to true so that the tc_run() loop stops and returns control back to the user

Library File:: libClTcUtils.a

See Also: bar()

int clTcInitialize	(	const ClCharT *	subsystem,
		const ClCharT *	test_name,
		int()(ClTcParamListT param_list)	func_to_register
	)

Initialize Test Lifecycle Control (TLC) infrastructure and register test case start function.

Header File:: clTcUtils.h

Parameters

subsystem_name	test case qualifier used by parser to search the configuration file to get to the appropriate subsystem
test_case_name	test case qualifier used by parser to search the configuration file to get to the appropriate test case within the subsystem
(*func_to_register)(ClTcParamListT	*param_list) function pointer to user function that runs the test case

Returns: None

Return values

CL_OK	if all succeeds
CL_ERR_INVALID_PARAMETER	if function pointer is NULL
ASP	return codes if OSAL API calls fail

Description:: Initializes internal data structures so that a test can be started or stopped based on the locking and unlocking of a Service Group. The assumption here is that the "THREAD_FOR_APP" option was chosen during the modeling of this application.

The user is expected to call clTcRun() at the end of initialization phase in clCompAppInitialize() so that a forever loop is started.

When the state change to active is received, the user calls clTcActivate() which runs the test function registered with this

Library File:: libClTcUtils.a

See Also: bar()

int clTcParseConfigFile	(	ClCharT *	file_path,
		ClCharT *	file_name,
		ClCharT *	subsystem_name,
		ClCharT *	test_case_name,
		ClTcParamListT *	param_list
	)

Parse a file containing runtime paramaters for a test case.

Parameters

file_path	complete path to config file location on target
file_name	config file name follows schema defined by clTcParamDef.xsd
subsystem_name	test case qualifier used by parser to search the configuration file to get to the appropriate subsystem
test_case_name	test case qualifier used by parser to search the configuration file to get to the appropriate test case within the subsystem

Returns: param_list pointer to a structure of type tc_param_listT in which all the parsed parameters are stored

Return values

CL_ERR_NULL_POINTER	file could not be opened by ezxml
CL_ERR_NO_MEMORY	memory allocation failed
CL_ERR_INVALID_PARAMETER	input argument(s) is/are invalid
CL_ERR_DOESNT_EXIST	test case could not be found in config file
CL_ERR_INVALID_BUFFER	general parsing error

Description: Parses a given XML file and the retrieves configuration parameters for a given test case and subsystem. This API assumes that the tc_param_listT struct is not allocated; so ensure that is the case before calling this API or else you will end up with a memory leak

Library File:: libTcClUtils.a

See Also: bar()

int clTcParseWorkLoad	(	ClAmsCSIDescriptorT *	csi_desc,
		ClCharT *	subsystem_name,
		ClCharT *	test_case_name,
		ClTcParamListT *	param_list
	)

Wrapper function for clTcParsConfigFile, called with the AMF CSI descriptor.

Parameters

csi_desc	Pointer to ClAmsCSIDescriptorT structure sent by AMF during a HA state change. This is expected to contain the configuration file name and location.
subsystem_name	test case qualifier used by parser to search the configuration file to get to the appropriate subsystem
test_case_name	test case qualifier used by parser to search the configuration file to get to the appropriate test case within the subsystem

Returns: param_list pointer to a structure of type tc_param_listT in which all the * parsed parameters are stored

Return values

CL_ERR_INVALID_PARAMETER	if input arguments are invalid
see	return codes for clTcParseConfigFile()

Description:: A wrapper function for clTcParseConfigFile, but this API takes the CSI descriptor as input and returns the parameter list. See clTcParseConfigFile() for more details.

Library File:: libTcClUtils.a

See Also: bar()

void clTcPrintParams ( void )

Print utility that prints the parsed runtime configuration parameters.

Header File:: clTcUtils.h clTestApi.h

Parameters

None

Returns: None

Return values

None

Description:: Utility function that prints all the parameters that are read in the configuration file; along with the subsystsem and test name Current this API calls the clTestPrint Macro as defined in clTestApi.h

Library File:: libClTcUtils.a

See Also: bar()

void clTcRun ( void )

API called to activate Test Lifecycle Control (TLC) control loop.

Header File:: clTcUtils.h

Parameters

None

Returns: None

Return values

None

Description:: Runs a forever loop, and check for two conditions. If the internal flag tc_run_test_flag is TRUE, then the user defined start routine is invoked with the configuration parameters read by clTcActivate The assumption here is that the "THREAD_FOR_APP" option was chosen during the modeling of this application. When the user specified routine returns clTcDeactivate() is invoked to stop this run. The other condition tested for is the internal flag tc_exit_test_flag. If this is true then the tc_finalize() routine has been invoked, which means the application is being terminated

Library File:: libClTcUtils.a

See Also: bar()

Files

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation