polyspace-test -generate

R2026b

(System Command) Generate test registration function from a set of Polyspace Test C/C++ test files

Since R2023b

Syntax

polyspace-test -generate -registration -results-dir <resultsFolder> -filename <regFile> -test-sources <testFiles> [options]

polyspace-test -generate -registration -main -results-dir <resultsFolder> -filename <regFile> -test-sources <testFiles> [options]

Description

The system command polyspace-test -generate generates a test registration function for the C/C++ xUnit tests provided in test files.

polyspace-test -generate -registration -results-dir <resultsFolder> -filename <regFile> -test-sources <testFiles> [options] generates a file <regFile> with a test registration function for the tests specified in <testFiles>.

polyspace-test -generate -registration -main -results-dir <resultsFolder> -filename <regFile> -test-sources <testFiles> [options] generates a file <regFile> with a test registration function and a main function for the tests specified in <testFiles>.

Examples

Generate Test Registration and Test main

This example shows how to generate a test registration function and a test main that invokes this function, given a set of test sources. Automatically generating the test registration function allows you to define new tests without explicitly adding them in your test registration function.

Follow these steps using files in the folder <polyspaceroot>\polyspace\examples\doc_pstest\test_suites_setup_teardown. Here, <polyspaceroot> is the Polyspace^® installation folder.

1. Compile the source file example.c and the test files test1_no_regfcn.c and test2_no_regfcn.c, along with the Polyspace Test™ xUnit API libraries. The test files contain test definitions only, and do not have a test registration function or a main function.

   For instance, if you are using the GCC compiler, run the following at the command line:

   gcc example.c test1_no_regfcn.c test2_no_regfcn.c <pstunit_source> -I <pstunit_includes> -o testrunner
   

   Here, <pstunit_source> and <pstunit_includes> are the files and folders containing the xUnit API definitions:

   • <pstunit_source> is the file <polyspaceroot>\polyspace\pstest\pstunit\src\pstunit.c.

   • <pstunit_include> is the folder <polyspaceroot>\polyspace\pstest\pstunit\include.

   You see a compilation error because of a missing main function.

2. Generate the test registration function that registers the tests in the test files and a main function that invokes the test registration function:

   polyspace-test -generate -registration -main -filename testReg.c -results-dir testRegFolder -test-sources test1_no_regfcn.c test2_no_regfcn.c

3. Recompile the sources and tests, along with the newly generated file. The compilation succeeds, and when you run the tests, you see results from all the test files.

   For instance, if you are using the GCC compiler on Windows^®, run the following:

   gcc example.c test1_no_regfcn.c test2_no_regfcn.c testReg.c <pstunit_source> -I <pstunit_includes> -o testrunner
   testrunner.exe

   Open the generated file testReg.c. You see a test registration function defined using the macro PST_REGFCN and called in a main function using the macro PST_REGFCN_CALL. The test registration function adds the tests from all the test files using the PST_ADD_TEST macro.

Input Arguments

-results-dir <resultsFolder> — Path to folder for storing test registration file

string

Path to folder where the generated test registration file is stored.

-filename <regFile> — Name of test registration file

string

Name of test registration C/C++ file.

-test-sources <testFiles> — Paths to xUnit test files

string

One or more space-separated paths to C/C++ xUnit test files.

options — Options for registration file generation

string

Option	Description
-registration-name <funcName>	Specify the name of a test registration function.
-force-regenerate	Regenerate test registration file even if the test files have not changed.

Limitations

The -generate -registration command uses regular expressions to detect test macros, such as PST_SIMPLE_TEST, PST_SIMPLE_TEST_BODY, or PST_TEST, in the specified test files, and then generates the registration function. The test detection has the following limitations:

• The test detection does not account for block comments, inline comments, or strings that resemble test macros. If your test files contain commented-out or string-enclosed macros, the command incorrectly registers them as actual tests.

• The test detection does not recognize macros with multiple parameters where the arguments span multiple lines. For instance, if you split the arguments to PST_TEST(suite, name) across two lines, the command does not detect the test.

• If you create your own macros for test definition using #define-s like the following:

  #define MY_TEST PST_TEST

  The test detection does count invocations of your macros as tests.

If you add your xUnit tests to a Polyspace Platform project, the test registration function is automatically generated at build time. The test registration via Polyspace Platform projects performs a static analysis of your test code and avoids the above limitations.

Version History

Introduced in R2023b