Capturing Code Coverage Data |
VIRTUAL MACHINE |
 |
|
Capturing Code Coverage Data |
VIRTUAL MACHINE |
|
Trail: PROIV Documentation > Developer > PROIV Developer > Code Coverage > Capturing Code Coverage Data
A pre-requisite to using code coverage is enabling the generation of additional information during builds. If this is not done then the code coverage data will have little value. Please ensure you have followed those instructions.
The capturing of the code coverage data is performed by the Virtual Machine as functions (screens, reports and updates) are executed. It counts events with attached logic firing and monitors the execution of instructions in compiled logics. The additional code coverage information allows the Virtual Machine to map the execution of these instructions back to the logic source.
Code coverage capture works at the session level. So there could be two sessions (different operators) where one is capturing code coverage and the other isn't. The one capturing code coverage will not include any functions executed by the other.
The code coverage capture can be configured and/or enabled via the PROIV Dashboard. This includes switches for generating the additional information during builds, capturing data and the ".p4cc" filenames used (see Getting Started page). These provide the initial settings that all sessions will use. Unless the code coverage is explicitly stopped (see next section) then the code coverage is saved when sessions end.
The code coverage capture can also be configured and/or enabled via the Session object in a PROIV logic. The properties / methods relating to code coverage are:
The most important is "Session.CodeCoverage" which / enables disables the code coverage. The
remaining methods control the saving of the code coverage data and have default values / behaviours.
When code coverage is enabled, using "Session.CodeCoverage = True", then subsequent executed functions
will have code coverage captured. It will not apply to the function currently executing i.e. the one that switched
on the code coverage. The reason for this is that functions must be started by the Virtual Machine with
additional instrumentation in place. It's too late for the currently executing function.
If using the Session object, the recommended practice is not to enable code coverage in the on entry logic of the functions you want to test. Instead write a simple update function (without files) that configures and enables the code coverage in its on entry event. Run this first and then start the function(s) you want to want to test. Alternatively you could set the "Exit Link Function" in the properties list of your update function (for non-global) or use GLOBAL_LSCALL (for global) to automatically invoke the function you want to test.
The outcome of the capture stage are ".p4cc" files containing code coverage data. These files are not intended to be
human-readable but to be consumed by later stages. The format of the file name is:
"<prefix>_<process-id>_<YYYYMMDD>T<HHMMSS>.p4cc" where:
prefixthe prefix of the filename.
process-idthe process ID of the virtual machine performing the code coverage capture.
YYYYMMDDthe four-digit year, two-digit month and two-digit day of the month on which the capture began e.g. 20230116 for the 16th of January 2023.
HHMMSSthe two-digit (24-)hour, two-digit minute and two-digit second on which the capture began e.g. 142836 for twenty-eight minutes past two PM and thirty-six seconds.
The file contains the timestamp of when code coverage capture started in its name. Inside the file is a timestamp of when code coverage capture ended. The directory the file is saved in can be specified explicitly.
The code coverage capture data is automatically saved when:
code coverage capture is disabled using "Session.CodeCoverage = False";
the current session ends;
the configuration of the file (e.g. prefix) changes;
an interval to periodically save at has been specified using
"Session.CodeCoverageSaveInterval".
If the configuration of the file changes (e.g. different prefix, directory path, tag etc) while code coverage capture is enabled then all the existing captured data is saved to the previous filename, the captured data is reset, and newly captured data is saved under the new filename.
If you specify a custom directory to save the code coverage captured data (".p4cc") files into then it is assumed PROIV will have the correct permissions to write into it. If this is not the case then an error will be generated and code coverage capture data will be lost. If the file is being saved at the end of a session then it is not possible to show an error and the only record of the failure is in the PROIV trace file.
The directory to save the ".p4cc" files under can be specified by both the PROIV Dashboard and the Session object. It is recommended to set the directory via the PROIV Dashboard as the code coverage analytics accessed via the PROIV Dashboard is only aware of this setting. Setting the directory via the Session object is for more advanced use cases.
Topic ID: 700080