Class CodeCoverage

Introduction

This class provides code coverage analysis by sampling the lines of code executed by a program and counting those occurrences, and by parsing the source files to find any code that was not executed.

Sampling is performed by using a Telnet connection to drive the Synergy/DE remote debugger, stepping through the code a line at a time and recording the line numbers encountered. This process can take quite a bit of time, depending on the code being executed. Because the Telnet remote debugger is not available for Synergy.NET, this class is not provided for .NET either.

This class is used by two supplied utilities: cover and htmlcover.

Contents

  1. Introduction
  2. Contents
  3. Explanation of symbols used
  4. Member reference
    1. Analyze - Analyze a source file
    2. AnalyzeAll - Analyze all known source files
    3. Map - Map of source files
    4. Markup - Generate an HTML report for a file
    5. MarkupAll - Generate an HTML report for all files
    6. Sample - Sample an executable
    7. SourcePath - Path for source files
    8. TelnetPort - Port to use for sampling
  5. Related classes
    1. SourceFile - a source file being sampled or analyzed
      1. (constructor)
      2. lines - hash of lines and hits
      3. name - the filename
      4. NumberWithin - number of lines within a range of hits
      5. PercentageWithin - percentage of lines within a range of hits
    2. ProgressHandler - Handler for progress notifications
      1. OnProgress - Progress event notification
      2. ProgressStdOut - Derived class for sending notifications to stdout

Explanation of symbols used

Words in italics indicate an instance of a class. The word corresponds to the class name, except where more than one instance is represented in the same statement. In that case a number (2, 3, etc.) is appended to the class name.

Words in normal typeface are to be taken literally (required punctuation, class name in a static reference, method name, etc.)

The symbol => is used to separate an expression (on the left) from its return value (on the right).

An ellipsis (...) indicates that the previous argument may be repeated any number of times. The description will indicate whether one instance is required.

Member reference

method Analyze

codecoverage.Analyze(a) => boolean
Attempts to open the file specified by a within any of the directories specified by the SourcePath property. If the file cannot be opened, it returns false. Otherwise, the file is analyzed to detect all executable statements. If a corresponding SourceFile is not in the Map, it will be added. For each statement that is determined to be executable, if that line number does not exist in the lines for the associated SourceFile, it will be added with a hit count of zero.

method AnalyzeAll

codecoverage.AnalyzeAll() => ls
codecoverage.AnalyzeAll(ProgressHandler) => ls
Calls Analyze for each source file that is contained in the Map. Any file that cannot be opened is removed from the Map. Returns a list of the names of the files that could not be opened. If ProgressHandler is passed, then as each file is analyzed, that event will be logged to ProgressHandler's OnProgress method.

property Map

codecoverage.Map => Hash
codecoverage.Map = Hash
This property specifies a Hash of a => sourcefile, where a is the name of the file, and sourcefile is an associated SourceFile.

method Markup

codecoverage.Markup(a) => ls

Returns a list of HTML source lines that represent the source code from the file specified in a, marked up to indicate code coverage. If the file cannot be opened, then ls is returned as a list without any source lines, but still containing headers. If the file does not exist in the Map, it will be analyzed.

In the generated HTML, the first line will be a header in a <div> section of class "coverage coverage-head". This will contain <span>s for each header, of the same class as the columns, which are "coverage-line" (line number), "coverage-source" (the source line itself), and "coverage-hits" (the number of executions sampled). Each successive line is an actual source line from the file enclosed within a <div> with two classes: "coverage" and a class that specifies a range of hits:

  • coverage-notexe - not an executable statement
  • coverage-0 - not executed
  • coverage-1 thru coverage-10 - executed 1 to 10 times
  • coverage-over10 - executed more than 10 times

method MarkupAll

codecoverage.MarkupAll(a, a2) => ls
codecoverage.MarkupAll(a, a2, ProgressHandler) => ls

Generates an HTML report of coverage for all known files, returning a list of files that could not be opened. The first argument (a) specifies the name of the HTML file that will be created. The second argument (a2) specifies the title for the report. At the top of the report will be a table that contains the name of each source file (linked to its specific sub-report) and the percentage of code executed at least once, more than once, and more than 10 times. Each file's report (generated by Markup) is then presented in a <div> section of class "coverage-file" and an id corresponding to the name of the file. If ProgressHandler is passed, then its OnProgress method will be invoked for each file as it is being processed.

The generated file contains a link to a stylesheet named "coverage.css". An example of this stylesheet can be found in tests\coverage.css.

method Sample

codecoverage.Sample(a) => Hash
codecoverage.Sample(a, ProgressHandler) => Hash
This method launches the Synergy/DE executable named in a in remote debug mode to sample the line numbers executed. If the executable needs arguments, you may pass them within a as well. Do not include "dbr" itself or any debug switches to that command. This method may run for some time. It increments the line count for each line that is executed to the appropriate SourceFile within the Map, which it returns. If a source file is encountered that isn't in the map, it will be added. If ProgressHandler is supplied, then as each line of the main source file is encountered, that event will be passed to ProgressHandler's OnProgress method.

static property SourcePath

CodeCoverage.SourcePath => string
CodeCoverage.SourcePath = string
This property specifies the list of directories to search for source files for analysis. Multiple directories should be separated by a comma. This property defaults to the value of the environment variable SOURCE_PATH, and modifying it changes the value of that environment variable.

TelnetPort

codecoverage.TelnetPort => int
codecoverage.TelnetPort = int
This public member specifies the port to use for the Telnet session launched by the Sample method. It defaults to 2499.