Menu

Squish Coco

Code Coverage Measurement for Tcl, QML, C# and C/C++

Part IV
CoverageScanner Reference

Chapter 8  Introduction

CoverageScanner is a C++ program that—in effect—replaces the usual compiler. It uses the native compiler’s preprocessor program to process the source code, then inserts instrumentation code into the preproecessed program, and at the end it compiles and links the project file, in the same way as in a normal build.

CoverageScanner’s instrumentation process consists of:

  1. declaring a static table that contains the of instrumentation results.
  2. generating a library which produces an execution report when the program terminates or receives a UNIX® signal or a Microsoft® Windows event.
  3. adding the instrumentation code itself for each relevant statement or Boolean expression.

The compiler, linker and preprocessor that are used are from the native environment (gcc, Visual Studio, etc.). The Squish Coco tools are used transparently and the developer has only to prepend ’cs’ to the name of the compiler executable to activate the code coverage1. For example, using ’csgcc’ instruments the source code and uses the ’gcc’ compiler to generate objects.

Another way to achieve coverage is to add a wrapper directory to the search path. It contains compiler wrappers with the same name as the native tools. They are disabled by default but can be switched on with help of the COVERAGESCANNER_ARGS environment variable.

8.1  Invoking CoverageScanner

CoverageScanner works like a pre-processor which calls after instrumenting a source file the native compiler (Microsoft® cl.exe, GNU g++, …).

Several invocation method are possible:

  1. Using the dedicated CoverageScanner executable for a specific compiler: CoverageScanner executable for a specific compiler is called to cs+’native compiler name’ or alternatively ’native compiler name’+-cs. (example: cl.exe is the Microsoft® C++ compiler and the corresponding CoverageScanner executable is cscl.exe or cl-cs.exe).

    CoverageScanner aims to work then as the native compiler with the difference that the code get instrumented.

    Example

    csg++ source.cpp -o application.exe
  2. Using CoverageScanner compiler wrapper and activating the instrumentation using --cs-on in the command line arguments:

    Squish Coco provides also a replacement of the native compiler called wrapper which extends its command line argument to support the code coverage feature. To use it it is necessary to add at the first position in the PATH variable the path of CoverageScanner wrapper. The instrumentation get activated, when adding --cs-on to the command line argument.

    Example

    export PATH=/opt/SquishCoco/wrapper/bin:$PATH
    g++ --cs-on source.cpp -o application.exe

    Or, without modifying globally the PATH variable:

    PATH=/opt/SquishCoco/wrapper/bin:$PATH g++ --cs-on source.cpp -o application.exe
  3. Using CoverageScanner compiler wrapper and activating the instrumentation through COVERAGESCANNER_ARGS environment variable:

    It is also possible to set the command line arguments of the wrapper using the COVERAGESCANNER_ARGS environment variable (see Chapter 9.1). In this case it is no longer necessary to modify the command line arguments.

    Example

    export PATH=/opt/SquishCoco/wrapper/bin:$PATH
    export COVERAGESCANNER_ARGS='--cs-on'
    g++ source.cpp -o application.exe

    Or, to instrument a complete project built using GNU make:

    COVERAGESCANNER_ARGS='--cs-on' PATH=/opt/SquishCoco/wrapper/bin:$PATH make all
  4. Using --cs-compiler command line option of CoverageScanner:

    --cs-compiler specifies which native compiler should be used. All other command line arguments, except those specific to CoverageScanner, are passed through to the native compiler.

    Example

    coveragescanner --cs-compiler=g++ source.cpp -o application.exe
The native compiler path needs to appear in the PATH variable, after the path to the compiler wrappers. This is necessary for finding the location of the native compiler after insertion of the instrumentation code.

Compiler support is done with the help of a profile. It contains declarations which make it possible to adapt CoverageScanner to C, C++ and C# preprocessors, compilers and linkers.

For a description of the compilers that are currently supported see Chapter 47. For a description of the profile syntax see Chapter 50

Chapter 9  Command Line Arguments

Syntax:

cscompiler⟩    [⟨cs-options⟩] ⟨compiler arguments
coveragescanner –cs-compiler=⟨STRING⟩ [⟨cs-options⟩] ⟨compiler arguments
coveragescanner –cs-profile=⟨STRING⟩  [⟨cs-options⟩] ⟨compiler arguments

where

compiler
One of the compilers supported by Squish Coco. Calling cscompiler⟩ results in a call of CoverageScanner as a wrapper of ⟨compiler⟩.
cs-options
One or more of the options that are described in the following sections.
compiler arguments
All the other options. They are copied to the command line of the compiler when it is called by CoverageScanner.

For the use of --cs-compiler and --cs-profile see Chapter 9.2.9.

The command line arguments are prioritized by their order in the command line: the latest entered option has a higher priority than the first one.

Examplecscl --cs-include=foo.h --cs-exclude=foo.h will exclude the header file foo.h from the coverage analysis.

9.1  Environment variables

CoverageScanner also reads options from the environment variable COVERAGESCANNER_ARGS. The options must be separated by spaces or tab characters (‘ ’ or ‘\t’). If both command line arguments are present and the variable COVERAGESCANNER_ARGS is set, the command line options take precedence over the options in the environment variable.

This variable should only be set temporarily, e.g. in a script, because otherwise it would influence all builds.

The location of the temporary files that CoverageScanner generates can be changed by setting the environment variable SQUISHCOCO_TEMP_DIR to the path to another directory (see Chapter 46.3).

9.2  List of options

9.2.1  Coverage methods

For a description of the coverage methods, see Part III.

--cs-off
Disable all code coverage analysis. CoverageScanner then calls the compiler or linker unchanged.
--cs-on
Enable code coverage analysis.

