Parameterized Test Units

You can leverage the tests you write in Test Units by using STRIDE's parameterization feature. This allows you to supply parameters to your test units at run time to customize test behavior.

How Parameters are Passed from the Host

Parameters to be passed to a target test unit are supplied on the stride.exe command line used to invoke the test unit. Test unit parameter values are specified between parentheses characters immediately following the test unit name on the command line.

Number Parameter

For example, assume that you have a test unit implemented on the target named MyTest and it has been coded to accept a single integer parameter. To run this test unit with the parameter value 17, use the following run specification:

 --run=MyTest(17)

String Parameter

As a second example, consider a test unit coded to take a single string as a parameter. The parameter is supplied as follows:

 --run=MyOtherTest(\"string\")

Note that the string parameter must be enclosed with double quote characters. The double quotes are escaped with a backslash as this is required by the command line processor.

Parameter Containing Spaces

When the string parameter contains one or more spaces, the command processor further requires you to enclose the entire --run argument in double quotes as follows:

 --run="MyOtherTest(\"this is the parameter\")"

Note that the command line processor requires you to enclose with double quotes if there are any spaces at all in the --run argument. This can be counter-intuitive when passing only number types.

No space in argument list

 --run=TestX(123,555,3.14)

Space in argument list

 --run="TestX(123, 555, 3.14)"

Multiple Parameters

You may pass any number of parameters to a test unit, and each parameter may be of any supported type. An example is shown below:

 --run="YetAnotherTest(19.58, -1, \"Encinitas\", 92024, \"south\")"

A few additional examples are shown on the STRIDE Test Runner Reference page.

How Parameters are Received on the Target

Parameters are passed from the stride.exe command line and are presented on the target as follows:

C++ test unit

Parameters are presented as constructor arguments to the test unit class

C-Class test unit

Parameters are presented as arguments to the Initialization function.

Flist test unit

Not supported

C++ Test Unit

When using parameters with a C++ test unit, you declare and implement a public constructor that takes the number and type of arguments you want to receive.

Important: Do Not declare or implement a default constructor (constructor taking no arguments) in a class that gets parameters.

MyTest.h

#include <srtest.h>

class MyTest : public stride:srTest
{
public;
    MyTest(int nParam, const char* szParam)
    {
        // typically, you will store parameter values into member variables for use by
        // the member test methods
        m_nParam = nParam;
        strncpy(m_szParam, szParam, MAX_LEN);
    }

    // Tests
    void Test1();
    ...
    ...
    ...
private:
    int m_nParam;
    char m_szParam[MAX_LEN];
};

#ifdef _SCL
#pragma scl_test_class(MyTest)
#endif

C-Class Test Unit

MyTest.h

#include <srtest.h>
  
typdef struct MyTest
{
    int m_nParam;
    char m_szParam[MAX_LEN];

    void (*Test1)(struct MyTest* self);
    ...
    ...
    ...
} MyTest;

void MyTest_Init(MyTest* self, int nParam, const char* szParam);

#ifdef _SCL
#pragma scl_test_cclass(MyTest, MyTest_Init)
#endif

MyTest.c

#include  "MyTest.h"
 
static void Test1(MyTest* self)
{
    ...
    ...
    ...
}

/* other test implementations */
...
...
...


void MyTest_Init(MyTest* self, int nParam, const char* szParam)
{
    self->m_nParam = nParam;
    strncpy(self->m_szParam, szParam, MAX_LEN);

    self->Test1 = Test1;
    ...
    ...
    ...
}

Supported Parameter Types

ANSI/Unicode strings and number parameter types are directly supported.

String types	ANSI char* const char* Unicode short* const short* Where wchar_t is a built-in type, pointers to this type are also supported
Number types	all integer types float double

Constructor Rules for Parameterized C++ Test Classes

Because STRIDE test classes are instantiated dynamically by the STRIDE runtime, the rules for construction are subtly different from garden-variety C++ classes.

Don't Declare More Than One Public Constructor

You must declare only one public constructor in a test class.

This is typically not a problem for non-parameterized test classes, as a common default constructor is what's needed. Often you will begin with a non-parameterized test class and add the parameterization later as your testing gets more sophisticated. A common mistake here is to add a second public parameterized constructor to the class in addition to the original default constructor; this is perfectly legal in C++, but will not give you the desired result.

You must ensure that you have only one public class constructor.

Example

// MyTest.h

#include <srtest.h>

class MyTest : public stride::srTest
{
public:
    // Don't do this!
    MyTest();  // WRONG! DON'T DECLARE DEFAULT (NULLARY) CONSTRUCTOR!

    // Do only this
    MyTest(int param1, const char* param2);  // CORRECT: Declare only your paramterized constructor

   ...
};

Default Constructor Parameters Are Not Used

Default constructor parameters are a very common and useful pattern in C++ programming. Where declared, default parameter values are inserted where appropriate by the C++ compiler at build-time (static polymorphism).

In the case of STRIDE, each test class is instantiated dynamically on demand by the harnessing code. The harnessing code does not know at build time whether constructor parameters will be omitted when the class is ultimately instantiated. (Recall that constructor parameters are specified on the stride.exe command line on the host computer.)

Therefore, STRIDE imposes the following rules:

• Test class constructor arguments may be omitted
  • Only trailing arguments may be omitted; they must be the last argument(s)
  • The test class declaration does not need to specify default arguments for the above to work. (In fact the default arguments won't be used!)

• Any arguments that are omitted will be supplied to the constructor with the value 0 for number types and empty (zero-length) string for character pointer types.

Example

// MyTest.h

#include <srtest.h>

class MyTest : public stride::srTest
{
public:
    // Default parameter values WILL NOT be used!
    // If a parameter is not specified on stride command line,
    // its value is always passed to the constructor as 0 or empty string
    MyTest(int param1 = 100, int param2 = 200);  // WRONG! DON'T DO THIS!
    ...
};

A Pattern To Implement Non-Zero Default Construction Parameters

// MyTest.h

#include <srtest.h>

#define MAX_STRING 256

class MyTest : public stride::srTest
{
public:
    MyTest(int nParam, float fParam, const char* szParam);
    ...

private:
    int m_nParam;
    float m_fParam;
    char m_szParam[MAX_STRING];
};


// MyTest.cpp

static const int nDEFAULT_NPARAM = 100;
static const float fDEFAULT_FPARAM = 3.1415;
static const char szDEFAULT_SZPARAM[] = "This is the default value";

MyTest::MyTest(int nParam, float fParam, const char* szParam)
{

    m_nParam = nDEFAULT_NPARAM;
    if (nParam)
    {
        m_nParam = nParam;
    }

    m_fParam = fDEFAULT_FPARAM;
    if (fParam)
    {
        m_fParam = nParam;
    }

    memset(m_szParam, 0, MAX_STRING);
    strncpy(m_szParam, szDEFAULT_SZPARAM, MAX_STRING - 1);
    if (szParam[0])
    {
        strncpy(m_szParam, szParam, MAX_STRING - 1);
    }
}

---

Notes