altcover.fake 8.2.821

A cross-platform pre-instrumenting code coverage tool set for .net/.net core and Mono

Install-Package altcover.fake -Version 8.2.821
dotnet add package altcover.fake --version 8.2.821
<PackageReference Include="altcover.fake" Version="8.2.821" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add altcover.fake --version 8.2.821
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: altcover.fake, 8.2.821"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install altcover.fake as a Cake Addin
#addin nuget:?package=altcover.fake&version=8.2.821

// Install altcover.fake as a Cake Tool
#tool nuget:?package=altcover.fake&version=8.2.821
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

altcover.fake

Contains options to run AltCover as part of dotnet test within a Fake build script.

Usage

Given specifications prepare, process and collect specifications (part of the API), extend a dotnet test invocation with coverage collection

open AltCoverFake.DotNet.DotNet // extension method WithAltCoverOptions
Fake.DotNet.DotNet.test (fun to' -> to'.WithAltCoverOptions prepare collect process) "dotnettest.fsproj"

See the Wiki page for full details

What's in the box?

APIs for integration into Fake build scripts -- what one might expect to see as a module Fake.DotNet.Testing.AltCover, just like the other Fake.DotNet.Testing.* modules, only built and maintained with the rest of the tool.

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.

Continuous Integration

Build GitHub Build statusBuild history AppVeyor Build status Build history
Test coverage Coveralls Coverage Status AppVeyor Test status

Possible retirement/obsolescence of support

tl;dr -- legacy framework/Mono support is not going away any time soon.

As net472 can consume netstandard2.0 libraries (everything but the recorder), and .net core 2+ can consume net20 libraries (the recorder), legacy framework/Mono support continues until such a time as it is no longer possible to retain those API levels.

altcover.fake

Contains options to run AltCover as part of dotnet test within a Fake build script.

Usage

Given specifications prepare, process and collect specifications (part of the API), extend a dotnet test invocation with coverage collection

open AltCoverFake.DotNet.DotNet // extension method WithAltCoverOptions
Fake.DotNet.DotNet.test (fun to' -> to'.WithAltCoverOptions prepare collect process) "dotnettest.fsproj"

See the Wiki page for full details

What's in the box?

APIs for integration into Fake build scripts -- what one might expect to see as a module Fake.DotNet.Testing.AltCover, just like the other Fake.DotNet.Testing.* modules, only built and maintained with the rest of the tool.

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.

Continuous Integration

Build GitHub Build statusBuild history AppVeyor Build status Build history
Test coverage Coveralls Coverage Status AppVeyor Test status

Possible retirement/obsolescence of support

tl;dr -- legacy framework/Mono support is not going away any time soon.

As net472 can consume netstandard2.0 libraries (everything but the recorder), and .net core 2+ can consume net20 libraries (the recorder), legacy framework/Mono support continues until such a time as it is no longer possible to retain those API levels.

Release Notes

This build from https://github.com/SteveGilham/altcover/tree/a9c0c13e47da072aa8a149e3cf0d6d6bf49b2710

