Skip to content

The Visualizer

Jump to bottom
Steve Gilham edited this page Jul 26, 2020 · 20 revisions

A stand-alone GUI application to show what's in your NCover or OpenCover format output.

This is provided as a dotnet global tool in the altcover.visualizer package, which from release 7.1.780 is based on the AvaloniaUI cross-platform toolkit

Avalonia-based visualizer

and also, as the legacy original Framework/Mono+GTK# executable that derives from the original c.2010 work, provided in the altcover package.

GTK#-based visualizer

A GTK+3/.net core based version was added in release 4.0.618; but this is now considered obsolete

User Guide

Here's the simple naming of parts

Annotated

The recently accessed list is a drop-down for quick access to coverage files of current interest. The Refresh option is there for reloading the file you're currently examining e.g. after doing another test run.

The tree view opens with just the node for the coverage file shown. Drill down to the method of interest and double-click to load the appropriate source file.

The tree view shows the structure of the assemblies in the report, including virtual groupings for modules (classes that only contain classes, so have no presence in the XML reports), (as seen in the inset) for properties (get_ and/or set_), and for events (add_ and/or remove_). Also where a type is just a function (i.e. only has an Invoke method), there is separate icon for that.

Colouring

A painter's algorithm approach is used -- first the whole source file is drawn, then the covered sections, then the un-covered ones, and finally any special cases. This approach ensures that the uncovered code is shown explicitly and is not obscured when some of the line, or a multi-line enclosing sequence point, happens to be covered : it's the unflattering view for engineers, rather than the sea of green for managers.

If the coverage file contains branch information, then an icon is shown in the left margin, in red-on-white for uncovered, black-on-yellow for partial coverage and black-on-pale green for complete coverage, with the details in tool-tip text for that icon.

Avalonia UI

The source is rendered by default in grey-on-whitesmoke; covered sequence-points are painted a medium blue, and then uncovered code is painted in crimson.

With the --showstatic option, normally ignored code like auto-properties is shown in the report, and if not covered will appear as black, and with the --showGenerated option other code marked as [GeneratedCode] or [CompilerGenerated] shows as gold if not covered.

Annotated v6.6 - static and generated code

For purposes of demonstration, one test method here has been manually decorated with the [GeneratedCode] attribute; if the system under test uses code generation, marking it as such should be standard practice.

From v7.1.783, this visualizer version also offers some limited font selection for source display

Tool-bar with font selection icon

  • On Windows, this uses the native FontChooser() API, restricting to monospace fonts (the default is "Courier New Normal 10")
  • Otherwise if the Tcl/Tk wish shell (assumed to be Tcl/Tk v8.6 or later) is on the PATH, the toolbar-icon is also shown. In the latter case, this spawns wish as a separate process to use its cross-platform font selection support; terminating the process when either a font selection is made (e.g. via Okor Apply), or the selection dialog is dismissed. There are no APIs there to restrict the font chooser to monospace fonts, so choose wisely (the default is "Monospace Normal 10")

GTK

As it makes use of a more mature toolkit, this version of the visualizer offers some extra functionality.

  • a choice of the font for source display, with an extra toolbar icon to open a font selection dialog : unfortunately, the APIs aren't there to restrict the GTK font chooser to monospace fonts, so choose wisely (the default is "Monospace Normal 10")
  • the ability to colour background as well as foreground for formatted text
  • more standard widgets (like the all in one open file dialog + dropdown list button, and toolbar buttons with built-in stock icons for standardised operations)

The source is rendered by default in grey-on-whitesmoke; covered sequence-points are painted a medium blue on pale green, and then uncovered code is painted in red-on-white.

With the --showstatic option, normally ignored code like auto-properties is shown in the report, and if not covered will appear as white smoke on black, and with the --showGenerated option other code marked as [GeneratedCode] or [CompilerGenerated] shows as grey on gold if not covered.

Annotated v6.6 - static and generated code

Configuration

Configuration information -- screen size and location, recently accessed list, source font -- is stored in the registry (or the Mono file-based equivalent on non-Windows platforms) under HKCU\SOFTWARE\AltCover\Visualizer; the newer version uses an XML config file $(Environment.SpecialFolder.ApplicationData)/.altcover/Visualizer.xml whose content looks like

<?xml version="1.0" encoding="utf-8"?>
<AltCover.Visualizer>
  <CoveragePath>...folder of last coverage file opened...</CoveragePath>
  <Font>...font specification...</Font>
  <Geometry x="###" y="###" width="###" height="###" />
  <RecentlyOpened>...file...</RecentlyOpened>
  <RecentlyOpened>...file...</RecentlyOpened>
...
</AltCover.Visualizer>

For backwards compatibility with the GTK-based visualizer, font selections are stored in the textual representation of a Pango font definition, in the format font face[,] [token [token [token...]]] [size] [@variations]. The comma is required if the font name contains a space-sparated string that could be interpreted as a valid descriptive token.

Valid token values for weight are

  • Thin
  • Ultra-Light
  • Extra-Light
  • Light
  • Semi-Ligh
  • Demi-Light
  • Book
  • Regular
  • Normal
  • Medium
  • Semi-Bold
  • Demi-Bold
  • Bold
  • Ultra-Bold
  • Extra-Bold
  • Heavy
  • Black
  • Ultra-Heavy
  • Extra-Heavy
  • Ultra-Black
  • Extra-Black

The Tcl/Tk font representation flattens everything lighter to "Normal", and everything above to "Bold"

Valid slope values are

  • Roman
  • Oblique
  • Italic

Functionally, "Oblique" and "Italic" are equivalent.

Valid but ignored Pango tokens are

  • any trailing "@variations"
  • Small-Caps
  • Ultra-Condensed
  • Extra-Condensed
  • Condensed
  • Semi-Condensed
  • Semi-Expanded
  • Expanded
  • Extra-Expanded
  • Ultra-Expanded
  • Not-Rotated
  • South
  • Upside-Down
  • North
  • Rotated-Left
  • East
  • Rotated-Right
  • West

If the <Font /> tag doesn't exist, insert it ahead of <Geometry />.

Command-line option -r clears the existing recent file list; -g clears the existing stored size and location.

Obsoleted

A GTK+3/.net core based version was added in release 4.0.618; it's a straight port of (shares much of its code with, with just GTK API changes from) the original.

GTK3-based visualizer

The code is still built, just not bundled for release.

NOTE if this version of the program crashes when trying to open the Open... menu item, this probably means that the GTK3 environment isn't 100% set up. For the GTK3 visualizer, at v6.7 --schemadir[=path] sets or clears an application-level GSETTINGS_SCHEMA_DIR value, otherwise, manually, set environment variable GSETTINGS_SCHEMA_DIR to the path of the folder containing the GTK settings file gschemas.compiled e.g.

$env:GSETTINGS_SCHEMA_DIR="C:\msys64\mingw64\share\glib-2.0\schemas"
Clone this wiki locally