This is the default if CoverageScanner is called directly or as a wrapper that starts with cs, like csgcc. If the wrapper has however the same name as the program (e.g. gcc), code coverage is by default switched off.

--cs-off=pattern
Disable all code coverage analysis when compiling a source with an absolute file name that matches the wildcard expression ⟨pattern⟩ or if the string ⟨pattern⟩ is identical to a command line argument. CoverageScanner then calls the compiler or linker unchanged.
--cs-on=pattern
Enable all code coverage analysis when compiling a source with an absolute file name that matches the wildcard expression ⟨pattern⟩ or if the string ⟨pattern⟩ is identical to a command line argument.

It is possible to have several --cs-on=pattern⟩ and --cs-off=pattern⟩ options. The last option that is matching decides whether code coverage analysis is enabled or disabled.

If several sources are compiled with the same compiler command (as it occurs with C#), disabling the coverage analysis for one source file with --cs-off=pattern⟩ will disable the analysis for all others.
--cs-hit
Set the instrumentation mode to hit instrumentation. It then only matters whether an instrumentation point (a line, a condition or a block) was executed at least once, not how many times.
--cs-count
Set the instrumentation mode to count instrumentation. (Default)

With this mode, the number of times an instrumentation point is executed is counted.

--cs-statement-block
Enable statement block coverage.
--cs-decision
Enable statement block and decision coverage.
--cs-condition
Enable statement block, decision and condition coverage. (Default)
--cs-mcc
Enable Multiple condition coverage.
--cs-mcdc
Enable MC/DC coverage.
--cs-function
Enable function coverage. (Default)
--cs-no-function
Disable function coverage instrumentation.
--cs-line
Enable line coverage. (Default)

If this option is set, decision and condition coverage are automatically enabled too and full instrumentation mode (--cs-full-instrumentation) is switched on.

--cs-no-line
Disable line coverage. The other instrumentation modes that are automatically enabled by --cs-line are not disabled.
Summary of the effects of the options for coverage metrics

Most of the command line options that switch a certain coverage metric on also enable the data collection for other metrics. The following table shows which option enables which metrics.

Sometimes, the coverage measurements are also influenced by the option --cs-partial-instrumentation. For each of them, the table has two lines. The second line shows what happens when --cs-partial-instrumentation is present too. It is marked “(+partial)” in the table.

 FunctionLineStatementDecisionConditionMC/DCMCC
CoverageScanner Flags  Block    
--cs-statement-block     
--cs-decision   
--cs-decision (+partial)    
--cs-condition   
--cs-condition (+partial)    
--cs-mcc
--cs-mcdc

9.2.2  Fine-tuning of the instrumentation

--cs-no-exceptions
Do not instrument the catch block of a trycatch statement.
--cs-no-assignments
Do not instrument Boolean expressions in assignments.
--cs-no-execution-time
Disable the usage of performance measurements of the application to instrument. (By default, execution time measurement is enabled.)
--cs-execution-time
Enable the usage of performance measurements of the application to instrument.
--cs-no-function-profiler
Disable Squish Coco profiler.
--cs-function-profiler=option
Enable Squish Coco profiler. ’option’ can be on of the followings:
all
instrument all functions.
skip-trivial
Disable Squish Coco profiler for function having only one statement.
--cs-no-returns
Do not instrument Boolean expressions in return statements.
--cs-combine-switch-cases
With this option, decision and condition coverage do not distinguish between case labels that lead to the same code. This means that in the following code, the cases i == 3 and i == 4 are not distinguished. If the option is not set, the two cases are counted separately.
switch (i) {
    case 3:
    case 4:
       i = 0;
       break;
    ...
}
The option is valid for C++ and C#.
--cs-partial-instrumentation
Suppression of redundant conditions. Setting this option also disables line coverage.

The option influences the instrumentation of if statements without an else part, like

if (cond) {
    i += 1;
}

Without the option, an invisible else branch is created and its coverage is measured too. If the option is set, this is no longer done and the coverage of the case in which cond is false is no longer measured. The instrumented code then becomes slightly smaller, which may be necessary on small embedded systems.

--cs-full-instrumentation
No suppression of redundant conditions. (Enabled by default)
--cs-boost
Specific handling of Boost library constructs. Currently this only means that the code behind the macro BOOST_FOREACH is not instrumented. (Enabled by default.)
--cs-no-boost
No specific handling of Boost library constructs.
--cs-qt4
No instrumentation for class members generated by moc for the Qt4 and Qt5 libraries (Q_OBJECT, qt_metacall, qt_metacast, …) . The code behind the macro Q_FOREACH stays also uninstrumented. Qt signals remain instrumented. (Enabled by default.)
--cs-no-qt4
No specific handling of the Qt4 and Qt5 libraries.
--cs-qt3
No instrumentation for class members generated by moc for the Qt3 library (Q_OBJECT, className, tr, …). Qt signals remain instrumented. (Enabled by default.)
--cs-no-qt3
No specific handling of the Qt3 library.
--cs-no-annotations
No extraction of annotations (comments and manual validations) from the source files.
--cs-no-purecov-annotations
No extraction of purecov’s annotations from the source files.
--cs-vs2010-lambda
Instrument the expression in the return statement of a lambda function.

This brings a better support of lambda expression on Microsoft® Visual Studio® 2010. The option is only valid for C++11 compilers and Microsoft® Visual Studio® 2010. With a C compiler or an older C++ compiler, this option has no effect.

--cs-exit-function=function
Declare ⟨function⟩ as the name of an exit function.

An exit function is a command that ends the control flow in a function, like a return statement or the call of the exit() function, or a function that always throws an exception. Any code directly after such a statement is then unreachable. With this option, it is possible to inform Squish Coco that there are user-defined functions that have the same effect as exit().

The option can be repeated; then several exit functions are declared.

--cs-no-line-directive
Remove all #line directives from the code generated by the preprocessor for C++and C#.

The preprocessor is called by the CoverageScanner before instrumenting a file; afterwards the original compiler is called. On some systems, compiling a file this way causes problems that do not occur when the compiler is called directly. Removing the #line statements then sometimes helps.

--cs-counter-size=int
Size of the internal execution counters. Possible values are 1 (byte), 4 (32bit integer) or 8 (64bit integer). The counters are used inside the instrumented program to count the number of times an instrumentation point has been executed. Large internal counters prevent counter overflows, smaller counters may be necessary on small embedded systems to save space. The default value is 8.
--cs-mcc-max=size | --cs-mcdc-max=size
Set the maximal size of the instrumentation tables that are used for Multiple Condition coverage or MC/DC. The default for ⟨size⟩ is 8000.

For each decision, a truth table is generated under Multiple Condition coverage and MC/DC. ⟨size⟩ is the maximal number of lines in the table. If a decision requires a truth table that is longer than ⟨size⟩, Squish Coco falls back to condition coverage for that decision.

9.2.3  File and path inclusion

The following options specify which files are included in the code coverage. The options apply to files on the command line and to those that are specified on #include statements.

One can use wildcards and regular expressions. In contrast to the common usage, the ‘*’ in wildcard expressions matches also the path separation characters. The syntax of regular expressions is described in Section 9.4.

Options accumulate. If more than one of the file inclusion/exclusion option is present, the last one that matches a given file determines whether it is included or excluded.

In the next options, name of the file in question is first converted to an absolute path.

--cs-include-file-abs-wildcard=pattern
Include a file in the coverage analysis if its absolute path matches the wildcard expression ⟨pattern⟩.
--cs-exclude-file-abs-wildcard=pattern
Exclude a file from the coverage analysis if its absolute path matches the wildcard expression ⟨pattern⟩.

Example--cs-exclude-file-abs-wildcard=*.h excludes all files with the extension .h.

--cs-include-file-abs-regex=pattern
Include a file in the coverage analysis if its absolute path matches the regular expression ⟨pattern⟩.
--cs-exclude-file-abs-regex=pattern
Exclude a file from the coverage analysis if its absolute path matches the regular expression ⟨pattern⟩.

Example--cs-exclude-file-abs-regex=^.*\.h$ excludes all files with the extension .h.

--cs-include-path=path
Include all files in the directory ⟨path⟩ and its subdirectories in the coverage analysis. Wildcards or regular expressions cannot be used.

Example--cs-include-path=c:\include includes all files located in c:\include.

--cs-exclude-path=path
Exclude all files in the directory ⟨path⟩ and its subdirectories from the coverage analysis. Wildcards or regular expressions cannot be used.

Example--cs-exclude-path=c:\include excludes all files located in c:\include and its subdirectories.

Examples for complex inclusion patterns:

Relative paths

The following options refer to the name under which a file occurs in an #include statement or on the command line.

File paths and wildcard expression are converted to a canonical form which does not contain ‘.’, ‘..’, or a duplicated path separation character. (A ‘..’ at the beginning is however not removed.) On Microsoft® Windows, characters are also converted to lower case and every slash (‘/’) is replaced with a backslash (‘\’).

Regular expressions are untouched. It is e.g. necessary to ensure that they do not contain duplicated path separators.

--cs-include-file-wildcard=pattern
Include a file in the coverage analysis if its normalized path matches the wildcard expression ⟨pattern⟩.

Example--cs-include-file-wildcard=../include/*.h includes all files with the extension .h located in the directory ../include/ and its subdirectories.

--cs-exclude-file-wildcard=pattern
Exclude a file from the coverage analysis if its normalized path matches the wildcard expression ⟨pattern⟩.
--cs-include-file-regex=pattern
Include a file in the coverage analysis if its normalized path matches the regular expression ⟨pattern⟩.

Example--cs-include-file-regex=^\.\./include/[^/]*\.h$ includes all files with the extension .h located in ../include/.

--cs-exclude-file-regex=pattern
Exclude a file from the coverage analysis if its normalized path matches the regular expression ⟨pattern⟩.

Relative file names are computed relatively to the current working directory. For example, depending on the working directory one has to use different parameters in order to inhibit the instrumentation of a file src/test.c: If one is outside the directory src, one may use

$ csgcc src/test.c --cs-exclude-file-wildcard=src/test.c

but when switching to src, the parameters must change:

cd src
$ csgcc test.c --cs-exclude-file-wildcard=test.c
Setting inclusion/exclusion expressions on absolute paths should be preferred on complex build systems, since modern build system often change the current working directory. Working with absolute paths make it easier to set global rules for a project.

9.2.4  Function inclusion

--cs-include-function-wildcard=string
This command line option enables the user to include a function in the coverage analysis. The function name is specified using a wildcard expression and must include for C++ code the class name and namespace.

Example--cs-include-function-wildcard=C::* includes all members of the class C.

--cs-exclude-function-wildcard=string
This command line option enables the user to exclude a function from the coverage analysis. The function name is specified using a wildcard expression and must include for C++ code the class name and namespace.

Example--cs-exclude-function-wildcard=*::Get* excludes all members of any classes which starts with Get.

--cs-include-function-regex=string
This command line option enables the user to include a function in the coverage analysis. The function name is specified using a regular expression and must include for C++ code the class name and namespace. (see chapter 9.4 for the syntax)
--cs-exclude-function-regex=string
This command line option enables the user to exclude a function from the coverage analysis. The function name is specified using a regular expression and must include for C++ code the class name and namespace. (see chapter 9.4 for the syntax)

If more than one of these inclusion/exclusion option is present, the last one that matches a given function determines whether it is included or excluded.

The following option works indepentent of the previous ones:

--cs-record-empty-functions
Enable instrumentation of functions with an empty body. (By default this is disabled.)

9.2.5  Debugging

--cs-verbose-source-lines=int
Maximum number of source code lines dumped in an error message.
--cs-verbose=string
Generate verbose debug messages. Possible options are:
cmd
During the build, CoverageScanner displays the command line arguments of the programs it executes. This includes especially the command line arguments of the compiler when it translates the instrumented source code.
build
During the build, the instrumentation by CoverageScanner is traced. This includes e.g. the information about which files are instrumented and which are excluded from instrumentation.

This option automatically implies --cs-verbose=cmd.

api
When the instrumented program is run, the calls to the CoverageScanner library are traced.
By default, the output is written to stderr.
--cs-verbose-file=file
Define the file used for generating a CoverageScanner log file. This option has no effect when --cs-verbose is not used.
--cs-keep-instrumentation-files
Do not delete temporary instrumentation files. They will be left under random names in the Squish Coco temporary directory (see Chapter 46.3).
--cs-warnings=string
Instrumentation warning behaviour:
none
Warnings will not be displayed.
display
Warnings will be displayed via stderr.
error
Warnings will trigger a compilation error.
--cs-compilation-warnings=string
Compilation warning behaviour:
none
Warnings will not be displayed.
display
Warnings will be displayed via stderr.
error
Warnings will trigger a compilation error.
--cs-annotation-warnings=string
Source code annotations warning behaviour:
none
Warnings will not be displayed.
display
Warnings will be displayed via stderr.
error
Warnings will trigger a compilation error.

9.2.6  Execution report

--cs-output=string
Set the file name for the execution report. The extension .csexe is added automatically.

By default, ⟨string⟩ has the value “%F” and CoverageScanner uses the application name without the path as name for the .csexe file.

The value of ⟨string⟩ may be an absolute path, like “/my/dir/%F”. The directories in this path must already be present when the instrumented program runs, since CoverageScanner does not create them by default.1 Otherwise, ⟨string⟩ is interpreted as a path relative to the working directory at the time the program starts.

string⟩ may contain several format specifiers. The values of the following specifiers are computed at compile time:

%T
Current local time as an integer. (Example: 163355 for 16h33 and 55s)
%D
Current local date as an integer. (Example: 20140130 for January 30, 2014)
%F
Application/library file name without path.
%A
Absolute application/library file name.
%B
Application/library file name without path and extension.
%P
Application/library file path.
%/
File path separator (on Unix a slash, ‘/’, and on Windows a backslash, ‘\’).

The values of the following format specifiers are computed at runtime:

%c
Current working directory. The value is is computed before the main() function is started. If the current working directory changes, this path remains identical.
%p
Process identifier. If for any reason it cannot be computed, “%p” will be replaced with an empty string.
%t
Current local time. If for any reason it cannot be computed, “%t” will be replaced with an empty string.
%d
Current local date. If for any reason it cannot be computed, “%d” will be replaced with an empty string.
<X>
Replace “<X>” with the content of the environment variable “X”.
--cs-file-name-format-specifier
Enable the file format specifiers support.
--cs-no-file-name-format-specifier
Disable the file format specifiers support.
--cs-lock-csexe
Create a lock file which lock the access of the .csexe file during its generation.
--cs-nolock-csexe
Inverse option to --cs-lock-csexe. The preprocessor output is transmitted to CoverageScanner through a temporary file.
--cs-dump-on-signal=signal
Generate an execution report when a specific signal was received. The signal can be specified by a number from 1 to 63, or by the conventional signal name, like SIGINT, SIGTERM, etc. (see Chapter 37.1).
--cs-dump-on-event=string
Generate an execution report when a specific Microsoft® Windows event was received (see Chapter 37.2).
--cs-trigger-function=triggerfunction
Make that at the end of each call of ⟨triggerfunction⟩, coverage data will be saved. This switch may be repeated to handle more than one trigger function.

function⟩ is specified according to the C++ convention. This means that A::foo stands for the function foo insider the A namespace or class. By default, the save function that is called when ⟨triggerfunction⟩ runs is __coveragescanner_save(), but it can be changed with the following switch.

--cs-coverage-save-function=savefunction
Set the custom function that is inserted by --cs-trigger-function.

savefunction⟩ must be a function without parameters, since it replaces __coveragescanner_save(). Squish Coco automatically inserts a declaration for ⟨savefunction⟩ at the beginning of each source file. This makes it possible to define ⟨savefunction⟩ in a file that is compiled with --cs-custom-library-source (see Section 9.2.8).

9.2.7  Command line modification

--cs-compiler-option=option
Add ⟨option⟩ to the end of the compiler command line when compiling the instrumented code. When code coverage is disabled, nothing happens. The option can be repeated if more than one option is needed.
--cs-libgen=option
Put an additional command line option to the compiler call which generates the code coverage library. The option can be repeated if more than one option is needed.

The options are appended and become the content of $LIBGEN$, a variable that may occur in the replacement text for the profile option COMPILER_CMD (see Chapter 50.4).

--cs-library-after=option
Put the linker argument for the CoverageScanner library after a specified option.

If used in the form “--cs-library-after=-lmylib”, the linker parameter for the CoverageScanner library will be inserted directly after the option -lmylib.

--cs-library-at-start
Add the linker argument for the CoverageScanner library before all other command line options.
--cs-library-at-end
Add the linker argument for the CoverageScanner library after all other command line options.

9.2.8  Generated code

--cs-no-csharp-dynamic
If set, the C# dynamic type is not used in the instrumentation code generated by Squish Coco.

With the dynamic type, Squish Coco can better handle Boolean expressions that contain non-Boolean objects with overloaded true and false functions. Dynamic types are however only available for Microsoft® Visual Studio® 2010 and later; for earlier C# versions, this option is needed.

--cs-csharp-dynamic
If set, the C# dynamic type is used in the instrumentation code generated by Squish Coco.
--cs-enable-coveragescanner-library-abs-wildcard=string
Enable the generation of the CoverageScanner library when the absolute file name of the generated binary matches the given wildcard expression.
--cs-disable-coveragescanner-library-abs-wildcard=string
Disable the generation of the CoverageScanner library when the absolute file name of the generated binary matches the given wildcard expression.
--cs-pointer-type=string
Type which can be used to cast a pointer to an integer. This might be ’int’ or ’long long’ depending of the target platform.
--cs-memory-pool=int
Generate a CoverageScanner library which uses a memory pool bytes instead of calling malloc()/cfunctionfree. The size of the pool is ⟨int⟩ bytes. This option is useful only for operating systems which do not support dynamic memory allocation.
--cs-memory-pool-code=string
Declaration code for the memory pool. This is optional and permits a custom declaration of the array containing the head used by the CoverageScanner library. The default implementation is a static array of character declared as followings: static char %S[%I]. The following placeholder are available:
%S
the symbol name for the custom heap.
%I
the heap size in bytes.
--cs-memory-alloc-failure-function=string
C-function name which is called when a malloc() call fails. The prototype of the function should be ’void func(int size)’ and should not return. The parameter size is the requested memory size passed as argument of the malloc() function. This permits to catch an out of memory issue of the CoverageScanner’s code through a custom function.
--cs-link-instrumentation-tables
Chain all instrumentation tables at link time and not at run time. (This is the default.)

The instrumentation tables are internal arrays generated by Squish Coco which contain the counter variables for code coverage.

--cs-register-instrumentation-tables
Chain all instrumentation tables at run time and not at link time. This option has an effect only on platforms for which the profile parameter INSTRUMENTATION_TABLES_LINKED_DURING_RUNTIME_SUPPORT (see Chapter 50.4) has the value “Yes”.
--cs-dotnet-exit-handler
Specific handling of .NET Core exit. This lets you save the execution report event if Environment.Exit is called.
--cs-no-exit-handler-installation
Disable the automatic installation of the handler which saves the code coverage report. If this handler is not installed, no executions report will be generated when the application exits or when a custom signal or Windows event is received. Call __coveragescanner_install() to install the handler manually.
--cs-minimal-api
With this command line option, a CoverageScanner API is generated that has fewer dependencies to external libraries than the default API. This may be necessary for embedded systems or when compiling a C# application with the command line switch /noconfig.
--cs-custom-library-source=file
Compile ⟨file⟩ as an additional source. The object code for ⟨file⟩ is then linked to the code of the program.

The option has an effect only for the instrumentation of C or C++ programs. The code in ⟨file⟩ must then be written in the same language.

This is to include larger pieces of code into the instrumented code for a program without the need to change the sources of the program. The result is that code in the program can use the functions defined in ⟨file⟩. But note that the new functions still need to be declared in the source files that use them.

When however ⟨file⟩ is used to define the ⟨savefunction⟩ that is set by --cs-coverage-save-function=savefunction⟩ (see Section 9.2.8), an explicit declaration is not necessary.

9.2.9  Miscellaneous

--cs-compiler=string
This command option enables the user to select a profile. This option does not normally need to be specified, due to the fact that the profile name is usually extracted from the command line name. (cscl.exe implicitly selects the profile cl.cspro)

Example--cs-compiler=cl selects the profile ’cl.cspro’.

--cs-profile=string
This option sets the path of CoverageScanner profile. Using this option is not compatible with --cs-compiler.

Example--cs-profile=%SQUISHCOCO%\cl.cspro is equivalent to --cs-compiler=cl on Microsoft® Windows.

--cs-architecture=string
Internal option to specify the target architecture. It sets the variable $ARCHITECTURE$ in the replacement text for the profile parameter PREPROCESSOR_CMD (see Chapter 50.3). The target architecture is also used to select alternate profile parameters (see Chapter 50).
--cs-parallel-build=int
Maximum number of concurrent code generation/compilation.
--cs-cpp-ext=list
List of file extensions corresponding to C++ files (ex: .cpp,.cxx)
--cs-c-ext=list
List of file extensions corresponding to C files (ex: .c)
--cs-native-toolchain=string
Adds a directory in the search path of the native compiler. This command can be repeated. In this case the first one is the preferred location.
--cs-option-file=file
Specify command line options from a file. The file may contain all valid CoverageScanner command line options and the command line options of the native tool. It must contain one argument per line. Leading and trailing spaces are removed and empty lines are ignored, but no other input processing is done. The option can be repeated.
--cs-file-name-lower-case
Convert absolute file names to lower case. (For backward compatibility with the version 4.1)
--cs-no-pch
If set, precompiled headers are deactivated during the compilation.
--cs-no-pch=pattern
Disable the precompiled header usage when compiling a source with an absolute file name that matches the wildcard expression ⟨pattern⟩ or if the string ⟨pattern⟩ is identical to a command line argument.
--cs-no-cspch
If set, the files with the extension .cspch are not generated. This files are only used to enhance the compilation speed when using precompiled headers.
--cs-squish
Enable the automatic Squish integration. (Default).
--cs-no-squish
Disable the automatic Squish integration.

9.3  Instrumenting using preprocessor symbols

CoverageScanner also activates the instrumentation if some symbols are present in the command line option. This allows you to instrument code from an IDE which does not permit adding custom command line options to the compiler or linker.
Example: Defining COVERAGESCANNER_COVERAGE_ON is equivalent of adding --cs-on to the command line.

Preprocessor symbolEquivalence
COVERAGESCANNER_RUNTIME_LOG--cs-verbose=api
COVERAGESCANNER_KEEP_INSTRUMENTATION_FILES--cs-keep-instrumentation-files
COVERAGESCANNER_VERBOSE--cs-verbose=build
COVERAGESCANNER_DUMP_ON_EVENT--cs-dump-on-event=Global\COVERAGE
COVERAGESCANNER_COVERAGE_ON--cs-on
COVERAGESCANNER_COVERAGE_OFF--cs-off
COVERAGESCANNER_COVERAGE_HIT--cs-hit
COVERAGESCANNER_COVERAGE_COUNT--cs-count
COVERAGESCANNER_COVERAGE_BASIC_BLOCK--cs-statement-block
COVERAGESCANNER_COVERAGE_DECISION--cs-decision
COVERAGESCANNER_COVERAGE_CONDITION--cs-condition
COVERAGESCANNER_COVERAGE_MCC--cs-mcc
COVERAGESCANNER_NO_CSHARP_DYNAMIC--cs-no-csharp-dynamic
COVERAGESCANNER_NO_LINE_DIRECTIVE--cs-no-line-directive
COVERAGESCANNER_CSHARP_DYNAMIC--cs-csharp-dynamic
COVERAGESCANNER_COVERAGE_LOCK_CSEXE--cs-lock-csexe
COVERAGESCANNER_COVERAGE_NOLOCK_CSEXE--cs-nolock-csexe
COVERAGESCANNER_COVERAGE_PARTIAL_INSTRUMENTATION--cs-partial-instrumentation
COVERAGESCANNER_COVERAGE_FULL_INSTRUMENTATION--cs-full-instrumentation
COVERAGESCANNER_COVERAGE_NO_EXCEPTIONS--cs-no-exceptions
COVERAGESCANNER_COVERAGE_NO_ASSIGNMENTS--cs-no-assignments
COVERAGESCANNER_MINIMAL_API--cs-minimal-api
COVERAGESCANNER_COVERAGE_COMBINE_SWITCH_CASES--cs-combine-switch-cases
COVERAGESCANNER_OUTPUT_ABS--cs-output=Global\%A
COVERAGESCANNER_PROFILER_ALL--cs-function-profiler=all
COVERAGESCANNER_PROFILER_SKIP_TRIVIAL--cs-function-profiler=skip-trivial
COVERAGESCANNER_DOTNET_EXIT_HANDLER--cs-dotnet-exit-handler

9.4  Regular Expressions

Regular expressions are composed of items (see table 9.1 for the full list) and combining operators. These can be:

ElementDescriptionEquivalenceReverse Element
^The caret marks the beginning of the string. For example, ^c: will only match file names with an absolute path on the drive C:. If you wish to match a literal ^ you must escape it by writing \^.  
$The dollar marks the end of the string. For example \.cpp$ will match every C++ file name. If you wish to match a literal $ you must escape it by writing \$.  
\<Match the start of a word.  
\>Match the end of a word.  
.Any character  
\ Escape character. Example\. corresponds to the character ’.’ and not any character  
\mAlphanumeric character[0-9a-zA-Z]\M
\aAlphabetic character[a-zA-Z]\A
\bBlank character[ \t]\B
\cControl character \C
\dDigit[0-9]\D
\gPrintable character except space[]\G
\lLower-case character[a-z]\L
\pPrintable character \P
\nPrintable character except space or alphanumeric character \N
\sWhite-space characters (space, form-feed , newline , carriage return , horizontal tab and vertical tab)[ \f\n\r\t\v]\S
\uUppercase letter[A-Z]\U
\xHexadecimal digits[0-9a-fA-F]\X
\wAlphanumeric character or underscore[0-9a-zA-Z_]\W
Table 9.1: Non ASCII Regular Expression Items

Chapter 10  Library calls

10.1  C and C++ Library

The CoverageScanner library is generated during instrumentation and enables the user

  1. to initialize the measurement system and select the name of the .csexe file,
  2. to install a handler which saves the execution report on exit,
  3. 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,
  4. to handle dynamically loaded libraries, and
  5. to 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.

10.1.1  __coveragescanner_install()

Syntax:

void __coveragescanner_install(const char *appname)
This function is not needed for gcc, clang or Microsoft® Visual Studio®.

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(argc,char *argv[])
{
#ifdef __COVERAGESCANNER__
  __coveragescanner_install(argv[0]);
#endif
  ...
}
Platform dependencies

With gcc, clang or Microsoft® 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 Chapter 50).

10.1.2  __coveragescanner_testname()

Syntax:

void __coveragescanner_testname(const char *name)

Set the name of the current test. It will be saved in the execution report and be displayed in the "Executions" window (see Chapter 19.1) 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”.

This and the following functions until __coveragescanner_save() are especially intended for the use with unit test frameworks (see Chapter 34).

10.1.3  __coveragescanner_teststate()

Syntax:

void __coveragescanner_teststate(const char *state)

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

"PASSED"
to indicate that the test was successful.
"FAILED"
to indicate that the test was not successful.
"INCIDENT"
to indicate that the test was not successful. (similar to failed)
"CHECK_MANUALLY"
to indicate that it was not possible to determine whether the test was successful.
"SKIPPED"
to indicate that 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 Chapter 19.1) when the .csmes file is loaded into CoverageBrowser.

10.1.4  __coveragescanner_add_html_comment()

Syntax:

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>”.

10.1.5  __coveragescanner_clear_html_comment()

Syntax:

void __coveragescanner_clear_html_comment()

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

10.1.6  __coveragescanner_save()

Syntax:

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.

10.1.7  __coveragescanner_clear()

Syntax:

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.

10.1.8  __coveragescanner_filename()

Syntax:

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 Chapter 50).

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

10.1.9  __coveragescanner_get_filename()

Syntax:

const char * __coveragescanner_get_filename()

Function which returns the ’.csexe’ file name.

10.1.10  __coveragescanner_register_library()

For the use of this and the following function, see Chapter 33.

Syntax:

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.
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 Chapter 50).

10.1.11  __coveragescanner_unregister_library()

Syntax:

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() (Microsoft® 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.

10.1.12  __coveragescanner_register_squish()

Syntax:

void __coveragescanner_register_squish()

Try to register the instrumented application with Squish. This makes most of the Squish 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.

10.1.13  __coveragescanner_set_custom_io()

Syntax:

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 *fp),
    int (*csremove)(const char *filename) )

Define your own set of I/O functions.

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.
csfputs
Write the string s to stream, without its trailing ’\0’.
csfopenappend
Open the file path for appending text at the end.
csfopenread
Open the file path for reading.
csfopenwrite
Open the file path for writing.
csfclose
Flush and close the stream pointed to by fp.
csremove
Remove the file filename from the file system.

By default, CoverageScanner writes the execution report (the .csexe file) to the file systems 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 I/O functions used by __coveragescanner_save().

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 *filename)             { return remove(filename); }
int csfclose(void *fp)                         { return fclose((FILE*)fp); }

Examples are available in Chapter 38.

10.2  C# Library

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

  1. Generate the execution report.
  2. Give a name to the executed tests.
  3. 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.

10.2.1  CoverageScanner.__coveragescanner_init()

Syntax:

void CoverageScanner.__coveragescanner_init()

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

10.2.2  CoverageScanner.__coveragescanner_testname()

Syntax:

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 is displayed in the "Executions" window (see Chapter 19.1) when the loaded in CoverageBrowser.

10.2.3  CoverageScanner.__coveragescanner_teststate()

Syntax:

void CoverageScanner.__coveragescanner_teststate(string state)

CoverageScanner.__coveragescanner_teststate() sets the state of the test which is currently being executed. The string parameter state can have the following values:

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

It will be saved to the execution report and is displayed in the "Executions" window (see Chapter 19.1) when the loaded in CoverageBrowser.

10.2.4  CoverageScanner.__coveragescanner_memory_pool_stat()

Syntax:

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

__coveragescanner_memory_pool_stat() permits to 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 makes only sense in the case of using a memory pool.

10.2.5  CoverageScanner.__coveragescanner_add_html_comment()

Syntax:

void __coveragescanner_add_html_comment(string comment)

__coveragescanner_add_html_comment() append a comment to the current execution. The comments needs to follow the HTML syntax but only the body is parsed. (The contents of the “<HEAD>” tag is ignored). This function can be called several times, in this case the content is appended.

10.2.6  CoverageScanner.__coveragescanner_clear_html_comment()

Syntax:

void __coveragescanner_clear_html_comment()

__coveragescanner_add_html_comment() clear comments added using void __coveragescanner_add_html_comment(string comment).

10.2.7  CoverageScanner.__coveragescanner_save()

Syntax:

void CoverageScanner.__coveragescanner_save()

CoverageScanner.__coveragescanner_save() saves the execution report and resets the status of all instrumentations.

10.2.8  CoverageScanner.__coveragescanner_clear()

Syntax:

void CoverageScanner.__coveragescanner_clear()

CoverageScanner.__coveragescanner_clear() resets the status of all instrumentations.

10.2.9  CoverageScanner.__coveragescanner_filename()

Syntax:

void CoverageScanner.__coveragescanner_filename(string name)

this function sets the file name of the execution report. The extension ’.csexe’ is added automatically.

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

10.2.10  CoverageScanner.__coveragescanner_set_custom_io()

Syntax:

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)

Parameters:

csfgets
Type:public delegate string __cs_fgets_delegate(System.IO.Stream stream)
csfgets reads in at most one less than size characters from stream and stores 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
Type:public delegate void __cs_fputs_delegate(string s, System.IO.Stream stream)
csfputs writes the string s to stream, without its trailing ’\0’.
csfopenappend
Type:public delegate System.IO.Stream __cs_fopenappend_delegate(string path)
csfopenappend open the file path for writing at the end.
csfopenread
Type:public delegate System.IO.Stream __cs_fopenread_delegate(string path)
csfopenread open the file path for reading.
csfopenwrite
Type:public delegate System.IO.Stream __cs_fopenwrite_delegate(string path)
csfopenwrite open the file path for writing.
csfclose
Type:public delegate void __cs_fclose_delegate(System.IO.Stream fp)
The csfclose function will flush and close the stream pointed to by fp.
csremove
Type:public delegate void __cs_remove_delegate(string n)
csremove removes filename from the file system.

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

Chapter 11  Controlling the instrumentation from the source code

Sometimes it is necessary to apply CoverageScanner settings only to certain regions of the source code, e.g. to exclude parts of a file from instrumentation.

Several methods to do this are described in this chapter.

11.1  Annotations

Source code annotations are specific comments which let you select source code parts to validate. Two kinds of annotations exist:

Comments
Comments are simple code comments which can be used for giving advice to the tester. They do not have any impact on the code coverage
Manual Validations
Manual validations indicate that some lines of code should be considered as validated. Manual validations have the same effect on code coverage as executing the source lines.

Source code annotations can directly be edited with CoverageBrowser or generated by writing specific comments into the source code.

11.1.1  Comments

To generate comments for a single source line it is only necessary to start a C or C++ comment with the keyword “coco:comment⟩”. This will insert a comment for all instrumentations in the current line.

Example: In the following example, the comment “To test the failure, change the current working directory to a read-only directory” will be added to the instrumentations of the line 4.

   1 void write_log( const char *text )
   2 {
   3    FILE * f = fopen( "log.txt", "a+" );
   4    if ( f ) /* coco: To test the failure,
   5                      change the current working
   6                      directory to a read-only directory */

   7    {
   8        fputs( text, f ):
   9        fclose( f );
  10    }
  11 }

