|
|
| (4 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| == Test Fixturing ==
| | The APIs for testing in C/C++ are documented in the following articles: |
|
| |
|
| ===What is Test Fixturing?===
| | * [[Test Point Testing in C/C++|Test Point Testing API]] (for writing native test point validation tests) |
| Recall that generic xUnit testing comprises four discrete phases:
| | * [[Runtime Test Services|Runtime Test Services API]] (for dynamic test result manipulation) |
| # Setup
| | * [[File Transfer Services|File Transfer API]] (for host file manipulation from the device under test) |
| # Exercise
| | * [[Test Fixturing in C/C++|Test Fixturing]] (for test unit fixturing in native code) |
| # Verify
| | * [[Test Documentation in C/C++|Test Documentation]] (how to document your native test units) |
| # Teardown
| | * [[Test Double|Test Doubles]] (for advanced dependency interception/function mocking in native code) |
| | |
| ''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 [[Test Unit Pragmas|scl pragmas]]:
| |
| | |
| *[[Scl test setup|scl_test_setup()]]
| |
| *[[Scl test teardown|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 | File Services Samples]] that demonstrates techniques and syntax for performing basic tasks using the [[File Transfer Services|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 [http://www.stack.nl/~dimitri/doxygen/ doxygen format]. In order to enable test unit documentation, here is summary of the necessary steps:
| |
| * document your test unit source with [http://www.stack.nl/~dimitri/doxygen/docblocks.html doxygen] formatted blocks. Since only header files are typically passed to the [[S2scompile|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 [[S2scompile|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|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 [http://www.doxygen.nl/docblocks.html]
| |
| | |
| === Examples ===
| |
| | |
| ==== Test Class ====
| |
| <source lang=c>
| |
| #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
| |
| </source>
| |
| | |
| ==== Test C-Class ====
| |
| <source lang=c>
| |
| #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
| |
| | |
| </source>
| |
| | |
| ==== Test FList ====
| |
| (source file name is ''my_flist.h'' in the example below)
| |
| <source lang=c>
| |
| #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
| |
| | |
| </source>
| |
| | |
| == Runtime Test Services ==
| |
| | |
| Refer to [[Runtime Test Services|this article]] for a complete listing of the Runtime Test Services APIs.
| |
| | |
| == File Transfer Services ==
| |
| | |
| Refer to [[File Transfer Services|this article]] for a complete listing of the File Transfer Services APIs.
| |
|
| |
|
| [[Category:Test Units]] | | [[Category:Test Units]] |