# altcover

Instrumenting coverage tool for .net (framework 2.0+ and core) and Mono, reimplemented and extended almost beyond recognition from dot-net-coverage, plus a set of related utilities for processing the results from this and from other programs producing similar output formats.

## Never mind the fluff -- how do I get started?

Start with the Quick Start guide

The latest releases can be downloaded from releases, but the easiest (and most automated) way is through the nuget packages.

## What's in the box?

For Mono, .net framework and .net core, except as noted

- `AltCover`, a command-line tool for recording code coverage (including dotnet and global tool versions)
- MSBuild tasks to drive the tool, including `dotnet test` integration
- An API for the above functionality, with Fake and Cake integration
- A PowerShell module (not mono) containing a cmdlet that drives the tool, and other cmdlets for manipulating coverage reports
- A coverage visualizer tool
  - For .net framework and mono (for .net framework, needs GTK# v2.12.xx installed separately -- see https://www.mono-project.com/download/stable/#download-win )
  - For .net core (needs GTK+3 installed separately -- for Windows, see e.g. https://github.com/GtkSharp/GtkSharp/wiki/Installing-Gtk-on-Windows)

### NuGet Packages

- General purpose install -- excludes the C# API and FAKE integration
- API install -- excludes the .net Framework/mono/GTK#2 Visualizer
- dotnet CLI tool install -- excludes the visualizer in all forms
- dotnet global tool install -- excludes the visualizer in all forms
- Visualizer dotnet global tool -- just the .net core/GTK#3 Visualizer as a global tool
- FAKE build task utilities -- just AltCover related helper types for FAKE scripts (v5.9.3 or later), only in this package

## Why altcover?

As the name suggests, it's an alternative coverage approach. Rather than working by hooking the .net profiling API at run-time, it works by weaving the same sort of extra IL into the assemblies of interest ahead of execution. This means that it should work pretty much everywhere, whatever your platform, so long as the executing process has write access to the results file. You can even mix-and-match between platforms used to instrument and those under test.

In particular, while instrumenting .net core assemblies "just works" with this approach, it also supports Mono, as long as suitable `.mdb` (or `.pdb`, in recent versions) symbols are available. One major limitation here is that the `.mdb` format only stores the start location in the source of any code sequence point, and not the end; consequently any nicely coloured reports that take that information into account may show a bit strangely.

### Why altcover? -- the back-story of why it was ever a thing

Back in 2010, the new .net version finally removed the deprecated profiling APIs that the free NCover 1.5.x series relied upon. The first version of AltCover was written to both fill a gap in functionality, and to give me an excuse for a ground-up F# project to work on. As such, it saw real production use for about a year and a half, until OpenCover reached a point where it could be used for .net4/x64 work (and I could find time to adapt everything downstream that consumed NCover format input).

Fast forwards to autumn 2017, and I get the chance to dust the project off, with the intention of saying that it worked on Mono, too -- and realise that it's déja vu all over again, because .net core didn't yet have profiler based coverage tools either, and the same approach would work there as well.

### Other notes

1. On old-fashioned .net framework, the `ProcessExit` event handling window of ~2s is sufficient for processing significant bodies of code under test (several 10s of kloc, as observed in production back in the '10-'11 timeframe); under `dotnet test` the `vstest.console` process imposes a 100ms guillotine, even though .net Core imposes no time-limit of its own. This is about enough time to fill in an NCover report for a program of no more than 1kloc, hence the development of a "write it all promptly to file and post-process" `Runner` mode. With version 5.3 and above, the `dotnet test` integration now hooks the VSTest in-process data collection, allowing an indefinite window to write collected data from memory, thus removing the file I/O bottleneck.

2. Under Mono on non-Windows platforms the default values of `--debug:full` or `--debug:pdbonly` generate no symbols from F# projects -- and without symbols, such assemblies cannot be instrumented. Unlike with C# projects, where the substitution appears to be automatic, to use the necessary `--debug:portable` option involves explicitly hand editing the old-school `.fsproj` file to have `<DebugType>portable</DebugType>`.

## Usage

See the Wiki page for details

## Roadmap

See the current project for details