CoverageScanner command line arguments Controlling the instrumentation from the source code

Library calls

C and C++ Library

The CoverageScanner library is generated during instrumentation and enables you to:

initialize the measurement system and select the name of the .csexe file
install a handler which saves the execution report on exit
in a unit test scenario, to pass information about the tests to the execution report, especially the name of the test, comments and the test result
handle dynamically loaded libraries
customize the output system for special needs

The library functions are accessible from any instrumented file, without the need for an #include directive. When a file is instrumented, a preprocessor symbol __COVERAGESCANNER__ is defined. It can be used to exclude calls to the library functions from the compilation when instrumentation is switched off.

`__coveragescanner_install()`

void __coveragescanner_install(const char *appname)

Note: This function is not needed for gcc, clang, Microsoft^® Visual Studio^® or most other modern C/C++ compilers.

Initialize the CoverageScanner library. It should be the first function call in the main() function. The parameter appname contains the name of the executable. It is used to set the name of the measurement file to <appname>.csmes.

__coveragescanner_install() registers an exit handler via atexit() in order to save the execution report whenever the application terminates. The handler calls the function __coveragescanner_save() to store the execution traces at the end of the program. It is called when the program terminates regularly and also if the signals SIGABRT, SIGTERM, SIGFPE, SIGILL, SIGINT, SIGSEGV and SIGTERM are received.

Suggested usage:

int main(int argc,char *argv[])
{
#ifdef __COVERAGESCANNER__
  __coveragescanner_install(argv[0]);
#endif
  ...
}

Platform dependencies

With gcc, clang or Visual Studio, CoverageScanner automatically installs a minimal handler. It saves the execution in the file program_name > .csmes on a normal exit of the application. Calling __coveragescanner_install() allows setting the file name of the execution report and also saves the report at an abnormal exit, like a crash or an interrupt by a signal.

__coveragescanner_install() is not available for a compiler if its profile parameter CUSTOM_SETUP is set to NONE (see CoverageScanner adaptation to a tool suite).

`__coveragescanner_testname()`

void __coveragescanner_testname(const char *name)

Set the name of the current test/execution. It will be saved in the execution report and displayed in the Executions window (see Executions) when the .csmes file is loaded into CoverageBrowser.

All code that is executed until the end of the program or the next call of __coveragescanner_save() is considered part of the test name. If tests get the same name, CoverageBrowser disambiguates them by numbers, like MyTest (2).

Test names may be hierarchical, with hierarchy levels separated by slashes: If a program defines two tests, group/test1 and group/test2, CoverageBrowser displays them as two tests, test1 and test2 under a common heading, group.

Note: This and the following functions until __coveragescanner_save() are especially intended for use with unit test frameworks (see Test suites and Coco).

`__coveragescanner_teststate()`

void __coveragescanner_teststate(const char *state)

Set the state of the current test. The parameter state may have the following values:

PASSED: the test was successful.
FAILED: the test was not successful.
INCIDENT: the test was not successful (similar to failed).
CHECK_MANUALLY: it was not possible to determine whether the test was successful.
SKIPPED: the test was skipped.

If the function is called twice, the first state is overwritten. The test state will be saved in the execution report and be displayed in the Executions window (see Executions) when the .csmes file is loaded into CoverageBrowser.

`__coveragescanner_add_html_comment()`

void __coveragescanner_add_html_comment(const char *comment)

Set an HTML comment to the current execution. There is only one HTML comment active at any time, but it can be put together with several calls of __coveragescanner_add_html_comment(). In this case, the values of the various comment parameters are concatenated.

The full comment must follow the HTML syntax, but only the content of the <body> tag is used. A minimal comment might therefore be something like <html><body>My comment</body></html>.

`__coveragescanner_clear_html_comment()`

void __coveragescanner_clear_html_comment()

Remove the comment added by calls of the function __coveragescanner_add_html_comment().

`__coveragescanner_save()`

void __coveragescanner_save()

Save the execution report and reset the status of all instrumentations. The coverage counters for each line of code and the execution status of the current test are reset, but the HTML comment stays unchanged.

`__coveragescanner_clear()`

void __coveragescanner_clear()

Reset the coverage counters for all lines of code.

This is useful in a unit testing framework. After the framework has started, __coveragescanner_clear() can be called. Then the activity of the framework at startup does not become part of the code coverage.

`__coveragescanner_filename()`

void __coveragescanner_filename(const char *name)

Set the file name of the execution report. The extension .csexe is added automatically. If name is NULL, the generation of execution reports is disabled.

name may contain the following escape sequences:

%p: The process identifier, if it is provided by the platform, otherwise the empty string.
%w: The working directory. The value is computed when the CoverageBrowser library is initialized; it does not change afterwards.
%t: The current time, or the empty string if it cannot be computed.
%d: The current date, or the empty string if it cannot be computed.

Platform dependencies