Comments can also be generated for multiples source lines using the keywords “coco begin:comment⟩” and “coco end”.

Example: In the following example, the comment “To test the failure, change the current working directory to a read-only directory” will be added to the instrumentations of the lines of the function write_log().

   1 void write_log( const char *text )
   2 {
   3    /* coco begin:  To test the failure,
   4                    change the current working
   5                    directory to a read-only directory */

   6    FILE * f = fopen( "log.txt", "a+" );
   7    if ( f )
   8    {
   9        fputs( text, f ):
  10        fclose( f );
  11    }
  12    /* coco end */
  13 }

11.1.2  Manual Validation

Manually validated instrumentation can be generated with a comment in the code that starts with the keywords “coco validated: comment⟩”. The ⟨comment⟩ will later occur in the coverage report. To validate a multi-line region of code, one can use the keywords “coco begin validated: comment⟩” and “coco end”. In order to be compatible with PureCoverage adjustments, CoverageScanner also recognizes “purecov:” line comments with the keywords “inspected” or “tested”, or alternatively “begin inspected”/“begin tested” and “end inspected”/“end tested” for multi-line annotations.

Example: In the following example, the comment “This function does not need to be tested, only used for debugging.” will be added to the instrumentations of the function write_log().

   1 void write_log( const char *text )
   2 {
   3    // coco begin validated: This function does not need to be tested, only used for debugging.
   4    FILE * f = fopen( "log.txt", "a+" );
   5    if ( f )
   6    {
   7        fputs( text, f ):
   8        fclose( f );
   9    }
  10 }
  11 // coco end

