The IDL Code Coverage feature helps you analyze the lines of code that were executed within your application. Code coverage is very useful at identifying unused or unneeded code paths, or to ensure that your "unit tests" are exercising all of your code.
There are three ways to use the Code Coverage feature: The CODE_COVERAGE function, within the Workbench's Editor View, and from the Profiler View.
With this method, you can compile and run your application, then call CODE_COVERAGE for each routine. This will return the lines of code that were not executed, and optionally the lines that were executed.
For example, save the following code in a file, compile the code but do not run it:
function ex_codecover
PRINT, 2+2
; not reached
if (0) then begin
PRINT, "never reached"
endif else begin
PRINT, "reached"
endelse
return, 1 & PRINT,'never reached'
PRINT, 'past the return'
end
Call the CODE_COVERAGE routine and print the results:
r = CODE_COVERAGE('ex_codecover', EXECUTED=e)
PRINT, 'Lines not executed: ', r.ToString()
PRINT, 'Lines executed: ', e.ToString()
IDL prints:
Lines not executed: 1 2 4 5 7 9 9 10
Lines executed: 0
Note that line 9 is repeated twice since there are two statements on the same line.
Now call the function and then call CODE_COVERAGE:
void = EX_CODECOVER()
r = CODE_COVERAGE('ex_codecover', EXECUTED=e)
print, 'Lines not executed: ', r.ToString()
print, 'Lines executed: ', e.ToString()
IDL prints:
Lines not executed: 5 9 10
Lines executed: 1 2 4 7 9
Note that line 9 is now in both the "executed" and "not executed" list, since only one of the statements was executed.
See CODE_COVERAGE for the rules on what is considered a "line of code."
To enable code coverage in the Workbench Editor, select the Run > Show Code Coverage menu item:
After selecting Show Code Coverage, the code coverage annotations will immediately appear in any Editors that contain compiled code. If you open an Editor that does not contain compiled code, those lines will not be highlighted.
For example, assume we have the same routine in the example above open in the Editor. Hit the Compile button to make sure that the code is freshly compiled but not run. The Editor should show the following:
The lines of code are highlighted in red, indicating that they have not been executed.
Now run the code by typing the following command:
IDL> void = EX_CODECOVER()
The Editor should now automatically update the highlighting to show which lines have been executed:
The green indicates lines that have been executed at least once. The red indicates lines that still have not been executed. Note that in line 9, the first statement was executed while the second statement was not. For this case the line is colored yellow.
Along the right-hand side, the "gutter" shows a snapshot of the entire file, with small green, yellow, or red bars. If you hover your mouse over one of the small bars it will display the line of code. If you click on a small bar it will jump to that section of code.
If you have other Editors open, then switching to those other editors will immediately show the code coverage for that file.
To reset the code coverage for a file, you can either re-compile the file or use the CODE_COVERAGE function with the /CLEAR keyword. Resetting the IDL session will also clear out the code coverage.
To turn off the code coverage highlighting, select the "Run->Hide Code Coverage" menu item.
Tip: IDL automatically keeps track of code coverage for all compiled routines, regardless of the setting of the Code Coverage menu item. You could run your entire application, turn on "Show Code Coverage", and then open up your code in the Editor. The Editor will then update with the current code coverage highlighting.
The Profiler View contains three columns related to code coverage:
The Code Coverage column also contains a graph for each routine, showing green for the percentage of code that was executed, and red for the percentage of code that was not executed. You can click on the "Code Coverage" header to sort the view in either increasing or decreasing percentage.
If you double click on an IDL .pro routine, the Editor will be opened to that routine. If code coverage is not already displayed, you can turn on Show Code Coverage using either the button on the Profiler View's toolbar or the Run > Show Code Coverage menu item.
See Profiler View for more details on using the Profiler.
You can change the appearance of the green, yellow, and red highlighting bars. In the Workbench, open up the Preferences dialog. You can either type the word "annotation" into the search box, or navigate to General > Editors > Text Editors > Annotations. There, you can choose the three different annotation types:
Changing the colors will change the highlighting in both the Editor and in the Profiler View.