Test API

Test Fixturing

What is Test Fixturing?

Recall that generic xUnit testing comprises four discrete phases:

1. Setup
2. Exercise
3. Verify
4. Teardown

Test fixturing refers to the Setup and Teardown phases of the testing.

In the Setup phase, we put all of the things into place that are required in order to run a our test and expect a particular outcome. This includes things like:

• Acquiring resources such as memory, hardware, etc.
• Setting up required states such as input files in place, memory filled with a pattern, dependencies initialized, etc.

In the Tear down phase, we clean up the fixturing we did in the Setup phase, leaving the system in a state that is ready to be used by the next test.

The Importance of Fixturing

The proper use of fixturing can simplify test writing and lead to these benefits:

• Separation of initialization/deinitialization code from your test code
• Reuse of setup and teardown code within a test unit
• Simplification of resource cleanup in test methods

STRIDE Fixturing Resources

Specifying Fixturing Methods

Within your source code, you can optionally specify setup and teardown methods using the scl pragmas:

• scl_test_setup()
• scl_test_teardown()

When declaring these pragmas, you specify 1) the test unit the pragma applies to; and 2) the name of the method that will be called by the STRIDE framework to perform the Setup or Teardown fixturing. If specifed, the STRIDE framework will call the Setup method before each test method in the test unit, and the Teardown method after each test method in the test unit.

You can see examples of fixturing delcarations in these test samples:

• Test Class Samples
• Test CClass Samples

Advanced Fixturing

A common test pattern--especially in the area of multimedia--is to create a test that is parametrized by an input file. The test is run multiple times with a different input file used for each run.

In this case the setup fixturing makes the file data available to the test (typically opening a file on the host, then copying data from host to target), and the teardown fixturing removes any files created on the target and so forth.

STRIDE offers an integrated solution to file fixturing that makes it possible from your target test code to specify a host-based file and transfer its data to the target. Refer to the File Services Samples that demonstrates techniques and syntax for performing basic tasks using the File Transfer Services API.

Test Documentation

The STRIDE Framework provides an integrated solution for automatically extracting documentation for your test units using the well-known doxygen format. In order to enable test unit documentation, here is summary of the necessary steps:

• document your test unit source with doxygen formatted blocks. Since only header files are typically passed to the stride compiler, we recommend you place your documentation in the header file. Alternatively, if you have an implementation (c or cpp) file with the same basename located in the same directory as your header file, we will search this file for documentation as well.
• configure your build/make process to call the stride compiler with the additional --documentation flag. If you are using one of our preconfigured makefiles in a sandbox environment, this option has already been enabled.
• run your build process to produce a stride database and stride enabled target application.
• start your application and execute the stride runner to connect and run the tests.
• The generated report will contain description information for the test suites and test cases generated from the doxygen blocks.

Recommendations and Guidelines

As mentioned above, we generally recommend that you document your test units in the header file so as to ensure that the stride toolchain is able to properly correlate test units with the extracted documentation. For simplicity, we also recommend that you place your documentation blocks as close as possibly to the documented entity (class, struct, or method) so as to avoid confusion. The following are specific notes about documenting each of the three types of test units that the STRIDE Framework supports.

Test Classes

Source documentation is generally straight-foward, with doc blocks preceding the corresponding class and method declaration. If you prefer to locate your documentation blocks elsewhere in the header file, use the \class tag to correlate your docs and declared test class.

Test C-Classes

Source documentation must relate to the structure that is used as the "C-Object" for the test unit. Since a C-Class uses function pointers to call its individual tests, test method documentation must be associated with the corresponding structure function pointer member. As such, method documentation for C-Classes must be in the header file.

Test FLists

Since FLists have no specific storage entity (class or struct) to which they are associated. As such, the only way to provide unit-level documentation for FLists is to document the source file in which its methods are declared. The unit documentation is associated with its file using the \file tag. Because of this restriction, you will only be able to provide documentation for one FList in each header file - so we recommend that you generally confine each Test FList to it's own source file pair (.h and .c). The test methods associated with an FList are documented as expected, with the documentation block preceding the function declaration.

Supported Doxygen Tags

Doxygen has a rich set of tags and formatting options aimed at comprehensive source documentation. The STRIDE Framework uses doxygen on a per-file basis to extract standalone documentation for individual test units and their methods. As such, we only support limited set of doxygen features in the code documentation. The STRIDE Framework supports the following doc formatting:

• custom HTML formatting
• lists (ordered, unordered, definition)
• code blocks
• bold and emphasis text

More advanced doxygen formatting tags (such as tables and parameter lists) are not supported at this time, but will likely be in future releases.

For more information on Doxygen formatting, see [1]

Examples

Test Class

#pragma once
#include <srtest.h>

///  \brief Summary description for MyTestUnit (optional)
///
/// More  detailed documentation goes here
/// This example shows the C++  commenting style, the C style may also be used
///

 
class MyTestClass{
  public:
    /// 
    ///  Description for Test_1 here.  
    ///
    bool  Test_1();
    
    /// 
    ///  Description for Test_2 here.  
    ///
    bool  Test_2();
};

#ifdef _SCL
#pragma  scl_test_class(MyTestClass)
#endif

Test C-Class

#pragma once
#include <srtest.h>

/*!  \brief Summary description for my_c_class(optional)

More detailed  documentation goes here 

*/
typedef  struct my_c_class
{
    /*! 
    Description  for Test_1 here.  
    */
    int    (*Test_1)(struct my_c_class* pcc);
    
    /*! 
    Description  for Test_2 here.  
    */  
    int    (*Test_2)(struct my_c_class* pcc);
} my_c_class;

#ifdef __cplusplus
extern  "C" {
#endif
void  my_c_class_init(struct my_c_class* pcc);
#ifdef  __cplusplus
}
#endif

#ifdef _SCL
#pragma  scl_test_cclass(my_c_class, my_c_class_init)
#endif

Test FList

(source file name is my_flist.h in the example below)

#pragma once
#include <srtest.h>

#ifdef __cplusplus
extern  "C" {
#endif

/*! 
\file  my_flist.h
\brief Summary description for my_flist(optional)
    
More detailed  documentation goes here  
 
*/

/*! 
Description  for Test_1 here.  
*/
int    Test_1();

/*! 
Description for Test_2 here.  
*/
int   Test_2();

#ifdef __cplusplus
}
#endif

#ifdef _SCL
#pragma  scl_test_flist("my_flist", \
    Test_1,\
    Test_2)
#endif

Runtime Test Services

Refer to this article for a complete listing of the Runtime Test Services APIs.

File Transfer Services

Refer to this article for a complete listing of the File Transfer Services APIs.