Guru: Code Coverage via CL Command

November 25, 2019 Susan Gantner

This is my third tip on using RDi’s Code Coverage support. In the first tip, we explored setting up a test run using Service Entry Points (a.k.a. SEPs). In the second one, I covered how to create a configuration for the test run. Here we’ll see how to use a CL command to run a Code Coverage test session without requiring interaction with RDi (except for reporting.)

Before seeing how to do it, it may be good to discuss why you may prefer to use this approach. Simply put, it makes it easier to automate the testing process so that it is more easily repeatable since you can write a CL program to not only call the programs to do the tests but also to start the Code Coverage session for that test run as well.

It’s important to understand however, that you will still need to use RDi to do the analysis and get the Code Coverage reports. But the testing process, along with the data collection for Code Coverage, can be started on the host where the tests will run.

If you’re not on IBM i V7.4 you must ensure that the PTFs to allow the CODECOV command to work are installed. I’ll list the PTFs at end of this tip. It may also be necessary for you to add the QDEVTOOLS library to the library list of your job for the command to work.

The CODECOV Command

Let’s look at the CODECOV command. It provides a way for you to specify the same information that you could have supplied via a Code Coverage configuration (as discussed in the previous tip) plus some other details.

                                                          Code coverage (CODECOV)                                                                               
 Command to run . . . . . . . .   ______________________________________                                           
 ____________________________________________________________________...                                                                                                                                                   
 Modules:                        _                                             
   Object . . . . . . . . . . .   __________    Name                         
     Library  . . . . . . . . .     *LIBL_____  Name, *LIBL, *CURLIB         
   Object type  . . . . . . . .   *PGM___       *PGM, *SRVPGM                
   Module . . . . . . . . . . .   *ALL______    Name, generic*, *ALL, *EXCEPT
                + for more values   *ALL______                                           
                + for more values   _                                           
 Code coverage view . . . . . .   *DFT___       *DFT, *LIST, *SOURCE         
 Code coverage level  . . . . .   *LINE         *LINE, *PROC     
 Output directory . . . . . . .   *CURRENT____________________________                                                                                                                 
 Output stream file . . . . . .   ____________________________________                                                                                                                           
 Code coverage test identifier.   ____________________________________                                            

As you can see, the command is fairly simple. As with most CL commands, most of the time you’ll likely take the defaults to many of the parameters. The minimum required parameters are the “Command to run” and the name of at least one program or service program for which to collect Code Coverage data. By default, it will collect data on all the modules in the program/service program named. To list names of additional programs or service programs, put a + either next to “Modules:” or on the second “+ for more values” entry.

The “command to run” is the same one we specified in the tab named “How to start” when we created a configuration in the previous tip. It’s the command that will be used to start the test run.

The code coverage view parameter allows you to specify whether to use the source or the listing view debug data when collecting test information. The default value uses whichever view is available – defaulting to source view if both are present.

The code coverage level refers to whether you want to collect data on the individual statements that were run (the default and the most common option) or whether you just want to collect data for each procedure called.

The next two parameters — output directory and output stream file — allow you to specify where to put the data that is collected during the testing session. It’s important that you remember where the output file is so that you can refer to it later when you analyze the data using RDi.

The directory defaults to the current directory for your job (usually the one specified in your user profile) and the stream file defaults to a generated name made up of the program name and a timestamp with an extension of .cczip. You may specify either an output directory or a fully qualified IFS file name, but not both.

The test identifier is currently not used, but may be used in a later version of RDi.

For the Code Coverage test run that I did for the images included here, I’ve included below the command I used. I took defaults for most of the parameters that weren’t required. The output directory defaulted to my current directory which is specified in my user profile as /home/GANTNER.

CODECOV CMD(CALL PGM(PARTNER400/RDICODECOV))     
        MODULE((PARTNER400/RDICODECOV *PGM *ALL))

When you press enter on the CODECOV command, it will set up the code coverage session and then automatically call your program using the “command to run” you specified. When the initial program finishes, it will write out the code coverage data to the IFS file you specified. After that, you’ll need to use RDi to analyze and report on that data.

After running my test, I received informational message CCR0021:

Created code coverage result file 
  (/home/GANTNER/RDICODECOV_1573600424.cczip).        

Analyzing And Reporting On Code Coverage Data

You may recall from the earlier tips that the reports automatically appeared in my RDi editor window when I started the process from RDi. How, then, do we get the reports if the tests were started on the host?

Remember the parameter that specifies a file where to store the Code Coverage data collected during the test run? After the test runs are complete on the host, I can request that the file containing that data be brought into my RDi workspace. When it’s there, I can then request the analysis and examine the report.

To do this, go to the Code Coverage Results view (covered in an earlier tip.) Press the green + in the toolbar of that view, highlighted in Figure 1 below. If you don’t already have the Code Coverage Results view in your RDi perspective, you can open in via the “Show view” option from the Window pulldown menu.

A dialog will appear to “Add Result Location” as shown in Figure 2 below. Since my result file is on the host in an IFS folder, I will press the “Remote Systems…” button.

Then the “Browse for folder” dialog appears as shown in Figure 3 below. First choose your remote host connection name from the Connection list. (Note that it may default to your local connection.) Then drill down through the IFS folders to locate the directory of the file you specified in the command and select that folder. Then press OK and press OK again to finish the earlier dialog. The name of your selected folder should be filled in the Location box.

Any Code Coverage .cczip files located in that folder will then be imported into your results view. Expand the folder name to show the code coverage result(s) that may be there. In my example (shown below in Figure 4) there were results from three separate CODECOV runs in the folder. Double click on one of the result files and the report will appear in the editor window the same way we saw in the earlier tips, including being able to drill down into the statement level data (if collected) by double clicking a module or procedure name in the Code Coverage Report.

I promised earlier to include the PTFs that you’ll need on your system to use the CODECOV command if you don’t yet have V7.4 on your IBM i. The PTFs listed below are for product 5770WDS. CODECOV command support is not available for host systems running V7.1 or earlier, although you can still use Code Coverage started from RDi.

V7.3: PTF SI65229 and SI64655

V7.2: PTF SI65228 and SI64544

In this series on using Code Coverage, we’ve now seen three ways to run it. In the two previous tips we covered how to start it from RDi — either using an SEP or using a configuration. Now we’ve seen how to start the testing from the IBM i host with a CL command. Lots of ways to make sure your testing is doing its job!

RELATED STORIES

How Thorough Was Your Last Test? RDi Code Coverage Can Tell You

RDi Code Coverage Without SEPs