Skip to content

The v5.x╱6.x AltCover API, plus Fake and Cake integration

Jump to bottom
Steve Gilham edited this page Apr 11, 2020 · 1 revision

F# core API v5.x/6.x

v6.0 changes/replaces the InputDirectory and OutputDirectory fields

Basic types

In AltCover.exe (.dll for .net core) we find the descriptions of the basic 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

module AltCover.Primitive (Requires qualified access)

This module contains the weakly-typed, all strings, data structures in the style of Fake

[<NoComparison>]
type CollectParams =
  {RecorderDirectory: String;
   WorkingDirectory: String;
   Executable: String;
   LcovReport: String;
   Threshold: String;
   Cobertura: String;
   OutputFile: String;
   CommandLine: String seq;
   ExposeReturnCode : bool; // new at 5.1
   SummaryFormat : String; // new at 5.2
}
  static member Create() : CollectParams

Create() returns an instance with all values empty Fields that are not applicable to the use case or platform are silently ignored.

[<NoComparison>]
type AltCover.PrepareParams =
  {InputDirectory: String; // InputDirectories : String seq at v6.x
   OutputDirectory: String; // OutputDirectories : String seq at v6.x
   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 seq;
   ExposeReturnCode : bool; // new at 5.1
   SourceLink : bool; // new at 5.1
   Defer : bool; // new at 5.3
   LocalSource : bool; // new at 6.1
   VisibleBranches : bool; // new at 6.2
   ShowStatic : string; // new at 6.6
   ShowGenerated : bool; // new at 6.6
}
  static member Create() : PrepareParams

Create() returns an instance that has all empty or false fields except OpenCover, InPlace and Save are true Fields that are not applicable to the use case or platform are silently ignored.

[<NoComparison; NoEquality>]
type Logging =
  {Info: String -> unit;
   Warn: String -> unit;
   Error: String -> unit;
   Echo: String -> unit;}
   static member Create() : Logging

Create() returns an instance that 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.

module AltCover.FSApi (Requires qualified access)

This contains wrappers for the primitive-based types to allow for future evolution -- one member of a discriminated union can be obsoleted without causing the whole type to fall into disarray (as is the case with obsoleting a field in a record).

type ValidatedCommandLine = // new at v6.7
  {
    Command: string list
    Errors: string array
  }
  with override self.ToString()

[<NoComparison>]
type CollectParams =
  | Primitive of Primitive.CollectParams
  ...
  member Validate : bool -> string array
  member WhatIf : bool -> ValidatedCommandLine // new at v6.7
  member RecorderDirectory : unit -> String
  member WorkingDirectory : unit -> String
  member Executable : unit -> String
  member LcovReport : unit -> String
  member Threshold : unit -> String
  member Cobertura : unit -> String
  member OutputFile : unit -> String
  member CommandLine : unit -> String seq
  member ExposeReturnCode : unit -> bool // new at 5.1
  member SummaryFormat : unit -> String // new at 5.2

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. The other members are simple properties reading the values from the contained instance; null strings will be retrurned as null, but null sequences will be returned as empty ones. Fields that are not applicable to the use case or platform are silently ignored. WhatIf compiles the effective command-line and the result of Validate