Note that the “coco end” comment is placed after the end of the function. This is because Coco measures code coverage of a function at its very end, there where the final closing brace is located. When we want to mark a complete function a covered, we need to include the last closing brace in the region between the manual validation comments.

Including the function header by placing the “coco begin” comment in front of the function is however not important.

11.2  C and C++ Pragmas

CoverageScanner defines C and C++ pragmas to control the instrumentation during the compilation. All control pragmas are handled in a stack: They are valid until the end of the source file or until a #pragma CoverageScanner(pop) is encountered.

The pragmas have the following syntax:
#pragma CoverageScanner ( string )
or: __pragma ( CoverageScanner ( string ) )
or: _Pragma ( "CoverageScanner ( string )" )

List of supported pragmas:

#pragma CoverageScanner(cov-on)
Enable code coverage instrumentation.
#pragma CoverageScanner(cov-off)
Disable code coverage instrumentation.
#pragma CoverageScanner(cov-hit)
Instruments using code coverage hit.
#pragma CoverageScanner(cov-count)
Instruments using code coverage count.
#pragma CoverageScanner(cov-statement-block)
Select statement block coverage as instrumentation method.
#pragma CoverageScanner(cov-decision)
Select decision coverage as instrumentation method.
#pragma CoverageScanner(cov-condition)
Select condition coverage as instrumentation method.
#pragma CoverageScanner(cov-partial-instrumentation)
Partial instrumentation of conditions and decisions.
#pragma CoverageScanner(cov-full-instrumentation)
Full instrumentation of conditions and decisions.
#pragma CoverageScanner(cov-assignment-on)
Instrument Boolean expressions in assignments.
#pragma CoverageScanner(cov-assignment-off)
Do not instrument Boolean expressions in assignments.
#pragma CoverageScanner(cov-return-on)
Instrument Boolean expressions in return statements.
#pragma CoverageScanner(cov-return-off)
Do not instrument Boolean expressions in return statements.
#pragma CoverageScanner(cov-switch-case-off)
Do not instrument all cases of a switch statement.
#pragma CoverageScanner(cov-switch-case-on)
Instrument all cases in a switch statement.
#pragma CoverageScanner(pop)
Restore the instrumentation options from before the call of the latest CoverageScanner pragma.

