This document covers the following topics:
The Natural Code Coverage is used to monitor the executed statements of a Natural application. It helps application programmers, administrators and quality engineers to analyze the code coverage of Natural applications and to investigate the coverage results in more detail with the Natural Source Editor.
A Natural Code Coverage analysis can be performed for finding unused or "dead" code in the Natural Application. This technique is typically used with automated testing. After having identified testing leaks with the Natural Code Coverage tool, quality engineers can add new or extend existing unit tests to finally get a better code coverage result.
The following is a quick description of how Natural Code Coverage could be used.
In general, coverage data is collected in Natural batch runs. The data is written to a Natural resource file and viewed in NaturalONE. However, in a Linux or Windows environment, coverage may also be performed from NaturalONE as described below.
To use Code Coverage in Linux or Windows environments
Create a project containing the application sources using the command Add to New Project.
Or:
Create a project containing the application sources via
checkout from subversion.
Set the parameters required for Code Coverage in the Session parameters field of the Natural runtime properties of the project:
GPGEN=(COVERAGE=ON)
COVERAGE=(ACTIVE=ON,RESLIB=MYLIB,RESNAME=MYRES)
Build the Natural application.
With GPGEN=(COVERAGE=ON) the Natural GP
information gets instrumented in the Natural environment to be used for code
coverage..
Issue the command Run As > Natural application.
Or:
Press ALT+SHIFT+X, N.
Or:
With the parameter
COVERAGE=(ACTIVE=ON,RESLIB=MYLIB,RESNAME=MYRES), Natural code
coverage analysis is done while the application is running and the result of
this analysis is written to a resource file
MYRES.ncvf in library
MYLIB.
Issue the command Add to Existing Project on the coverage resource file to add it to the NaturalONE project created in Step 1.
Select the code coverage resource file and issue the command Open with Natural Code Coverage.
The Code Coverage view is opened and shows the result of the code coverage analysis.
Double-click on the code covered Natural sources or use the Edit command from the context menu to open the code covered Natural sources.
The Source Editor is opened and all lines executed for this object are displayed with a green background.
To use Code Coverage in mainframe environments
Add the Profiler utility COVERAGE and START functions
to the Natural batch job to start the code coverage data collection.
Open the NCVF resource in NaturalONE to obtain the Code Coverage view.
From the Code Coverage view you can directly edit the source. The editor shows all lines containing covered statements with a green background.
Note:
It is not possible to start the code coverage from NaturalONE when you run
against a mainframe. NaturalONE is used to display the coverage data collected in
the mainframe batch job.
For more information regarding the Natural code coverage of Natural batch applications on the mainframe, refer to the Profiler and Code Coverage section of the Utilities documentation, which is part of your respective Natural documentation.
If you want to use the Natural Code Coverage in a Linux or Windows environment, Natural Version 8.4.1 or above is required on the server.
The programs to be code covered must have been cataloged with the Natural parameter
GPGEN=(COVERAGE=ON). The GPGEN parameter is described in detail in the
Parameter Reference section of the Natural documentation
corresponding to your platform.
To activate Natural Code Coverage at runtime the COVERAGE parameter must be set to
active: COVERAGE=(ACTIVE=ON). The COVERAGE parameter is described in
detail in the Parameter Reference section of the Natural
documentation corresponding to your platform.
At end of application execution, a code coverage result file with the extension .ncvf is written.
By default, mainframe resource files are not shown in NaturalONE. If you want to get access to the .ncvf file, you have to enable the display of the resource files in your Natural Development Server environment.
For more information regarding resources and the Natural code coverage of Natural batch applications on the mainframe, refer to the Natural Profiler and Code Coverage section of the Utilities documentation, which is part of the Natural documentation for Mainframes.
To use the Natural Code Coverage with a Natural program in a
Windows or Linux environment, you must first compile the program in your
Natural environment with the parameter GPGEN=(COVERAGE=ON). This
creates a generated program instrumented for code coverage in this environment.
See also Updating the Objects in the Natural Environment.
The Natural Application must then be executed with the parameter
COVERAGE=(ACTIVE=ON). Regarding the execution of a Natural
application please also refer to the section
Executing
Objects.
For details concerning the Default Launch settings, see Launching Natural Applications.
As a result of executing an application with the Natural Code Coverage, a resource file with the extension .ncvf is created in the Natural environment.
The contents of the code coverage resource file can be displayed in the Code Coverage View, either directly from within the corresponding Natural Development Server in the Natural Server view or from within a workspace project.
To view the results from within the Natural Development
Server
Select the code coverage resource file in the Natural Server view.
Open the context menu and choose Open with Code Coverage.
Note:
With this approach only the Code
Coverage view can be opened. Opening individual objects displayed in
the Code Coverage tree view directly in the
Natural Source Editor is
currently not possible.
To view the results from within the NaturalONE project
Transfer the code coverage resource file to a new project containing the application sources:
Select the code coverage resource file in the Natural Server view.
Open the context menu and choose Add to New Project
Or:
Transfer the code coverage resource file to an existing
project containing the application sources:
Select the code coverage resource file in the Natural Server view.
Open the context menu and choose Add to Existing Project
Select the NaturalONE project.
Open the context menu and choose NaturalONE > Open with Code Coverage.
As a result of the previously used command the Natural Code Coverage view is opened which provides an overview of the covered code in the Natural application.
When copycode is used in a Natural object, the object node in the Code Coverage view also shows the copycode hierarchy with the distribution of the executed statements (in the Coverage column) in the copycode and the object itself:
For example, the code coverage result of the sample application above shows that the copycode TESTCOVC executed 20% of the statements available in the copycode whereas the object itself (enclosed in the << >> brackets) without the copycode executed 100% of the statements. The code coverage of the object including the copycode is finally 69,2%.
To obtain more detailed information on the line coverage of a specific source displayed in the Code Coverage view, the Natural Source Editor can be used. Double-clicking on the Natural object or using the context menu Edit command on the Natural object will open the Natural Source editor showing the lines covered.
The background color green will be applied to the following source lines:
Lines which are fully covered.
Lines containing more than one statement where at least one statement is covered.
The first line of statements spread over several lines.
The source code coloring disappears when the source file is edited and/or marked as modified.
The source code coloring is only valid when the Natural source file in the editor is identical to the one used to create the .ncvf file.