[<ExcludeFromCodeCoverage; NoComparison>]
type PrepareParams =
  | Primitive of Primitive.PrepareParams
  ...
  member Validate : unit -> string array
  member WhatIf : unit -> ValidatedCommandLine // new at v6.7
  member InputDirectory : unit -> String // member InputDirectories : unit -> String list at v6.0
  member OutputDirectory : unit -> String // member OutputDirectories : unit -> String list at v6.0
  member SymbolDirectories : unit -> String list
  member Dependencies : unit -> String list
  member Keys : unit -> String list
  member StrongNameKey : unit -> String
  member XmlReport : unit -> String
  member FileFilter : unit -> String list
  member AssemblyFilter : unit -> String list
  member AssemblyExcludeFilter : unit -> String list
  member TypeFilter : unit -> String list
  member MethodFilter : unit -> String list
  member AttributeFilter : unit -> String list
  member PathFilter : unit -> String list
  member CallContext : unit -> String list
  member OpenCover : unit -> bool
  member InPlace : unit -> bool
  member Save : unit -> bool
  member Single : unit -> bool
  member LineCover : unit -> bool
  member BranchCover : unit -> bool
  member CommandLine : unit -> String seq
  member ExposeReturnCode : unit -> bool // new at 5.1
  member SourceLink : unit -> bool // new at 5.1
  member Defer : unit -> bool // new at 5.3
  member LocalSource : unit -> bool // new at 6.1
  member VisibleBranches : unit -> bool // new at 6.2
  member ShowStatic : unit -> string // new at 6.6
  member ShowGenerated : unit -> bool // new at 6.6

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. The other members are simple properties reading the values from the contained instance; null strings will be retrurned as null, but null sequences will be returned as empty ones. Fields that are not applicable to the use case or platform are silently ignored. WhatIf compiles the effective command-line and the result of Validate

[<NoComparison; NoEquality>]
type Logging =
  | Primitive of Primitive.Logging
  ...
  static member Create() : Logging
  static member ActionAdapter: Action<String> -> (String -> unit)
  member Error : unit -> (String -> unit)
  member self.Warn : unit -> (String -> unit)
  member self.Echo : unit -> (String -> unit)
  member self.Info : unit -> (String -> unit)

Create() returns a pure sink instance; ActionAdapter is a helper for C# use, and the others just return from the underlying structure.

module AltCover.Api (Requires qualified access)

This contains the core API methods

  • Prepare : FSApi.PrepareParams -> FSApi.Logging -> int
  • Collect : FSApi.CollectParams -> FSApi.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)

namespace AltCover

This contains the MSBuild tasks

Extended operations

The API is extended in AltCover.FSApi.dll, which includes APIs used by the PowerShell cmdlets, plus support for dotnet test integration

module AltCover.DotNet (Requires qualified access)

type CLIArgs =
  | Force of bool
  | FailFast of bool // new at v5.1
  | ShowSummary of String // new at v5.2
  | Many of CLIArgs seq // new at v5.1
  member ForceDelete : unit -> bool
  member Fast : unit -> bool  // new at v5.1
  member Summary : unit -> String // new at v5.2

