The IDL Workbench > Code Coverage

# Code Coverage

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.

## The CODE_COVERAGE Function

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

## Code Coverage in the Editor

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.

## Code Coverage in the Profiler View

The Profiler View contains three columns related to code coverage:

- Lines Run - The number of code lines that were executed within the routine. This is empty for system routines.
- Total Lines - The total number of code lines within the routine. This is empty for system routines.
- Code Coverage - The fraction of the total lines of code that were executed, which is just the ratio of Lines Run to Total Lines. A value of 0% indicates that none of the code was executed, while 100% indicates that all of the code was executed.

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.

## Changing the Highlighting Colors

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:

- Code Coverage Executed - lines of code that have been hit (default is green)
- Code Coverage Not Executed - lines of code that have not been hit (default is red)
- Code Coverage Partially Executed - lines of code that have been partially hit (default is yellow)

Changing the colors will change the highlighting in both the Editor and in the Profiler View.

## See Also

CODE_COVERAGE, Profiler View, Preferences, Editor View