Q. Never mind the fluff -- how do I get started?
A. Start with the Quick Start guide : https://github.com/SteveGilham/altcover/wiki/QuickStart-Guide
8.2.821 (Habu series release 6)
• Support deterministic builds /p:ContinuousIntegrationBuild=true, with or without --sourcelink//p:AltCoverSourceLink=true.  Note that assemblies created by deterministic builds will be excluded by -l//p:AltCoverLocalSource=true.
• Experiment with the ReadMe feature recently added to NuGet
• Internal refactoring of the JSON processing following the replacement of System.Text.Encodings.Web in the previous release.
8.2.820 (Habu series release 5)
• Replace System.Text.Encodings.Web for JSON-escaping module, class and method names
• [BUGFIX] issue #125 -- prevent an NullReferenceException is some cases of computing cyclomatic complexity (a failure to exactly copy the algorithm from Mono.Gendarme)
• [ENHANCEMENT; API] issue #126 -- further generalise the relative-directory support for CopyAlways/CopyIfNewer from v7.4; extends the ContingentCopy MSBuild task
8.1.819 (Habu series release 4)
• Adapt to recent F# compiler optimizations that make function objects static if they don't close over their environment -- properly detect their owner functions for exclusion and for JSON format output
• If the report format is JSON, ensure that the coverage file doesn't end .xml, and if not JSON, that it doesn't end .json (case-blind comparison)
8.1.817 (Habu series release 3)
• Merge-OpenCover cmdlet and OpenCover.Merge API.  It should handle both strict (OpenCover, AltCover --reportFormat=OpenCover) and more relaxed (coverlet, ConvertFrom-CoverageJson, Write-OpenCoverDerivedState -Coverlet) interpretations
• When --callContext indicates a method returning an F# async computation, then track all calls within the same async flow, just as with C# async methods from v7.2.800
8.0.816 (Habu series release 2)
• Move to Cake 1.0 as baseline for Cake support
• [VISUALIZER] Support for LCov and Cobertura format reports
• [VISUALIZER] For formats with only line-level information (e.g. LCov, Covertura or from coverlet), colour the whole line, and not just the line number gutter
8.0.815 (Habu series release 1)
• [BUGFIX] Issue 122 -- rework the method name tokenization for extracting the returnType (argumentList) signature values in the Cobertura output, fixing an off-by-one error that generated returnType argumentList) without the ( as well as the headline exception.
• [NEW] Native JSON report formatting (--reportFormat=Json or equivalents), a superset of coverlet's JSON
  ◦ AltCover classic mode -- just running the instrumented code and collecting results in the ProcessExit handler -- is not supported with --reportFormat=Json
  ◦ ConvertFrom-CoverageJson cmdlet to convert from coverlet or AltCover JSON to a miminal OpenCover format
  ◦ Preparing as Native JSON, to generate an LCov or Cobertura report at collection is supported
• [VISUALIZER] Both versions will now consume and display from coverlet and AltCover JSON output
• [BREAKING] the -x, --xmlReport argument or equivalent becomes just -r, --report since not all reports are XML
• [BREAKING] the stop-gap --jsonReport collection option from v7.6 is withdrawn, and the related ConvertTo-CoverageJson cmdlet now produces the AltCover native JSON format
• For both LCov and Cobertura output, coalesce cases of multiple sequence points per line into one entry per line
• Extensions to coverlet's JSON format are as follows
  ◦ Method has optional fields
    ⁃ SeqPnts (array of SeqPnt)
    ⁃ TId (integer tracking ID)
    ⁃ Entry and
    ⁃ Exit (arrays of timestamps)
  ◦ BranchInfo has optional fields
    ⁃ Id (integer unique ID)
    ⁃ Times (array of timestamps) and
    ⁃ Tracks (array of tracking IDs)
  ◦ SeqPnt is VC (visit count), SL (start line), SC (start column), EL, EC (ditto for end), Offset, Id, all integers, and optional Times and Tracks as for BranchInfo
  ◦ Because int64 doesn't fit as a double, tracking-related timestamps are represented as Base64Encoded strings of the ticks count as a network byte order quantity Convert.ToBase64String(BitConverter.GetBytes(IPAddresss.HostToNetworkOrder(ticks)))
7.6.812 (Genbu series release 15)
• [VISUALIZER] Move the global tool to the new 0.10 AvaloniaUI release
• Monitor API
  ◦ [BUGFIX] Harden the monitor API TryGetVisitTotals against race conditions in multi-threaded tests
  ◦ Publish the AltCover.Monitor API as API (i.e. under lib/) in the main package altcover as well as in altcover.api (but not in altcover.global; global tools aren't library compatible to be accessed through a package add reference).  It's there next to the PowerShell assembly (per altcover ImportModule) if you want to manually link to it, though
  ◦ Support writing unit tests involving the API back to net20 as well as netstandard2.0
• Add --jsonReport option (and equivalents) to output the NCover or OpenCover data in a minified JSON format, like the existing --lcovReport option does for that format.  The JSON is a direct map of the XML, with values appropriately typed.
• Add a ConvertTo-CoverageJson cmdlet and a ConvertToJson toolkit API to post-precess existing NCover/OpenCover reports
7.5.809 (Genbu series release 14)
• [NEW] AltCover.Monitor API to track current coverage from running unit tests.  Current implementation requires dotnet test, or other command-line testing with --defer set, in which the cumulative visit numbers are available, rather than everything having been dumped to file instead.
• [BUGFIX] In OpenCover format output, only emit <File /> records relevant to the respective module, not for all source files encountered so far.
For previous releases (7.4.x and earlier) go here -- https://github.com/SteveGilham/altcover/blob/master/ReleaseNotes%20-%20Previously.md

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
8.2.821 670 5/21/2021
8.2.820 1,029 4/26/2021
8.1.819 77 4/14/2021
8.0.816 70 2/19/2021
7.6.812 206 1/24/2021
7.5.809 145 1/17/2021
7.4.808 127 1/13/2021
7.3.806 89 1/7/2021
7.2.801 187 12/7/2020
7.1.795 762 11/9/2020
7.0.773 266 6/3/2020