controls whether a left-over __Saved directory from a previous run should be forcibly deleted (default false) -- see Issue #46

  • ToTestArgumentList : AltCover.FSApi.PrepareParams -> AltCover.FSApi.CollectParams -> AltCover.Dotnet.CLIArgs -> string list
  • ToTestArguments : AltCover.FSApi.PrepareParams -> AltCover.FSApi.CollectParams -> AltCover.Dotnet.CLIArgs -> 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.CoverageFormats (Requires qualified access)

  • 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

  • PostProcess: XDocument -> Ordinal -> unit and public static void PostProcess(XDocument document, Ordinal ordinal) to fill in the summary details in an OpenCover documentbased on the current coverage visit counts, where the enum AltCover.CoverageFormats.Ordinal has values Offset for data where the offset attributes are present and meaningful for comparison purposes such as computing branch exits, relating sequence and branch point entries, and SL where start lines have to be used as a fall back instead
  • FormatFromCoverlet: XDocument -> files:string array -> XDocument and `public static XDocument FormatFromCoverlet(XDocument document, string[] assemblies) to fill in as many gaps as possible in coverlet's dialect of OpenCover

module AltCover.OpenCoverUtilities (Requires qualified access)

  • 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 (Requires qualified access)

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

The input is in either NCover or OpenCover format

module AltCover.XmlUtilities (Requires qualified access)

  • 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

F# defined types

For C# programmers, the ValidatedCommandLine type has an interface that can be trated as

	public IEnumerable<string> Command { get; }
        public string[] Errors { get; }
        public override string ToString()

Basic Types

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

namespace AltCover.Parameters

    public interface ICollectArgs
    {
        string RecorderDirectory { get; }
        string WorkingDirectory { get; }
        string Executable { get; }
        string LcovReport { get; }
        string Threshold { get; }
        string Cobertura { get; }
        string OutputFile { get; }
        bool ExposeReturnCode { get; } // new at v5.1
        string SummaryFormat { get; } // new at v5.2
        string[] CommandLine { get; }

        FSApi.CollectParams ToParameters();

        string[] Validate(bool afterPreparation);
        ValidatedCommandLine WhatIf(bool afterPreparation); // new at 6.7
    }


    public interface IPrepareArgs
    {
        string InputDirectory { get; } // string[]  InputDirectories { get; } at v6.0
        string OutputDirectory { get; } // string[]  OutputDirectories { get; } at v6.0
        string[] SymbolDirectories { get; }
        string[] Dependencies { get; }
        string[] Keys { get; }
        string StrongNameKey { get; }
        string XmlReport { get; }
        string[] FileFilter { get; }
        string[] AssemblyFilter { get; }
        string[] AssemblyExcludeFilter { get; }
        string[] TypeFilter { get; }
        string[] MethodFilter { get; }
        string[] AttributeFilter { get; }
        string[] PathFilter { get; }
        string[] CallContext { get; }

        bool OpenCover { get; }
        bool InPlace { get; }
        bool Save { get; }
        bool Single { get; }
        bool LineCover { get; }
        bool BranchCover { get; }
        bool ExposeReturnCode { get; } // new at 5.1
        bool SourceLink { get; } // new at 5.1
        bool Defer { get; } // new at 5.3
        bool LocalSource { get; } // new at 6.1
        bool VisibleBranches { get; } // new at 6.2
        string ShowStatic { get; } // new at 6.6
        bool ShowGenerated { get; } // new at 6.6

        string[] CommandLine { get; }

        FSApi.PrepareParams ToParameters();

        string[] Validate();
        ValidatedCommandLine WhatIf(); //new at v6.7
    }

    public interface ILogArgs
    {
        Action<String> Info { get; }
        Action<String> Warn { get; }
        Action<String> Error { get; }
        Action<String> Echo { get; }

        FSApi.Logging ToParameters();
    }

    public interface ICLIArg
    {
        bool Force { get; }
    }

    public interface ICLIArg2 : ICLIArg // new at v5.1
    {
        bool FailFast { get; }
    }

    public interface ICLIArg3 : ICLIArg2 // new at v5.2
    {
        string ShowSummary { get; }
    }

namespace AltCover.Parameters.Primitive

Provides default implementations

    public interface CollectArgs : ICollectArgs
    {
        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; }
        public bool ExposeReturnCode { get; set; } // new at v5.1
        public string SummaryFormat { get; set; } // new at v5.2
        public string[] CommandLine { get; set; }

        public FSApi.CollectParams ToParameters();

        public string[] Validate(bool afterPreparation);
        public ValidatedCommandLine WhatIf(bool afterPreparation); // new at 6.7

        public static CollectArgs Create();      
    }


    public interface PrepareArgs : IPrepareArgs
    {
        public string InputDirectory { get; set; } // public string[] InputDirectories { get; set; } at v6.0
        public string OutputDirectory { get; set; } // public string[] OutputDirectory { get; set; } at v6.0
        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; }
        public bool ExposeReturnCode { get; set; } // new at 5.1
        public bool SourceLink { get; set; } // new at 5.1
        public bool Defer { get; set; } // new at 5.3
        public bool LocalSource { get; set; } // new at 6.1  
        public bool VisibleBranches { get; set; } // new at 6.2  
        public string ShowStatic { get; set; } // new at 6.6
        public bool ShowGenerated { get; set; } // new at 6.6

        public string[] CommandLine { get; set; }

        public FSApi.PrepareParams ToParameters();

        public string[] Validate();
        public ValidatedCommandLine WhatIf(); // new at 6.7

        public static PrepareArgs Create();        
    }

    public interface LogArgs : ILogArgs
    {
        public Action<String> Info { get; set; }
        public Action<String> Warn { get; set; }
        public Action<String> Error { get; set; }
        public Action<String> Echo { get; set; }

        public FSApi.Logging ToParameters();

        public static LogArgs Create();
    }

    public class CLIArgs : ICLIArg3 // new at v5.2 (as ICLIArg2 at v5.1, ICLIArg at v5.0)
    {
        public bool Force { get; set; }
        public bool FailFast { get; set; } // new at v5.1
        public string ShowSummary { get; set; } // new at v5.2
    }

The Create() methods return instances with all values empty, false or pure sink functions as approptiate to their type.

public static class AltCover.CSApi

  • public static int Prepare(IPrepareArgs p, ILogArgs l)
  • public static int Collect(ICollectArgs c, ILogArgs l)
  • public static string Ipmo()
  • public static string Version()
  • public static string ToTestArguments(IPrepareArgs p, ICollectArgs c, ICLIArg force)
  • public static string[] ToTestArgumentList(PrepareArgs p, CollectArgs c, ICLIArg force)

Fake integration

In AltCover.Fake.dll

module AltCover.Fake.Trace

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

type AltCover.Fake.Implementation

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

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

type AltCover.Fake.Api

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

wraps the core API functions. If the optional logging argument is not given, then AltCover.Fake.Trace.Default is assumed. The 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 string return is the location of the indicated command-line executable from the current NuGet package

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

  • member self.WithParameters (prepare:PrepareParams) (collect:CollectParams) : Fake.DotNet.DotNet.TestOptions (obsolete at v6.5)
  • member self.WithAltCoverParameters (prepare:PrepareParams) (collect:CollectParams) : Fake.DotNet.DotNet.TestOptions (from v6.5) Adds the result of AltCover.DotNet.ToTestArguments to the CustomParams member of the Common member
  • member self.WithImportModule () : Fake.DotNet.DotNet.TestOptions (obsolete at v6.6)
  • member self.WithAltCoverImportModule () : Fake.DotNet.DotNet.TestOptions (from v6.6) Adds "/p:AltCoverIpmo=true" to the CustomParams member of the Common member
  • member self.WithGetVersion () : Fake.DotNet.DotNet.TestOptions (obsolete at v6.6)
  • member self.WithAltCoverGetVersion () : Fake.DotNet.DotNet.TestOptions (from v6.6) Adds "/p:AltCoverGetVersion=true" to the CustomParams member of the Common member

Example

open AltCover
...
  let ForceTrue = DotNet.CLIArgs.Force true  
  let p2 = { Primitive.PrepareParams.Create() with CallContext = [| "[Fact]"; "0" |]
                                                   AssemblyFilter = [| "xunit" |] }
  let pp2 = FSApi.PrepareParams.Primitive p2
  let c2 = Primitive.CollectParams.Create()
  let cc2 = FSApi.CollectParams.Primitive c2

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

  DotNet.test
    (fun to' ->
    { to'.WithCommon(setBaseOptions).WithAltCoverParameters pp2 cc2 ForceTrue })
    "dotnettest.fsproj"

Cake integration

In AltCover.Cake.dll

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

which wraps 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; }
        public ICLIArg Force { get; set; }
        // Apply these settings in a pipeline
        public Func<ProcessArgumentBuilder, ProcessArgumentBuilder> Customize() // new at v6.6
        public Func<ProcessArgumentBuilder, ProcessArgumentBuilder> Concatenate(Func<ProcessArgumentBuilder, ProcessArgumentBuilder> customIn) // new at v6.6
    }

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. Equivalent to

            settings.ArgumentCustomization = altcover.Concatenate(settings.ArgumentCustomization);
            context.DotNetCoreTest(project.FullPath, settings);

Clone this wiki locally