The escape sequences are only available for a compiler if its profile parameter FILE_FORMAT_SPECIFIER is set to YES (see CoverageScanne adaptation to a tool suite).

Date and time may not be available on some embedded platforms.

`__coveragescanner_get_filename()`

const char * __coveragescanner_get_filename()

Return the .csexe file name.

`__coveragescanner_register_library()`

int __coveragescanner_register_library(const char *library_name)

Register a shared library that was loaded on demand. The function must be called after a library has been loaded with dlopen() (UNIX^®) or LoadLibrary() (Microsoft^® Windows). After it is registered, the code coverage of the library is saved in the same coverage report file as the coverage of the main application.

It is possible to call __coveragescanner_register_library() more than once, but every call must be matched by a corresponding call of __coveragescanner_unregister_library(). For each library there is a use counter to keep track of the registrations.

Returned values:

0: Success.
-1: Error: library could not be loaded.
-2: Error: invalid library name.
1: Success, but the library is already registered. The use count of the library has been incremented.
2: Success, but the library is not instrumented.

Note: For the use of this and the following function, see Code coverage of libraries.

Platform dependencies

__coveragescanner_register_library() and __coveragescanner_unregister_library() are not available for a compiler if its profile parameter PLUGIN_REGISTRATION_API is set to NO (see CoverageScanne adaptation to a tool suite).

`__coveragescanner_unregister_library()`

int __coveragescanner_unregister_library(const char *library_name)

De-register a shared library that was loaded on demand. The function must be called before a library is unloaded with dlclose() (UNIX) or CloseHandle() (Windows).

Returned values:

0: Success.
-1: Error: library was not registered.
-2: Error: invalid library name.
1: Success, but the library was not unregistered because its use count was not null.
2: Success, but the library is not instrumented.

`__coveragescanner_register_squish()`

void __coveragescanner_register_squish()

Try to register the instrumented application with Squish. This makes most of the Coco library functions accessible to Squish, so that it can control the writing of the coverage measurements.

It is rarely necessary to use this function explicitly since it is automatically called at start of the application (or by __coveragescanner_install(), if calling it is necessary).

Calling the function more than once has the same effect as calling it once. If the application was not started by Squish, the function has no effect.

`__coveragescanner_memory_pool_stat()`

void __coveragescanner_memory_pool_stat(int *size, int *used, int * max_used )

Retrieve the current memory consumption of the memory pool.

The following parameters are returned:

size: the overall size of the memory pool.
used: the current memory usage.
max_used: the peak memory usage.

This function only makes sense in the case of using a memory pool.

`__coveragescanner_set_custom_io()`

By default, CoverageScanner writes the execution report (the .csexe file) to the file system with help of common C library functions. In some situations, e.g. with embedded systems, it is necessary to use other methods. For this reason, CoverageScanner provides __coveragescanner_set_custom_io(), which lets you replace the output functions used by __coveragescanner_save().

void __coveragescanner_set_custom_io(
    char *(*csfgets)(char *s, int size, void *stream),
    int (*csfputs)(const char *s, void *stream),
    void *(*csfopenappend)(const char *path),
    void *(*csfopenread)(const char *path),
    void *(*csfopenwrite)(const char *path),
    int (*csfclose)(void *stream),
    int (*csremove)(const char *path) );

Arguments 0, 3 and 6 (csfgets, csfopenread, and csfremove) are pointers to functions that are only used when the coveragescanner argument --cs-lock-csexe is in use. You can provide a NULL pointer for each of them if you are not using that option.

The void* stream pointers returned from csfopenappend, csfopenread, and csfopenwrite are later passed in as arguments to csfputs, csfgets, and csfclose. They can but do not need to be of type FILE*.

Parameters:

csfgets: Read at most size - 1 characters from stream and store them into the buffer pointed to by s. Reading stops after an EOF or a newline is read. If a newline is read, it is stored in the buffer. A \0 is stored after the last character in the buffer. Return a non-negative number on success, or EOF on error. Only used for --cs-lock-csexe.
csfputs: Write the string s to stream, without its trailing \0. Return a non-negative number on success, or EOF on error.
csfopenappend: Open the file path for appending text at the end. Return a stream pointer that is later passed to csfputs or csfclose
csfopenread: Open the file path for reading. Return a stream pointer that is later passed to csfgets or csfclose. Only used for --cs-lock-csexe.
csfopenwrite: Open the file path for writing. Return a stream pointer that is later passed to csfputs or csfclose.
csfclose: Flush and close the stream. Return 0 if success, or EOF if error.
csremove: Remove filename from the file system. Return 0 if success, or EOF if error. Only used for --cs-lock-csexe.

These I/O functions have a default implementation:

char *csfgets(char *s, int size, void *stream) { return fgets(s, size, (FILE *)stream); }
int csfputs(const char *s, void *stream)       { return fputs(s, (FILE *)stream); }
void *csfopenappend(const char *path)          { return (void*)fopen(path, "a+"); }
void *csfopenread(const char *path)            { return (void*)fopen(path, "r"); }
void *csfopenwrite(const char *path)           { return (void*)fopen(path, "w"); }
int csremove(const char *path)                 { return remove(path); }
int csfclose(void *stream)                     { return fclose((FILE*)stream); }

Examples are available in Customizing I/O of CoverageScanner library.

C# library

CoverageScanner library is generated during the link process and enables the user to:

Generate the execution report.
Give a name to the executed tests.
Install a signal handler which saved the execution report on exit.

Additionally, CoverageScanner sets the preprocessor symbol __COVERAGESCANNER__ which excludes this function from a normal compilation.

`CoverageScanner.__coveragescanner_init()`

void CoverageScanner.__coveragescanner_init()

CoverageScanner.__coveragescanner_init() initializes explicitly the CoverageScanner library. Calling this function is only necessary on C# DLL which are not calling the static module initializer automatically.

`CoverageScanner.__coveragescanner_testname()`

void CoverageScanner.__coveragescanner_testname(string name)

CoverageScanner.__coveragescanner_testname() sets the name of the test which is currently being executed. It will be saved to the execution report and displayed in the Executions window (see Executions) when loaded in CoverageBrowser.

`CoverageScanner.__coveragescanner_teststate()`

void CoverageScanner.__coveragescanner_teststate(string state)

Set the state of the test which is currently being executed. The string parameter state can have the following values:

PASSED: the test was successfully executed.
FAILED: the test was not successfully passed.
INCIDENT: the test was not successfully executed (similar to failed).
CHECK_MANUALLY: it was not possible to determinate if the test was successfully executed.
SKIPPED: the test was skipped.

The values will be saved to the execution report and displayed in the Executions window (see Executions) when loaded in CoverageBrowser.

`CoverageScanner.__coveragescanner_add_html_comment()`

void __coveragescanner_add_html_comment(string comment)

Append a comment to the current execution. The comments need to follow the HTML syntax but only the body is parsed. The contents of the <HEAD> tag are ignored. This function can be called several times to append the content.

`CoverageScanner.__coveragescanner_clear_html_comment()`

void __coveragescanner_clear_html_comment()

Clear comments added using void __coveragescanner_add_html_comment(string comment).

`CoverageScanner.__coveragescanner_save()`

void CoverageScanner.__coveragescanner_save()

Save the execution report and resets the status of all instrumentations.

`CoverageScanner.__coveragescanner_clear()`

void CoverageScanner.__coveragescanner_clear()

Reset the status of all instrumentations.

`CoverageScanner.__coveragescanner_filename()`

void CoverageScanner.__coveragescanner_filename(string name)

Set the file name of the execution report. The extension .csexe is added automatically.

Note: Setting the execution report file name is necessary if the initialization function __coveragescanner_install() is not used.

`CoverageScanner.__coveragescanner_set_custom_io()`

void CoverageScanner.__coveragescanner_set_custom_io(
    __cs_fgets_delegate cs_fgets,
    __cs_fputs_delegate cs_fputs,
    __cs_fopenappend_delegate cs_fopenappend,
    __cs_fopenread_delegate cs_fopenread,
    __cs_fopenwrite_delegate cs_fopenwrite,
    __cs_fclose_delegate cs_fclose,
    __cs_remove_delegate cs_remove)

CoverageScanner writes the execution report (.csexe file) using the common C# file IO functions. For embedded systems, for example, it is necessary to use another way for recording it. For this reason, CoverageScanner provides CoverageScanner.__coveragescanner_set_custom_io(), which replaces the IO functions used by CoverageScanner.__coveragescanner_save().

Parameters:

csfgets:
public delegate string __cs_fgets_delegate(System.IO.Stream stream)

Read at most one less than size characters from stream and store them into the buffer pointed to by s. Reading stops after an EOF or a newline. If a newline is read, it is stored into the buffer. A \0 is stored after the last character in the buffer.
csfputs:
public delegate void __cs_fputs_delegate(string s, System.IO.Stream stream)

Write the string s to <stream>, without its trailing \0.
csfopenappend:
public delegate System.IO.Stream __cs_fopenappend_delegate(string path)

Open the file <path> for writing at the end.
csfopenread:
public delegate System.IO.Stream __cs_fopenread_delegate(string path)

Open the file <path> for reading.
csfopenwrite:
public delegate System.IO.Stream __cs_fopenwrite_delegate(string path)

Open the file <path> for writing.
csfclose:
public delegate void __cs_fclose_delegate(System.IO.Stream stream)

Flush and close the stream pointed to by <stream>.
csremove:
public delegate void __cs_remove_delegate(string path)

Remove path from the file system.

CoverageScanner command line arguments Controlling the instrumentation from the source code

Coco v7.2.1 ©2024 The Qt Company Ltd.
Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.