Skip to content

The v4.0 AltCover API, plus Fake and Cake integration

Jump to bottom
Steve Gilham edited this page Apr 28, 2020 · 5 revisions

Note -- there will be breaking API changes at v5.0 Note -- the deprecated CommandLine fields in the F# API cannot usefully be marked [Obsolete] without obsoleting the entire record, so there is a run-time rather than compile-time warning.

F# core API

module AltCover.Api

In AltCover.exe (.dll for .net core) we find the core functions corresponding to the MSBuild tasks; this part of the API is available in all variants of the AltCover NuGet package, even if in .net core scenarios, AltCover.dll may not be suitably located for the automagic linking to dependencies in the NuGet cache

  • Prepare : PrepareParams -> Logging -> int
  • Collect : CollectParams -> Logging -> int
  • Ipmo : unit -> string
  • Version : unit -> string

where int results are 0 for success and otherwise for failure (this would be the return code of the operation if run as a command-line function);

[<NoComparison>]
type AltCover.CollectParams =
  {RecorderDirectory: String;
   WorkingDirectory: String;
   Executable: String;
   LcovReport: String;
   Threshold: String;
   Cobertura: String;
   OutputFile: String;
   CommandLine: String; // deprecated
   Command: String seq; // preferred}
  with
    [<Obsolete>]
    static member Default : CollectParams
    static member Create() : CollectParams
    member Validate : bool -> string array
  end

where the Default instance has all values empty; Create() returns an instance with all values empty; Validate does simple checking of the arguments without causing any changes to the system; set the input argument true if the Prepare step has already run (and there should be instrumented code the RecorderDirectory; returns all the problems that the application command-line could report, so empty is success.

[<NoComparison>]
type AltCover.PrepareParams =
  {InputDirectory: String;
   OutputDirectory: String;
   SymbolDirectories: string seq;
   Dependencies: string seq;
   Keys: string seq;
   StrongNameKey: String;
   XmlReport: String;
   FileFilter: string seq;
   AssemblyFilter: string seq;
   AssemblyExcludeFilter: string seq;
   TypeFilter: string seq;
   MethodFilter: string seq;
   AttributeFilter: string seq;
   PathFilter: string seq;
   CallContext: string seq;
   OpenCover: bool;
   InPlace: bool;
   Save: bool;
   Single: bool;
   LineCover: bool;
   BranchCover: bool;
   CommandLine: String; // deprecated
   Command: String seq; //preferred}
  with
    [<Obsolete>]
    static member Default : CollectParams
    static member Create() : CollectParams
    member Validate : unit -> string array
  end

where the Default instance has all empty or false fields except OpenCover, InPlace and Save are true; Create() returns an instance that has all empty or false fields except OpenCover, InPlace and Save are true; Validate does simple checking of the arguments without causing any changes to the system; returns all the problems that the application command-line could report, so empty is success. and

type AltCover.Logging =
  {Info: String -> unit;
   Warn: String -> unit;
   Error: String -> unit;
   Echo: String -> unit;}
  with
    static member ActionAdapter : a:Action<String> -> (String -> unit)
    static member Default : Logging
  end

The Default instance just discards all strings input. For your particular use, direct message severities appropriately. Echo is used to echo the synthetic command line in case of inconsistent inputs.

Collect and Prepare stage fields that are not applicable to the use case or platform are silently ignored.

module AltCover.CoverageFormats

In AltCover.FSApi.dll

  • ConvertToLcov: XmlDocument -> Stream -> unit and public static void ConvertToLcov(XmlDocument xmlDocument, Stream stream)
  • ConvertToCobertura: XmlDocument -> XDocument and public static XDocument ConvertToCobertura(XmlDocument xmlDocument)

The input is either in NCover for OpenCover format; Cobertura, being XML, is returned as a document, the lcov format output is to a stream.

  • ConvertToNCover: IXPathNavigable -> XmlDocument and public static XmlDocument ConvertToNCover(IXPathNavigable navigable)
  • ConvertFromNCover: IXPathNavigable -> string array -> XmlDocument and public static XmlDocument ConvertFromNCover(IXPathNavigable navigable, string[] assemblies)

The conversion is from or to OpenCover format, respectively

module AltCover.DotNet

In AltCover.FSApi.dll

  • ToTestArgumentList : PrepareParams -> CollectParams -> string list
  • ToTestArguments : PrepareParams -> CollectParams -> string

The former creates the /p:AltCoverXXX="yyy" elements for a dotnet test invocation as an array of strings, the latter concatenates them, with space separators, into a single command line string.

module AltCover.OpenCoverUtilities

In AltCover.FSApi.dll

  • CompressBranching: IXPathNavigable -> bool -> bool -> XmlDocument and public static XmlDocument CompressBranching(IXPathNavigable navigable, bool withinSequencePoint, bool sameSpan)

The input is in OpenCover format; the F# arguments match the C# ones which match the cmdlet names.

module AltCover.Xhtml

In AltCover.FSApi.dll

  • ConvertToBarChar: IXPathNavigable -> XmlDocument and public static XmlDocument ConvertToBarChart(IXPathNavigable navigable)

The input is in either NCover or OpenCover format

module AltCover.XmlUtilities

In AltCover.FSApi.dll

  • ToXmlDocument: XDocument -> XmlDocument and public static XmlDocument ToXmlDocument(XDocument xDocument)
  • ToXDocument: XmlDocument -> XDocument and public static XDocument ToXDocument(XmkDocument xmlDocument)

General purpose interconversion utilities

The following types in the whole of the rest of the page are in assemblies only present in the altcover.api package

C# core API

static class AltCover.CSApi

In AltCover.CSApi.dll, provides the equivalents of the above

  • public static int Prepare(PrepareArgs p, LogArgs l)
  • public static int Collect(CollectArgs c, LogArgs l)
  • public static string Ipmo()
  • public static string Version()
  • public static string ToTestArguments(PrepareArgs p, CollectArgs c)
  • public static string[] ToTestArgumentList(PrepareArgs p, CollectArgs c)

where

    public class AltCover.CollectArgs
    {
        public string RecorderDirectory { get; set; }
        public string WorkingDirectory { get; set; }
        public string Executable { get; set; }
        public string LcovReport { get; set; }
        public string Threshold { get; set; }
        public string Cobertura { get; set; }
        public string OutputFile { get; set; }
        [Obsolete("Please use AltCover.CollectArgs.Command instead instead.")]
        public string CommandLine { get; set; }
        public string[] Command { get; set; }
        public static CollectArgs Default { get; }
        public string[] Validate(bool afterPreparation);
    }

    public class AltCover.PrepareArgs
    {
        public string InputDirectory { get; set; }
        public string OutputDirectory { get; set; }
        public string[] SymbolDirectories { get; set; }
        public string[] Dependencies { get; set; }
        public string[] Keys { get; set; }
        public string StrongNameKey { get; set; }
        public string XmlReport { get; set; }
        public string[] FileFilter { get; set; }
        public string[] AssemblyFilter { get; set; }
        public string[] AssemblyExcludeFilter { get; set; }
        public string[] TypeFilter { get; set; }
        public string[] MethodFilter { get; set; }
        public string[] AttributeFilter { get; set; }
        public string[] PathFilter { get; set; }
        public string[] CallContext { get; set; }

        public bool OpenCover { get; set; }
        public bool InPlace { get; set; }
        public bool Save { get; set; }
        public bool Single { get; set; }
        public bool LineCover { get; set; }
        public bool BranchCover { get; set; }
        [Obsolete("Please use AltCover.PrepareArgs.Command instead instead.")]
        public string CommandLine { get; set; }
        public string[] Command { get; set; }


        public static PrepareArgs Default { get; }
        public string[] Validate();
    }

and

    public class AltCover.LogArgs
    {
        public Action<String> Info { get; set; }
        public Action<String> Warn { get; set; }
        public Action<String> Error { get; set; }
        public Action<String> Echo { get; set; }
    }

Fake integration

In AltCover.Fake.dll (.net core only)

module AltCover.Fake.Trace

  • static member Default : Logging Returns an instance of the core API Logging type that hooks into the Fake.Core.Trace facilities

type AltCover.Fake.Api

wraps the core API functions.

  • static member Collect : args:CollectParams * ?log:Logging -> int
  • static member Ipmo : unit -> string
  • static member Prepare : args:PrepareParams * ?log:Logging -> int
  • static member Version : unit -> string
  • toolPath : Implementation -> string

where int results are 0 for success and otherwise for failure (this would be the return code of the operation if run as a command-line function); and the Implementation type is

[<NoComparison>]
type Implementation =
  | DotNetCore
  | Framework

to indicate which command-line executable from the current NuGet package to return

If the optional logging argument is not given, then AltCover.Fake.Trace.Default is assumed

type Fake.DotNet.DotNet.TestOptions Extension method (in module AltCover.Fake.DotNet)

  • member self.WithParameters (prepare:PrepareParams) (collect:CollectParams) : Fake.DotNet.DotNet.TestOptions Adds the result of AltCover.DotNet.ToTestArguments to the CustomParams member of the Common member
  • member self.WithImportModule () : Fake.DotNet.DotNet.TestOptions Adds "/p:AltCoverIpmo=true" to the CustomParams member of the Common member
  • member self.WithGetVersion () : Fake.DotNet.DotNet.TestOptions Adds "/p:AltCoverGetVersion=true" to the CustomParams member of the Common member

Example

open AltCover.Fake.DotNet
...
  let p2 = { AltCover.PrepareParams.Create () with CallContext = [| "[Fact]"; "0" |] }
  let c2 = AltCover.CollectParams.Create ()

  let setBaseOptions (o:DotNet.Options) =
    { o with WorkingDirectory = Path.getFullName "./_DotnetTest"
             Verbosity = Some DotNet.Verbosity.Minimal }

  DotNet.test (fun to' -> to'.WithCommon(setBaseOptions).WithParameters p2 c2) "dotnettest.fsproj"

Cake integration

In AltCover.Cake.dll

    public static class AltCover.Cake.Api
    {
        [CakeMethodAlias]
        public static int Prepare(this ICakeContext context, PrepareArgs p, LogArgs l = null)
        [CakeMethodAlias]
        public static int Collect(this ICakeContext context, CollectArgs c, LogArgs l = null)
        [CakeMethodAlias]
        public static string Ipmo(this ICakeContext context)
        [CakeMethodAlias]
        public static string Version(this ICakeContext context)
    }

which wrap the core API; if no logging support is supplied, then Cake logging at an appropriate severity is used.

    public class AltCover.Cake.AltCoverSettings
    {
        public PrepareArgs PreparationPhase { get; set; }
        public CollectArgs CollectionPhase { get; set; }
    }

combines the arguments into one object, and

    [CakeAliasCategory("DotNetCore")]
    public static class AltCover.Cake.DotNet
    {
        [CakeMethodAlias]
        [CakeAliasCategory("Test")]
        public static void DotNetCoreTest(
                    this ICakeContext context,
                    FilePath project,
                    DotNetCoreTestSettings settings,
                    AltCoverSettings altcover)
   }

hooks into the Cake wrapper for dotnet test and injects the AltCover command line arguments as specified.

Clone this wiki locally