Code Coverage

The IDL Code Coverage feature helps you analyze the lines of code that were executed within your application. Use code coverage to identify 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:

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 View

To enable code coverage in the Editor view, select Run > Show Code Coverage from the Workbench main menu.

The code coverage annotations will appear in any Editor view that contains compiled code. If you open an Editor that does not contain compiled code, those lines will not be highlighted.

For example, the routine shown above is open in the Editor view. Press the Compile button to compile the code but not run it. 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 will update the highlighting to show which lines have been executed:

In the example above, the green lines have been executed at least once and the red lines have not been executed. In line 9, the first statement was executed but the second statement was not; in this case, partially executes lines are colored yellow.

The right side of the Editor view shows a snapshot of the full file, with small green, yellow, or red bars. Hover the mouse over one of the small bars to display the corresponding line of code, or click on a small bar to jump to that section of code.

If you have other Editors open, then switching to another editor 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 Run > Hide Code Coverage from the Workbench main menu.

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 has 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. Click on the Code Coverage column heading to sort the view in either increasing or decreasing percentage.

If you double-click on an IDL .pro routine, the Editor will open to that routine. If code coverage is not already displayed, enable the Show Code Coverage button on the Profiler view toolbar, or select Run > Show Code Coverage from the IDL Workbench main menu.

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 IDL Workbench Preferences. In the Preference dialog, select General > Editors > Text Editors > Annotations. You can set highlight colors for three different annotation types in the Annotations dialog that appears.

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