11.3  C# regions

CoverageScanner defines C# extensions of the #region keyword which, at compile-time, controls the generation of the instrumentation. The #region extension has the following syntax:
#region CoverageScanner ( string )

The keyword #endregion restores the generation options.

List of supported regions:

#region CoverageScanner(cov-on)
Enable code coverage instrumentation.
#region CoverageScanner(cov-off)
Disable code coverage instrumentation.
#region CoverageScanner(cov-hit)
Instrument using code coverage hit.
#region CoverageScanner(cov-count)
Instrument using code coverage count.
#region CoverageScanner(cov-statement-block)
Select statement block coverage as instrumentation method.
#region CoverageScanner(cov-decision)
Select decision coverage as instrumentation method.
#region CoverageScanner(cov-condition)
Select condition coverage as instrumentation method.
#region CoverageScanner(cov-partial-instrumentation)
Partial instrumentation of conditions and decisions.
#region CoverageScanner(cov-full-instrumentation)
Full instrumentation of conditions and decisions.
#region CoverageScanner(cov-assignment-on)
Instrument Boolean expressions in assignments.
#region CoverageScanner(cov-assignment-off)
Do not instrument Boolean expressions in assignments.
#region CoverageScanner(cov-switch-case-off)
Do not instrument all cases in a switch statement.
#region CoverageScanner(cov-switch-case-on)
Instrument all cases in a switch statement.
email squish@froglogic.com