DiffblueBuild.yaml

# Overview
# ========
#
# This file contains the arguments for invoking ant when using Diffblue Cover. Cover will render the command to
# execute based on the "phase" that's being executed by assembling the flags, and any filtering arguments. For
# example, if we're trying to execute the build phase on windows you can expect the invoked command to
# look (something) like:
#
# ant.cmd \
#  compile
#
# The first line comes from the 'cmd' stanza (selected by the renderer based on detected operating system). The next
# lines come from the `global` stanza (empty by default -- use this if you want to apply any options to _all_
# invocations), and the `build` phase configuration below.
#
# Phases
# ======
#
# There are (currently) eight phases that Cover progresses through during the various executions. They are listed
# below along with examples of commands where they're invoked:
#
# info      : dcover create             : gathering information about the structure of the project (child-modules, etc.);
#                                         the classpath is not guaranteed to be correctly resolved at this stage.
# classpath : dcover create             : computes the project structure and classpath of the project under test
# launcher  : dcover create             : downloads the JUnit Jupiter Launcher (only needed for Gradle projects)
# clean     : dcover build --clean      : cleans the existing target/build files from the modules
# build     : dcover build              : rebuilds the modules
# test      : dcover create             : runs the tests of the module, can be filtered based on type (e.g. Diffblue,
#                                         non-Diffblue, or a named test)
# coverage  : dcover coverage-reports   : runs the tests and records the coverage, can be filtered like the test phase
# refactor  : dcover fix-build          : applies any refactorings, unsupported outside of Maven or Gradle)
# validate  : dcover validate           : runs all the tests, both Diffblue and Manual
#
# Variable Substitution
# =====================
#
# Throughout this file there are a number of variables that need to be substituted to make the commands work. These
# are of the form ${VARIABLE}. For substitution to work the VARIABLE must match exactly one of the known variables
# (listed below), if it doesn't match exactly it will be filtered out.
#
# Supported Variables and Their Purpose
# -------------------------------------
#
# The list below contains all the variables that will be replaced.
#
# Launcher
# ***********************
# DIFFBLUE_GROUP_ID    : the group ID of the artifact to download (e.g. the JUnit Jupiter Launcher)
# DIFFBLUE_ARTIFACT_ID : the artifact ID of the artifact to download (e.g. the JUnit Jupiter Launcher)
# DIFFBLUE_VERSION     : the version of the artifact to download (e.g. the JUnit Jupiter Launcher)
#
# Refactor
# ********
# Refactoring requires installing jar files bundles with cover hence the long list of variables here
#
# DIFFBLUE_REWRITE_CONFIG                         : the location of the rewrite configuration to apply
# DIFFBLUE_COVER_REFACTORING_RECIPES_JAR          : the location of the recipes for refactoring
# DIFFBLUE_COVER_REFACTORING_RECIPES_GROUP_ID     : the group ID for the recipes for refactoring
# DIFFBLUE_COVER_REFACTORING_RECIPES_ARTIFACT_ID  : the artifact ID for the recipes for refactoring
# DIFFBLUE_COVER_REFACTORING_RECIPES_VERSION      : the version for the recipes for refactoring
# DIFFBLUE_OPEN_REWRITE_JAR                       : the location of the rewrite jar file
# DIFFBLUE_OPEN_REWRITE_POM                       : the location of the rewrite pom file
# DIFFBLUE_OPEN_REWRITE_GROUP_ID                  : the group ID for the rewrite jar/pom files
# DIFFBLUE_OPEN_REWRITE_ARTIFACT_ID               : the artifact ID for the rewrite jar/pom files
# DIFFBLUE_OPEN_REWRITE_VERSION                   : the version for the rewrite jar/pom files
#
# Gradle Specific
# ***************
# MODULE_PATH                             : the path to the module separated by colons, e.g. project:application
# DIFFBLUE_GRADLE_INIT_SCRIPT             : the location of the Gradle init script, e.g. .diffblue/init.gradle
# DIFFBLUE_GRADLE_SPY_JAR                 : the location of the Gradle event listener classes
# DIFFBLUE_TEST_CLASS                     : the name of a single class containing tests to execute, used during the env checks
# DIFFBLUE_TEST_CLASS_REGEX               : the pattern matching class names containing created tests, e.g. **/*DiffblueTest**
# DIFFBLUE_TEST_CLASS_GLOB_PATTERN        : the pattern matching file names containing created tests, e.g. **/*DiffblueTest**
# DIFFBLUE_TEST_CLASS_REGEX_PATTERN       : the regex matching class names containing created tests, e.g. .*DiffblueTest.*
# DIFFBLUE_COVER_REFACTORING_INIT_SCRIPT  : the location of the Gradle init script to apply when configuring refactoring
#
# Maven Specific
# **************
# MODULE                             : the name of the module, e.g. application
# DIFFBLUE_JACOCO_VERSION            : the version of the Jacoco Maven plugin to use
# DIFFBLUE_MAVEN_USER_SETTINGS       : the location of the Maven user settings.xml configuration file
# DIFFBLUE_MAVEN_GLOBAL_SETTINGS     : the location of the Maven global settings.xml configuration file
# DIFFBLUE_MAVEN_SPY_JAR             : the location of the Maven event listener classes
# DIFFBLUE_TEST_FILE                 : the name of a single file containing tests to execute, used during the env checks
# DIFFBLUE_TEST_FILE_REGEX           : the pattern matching file names containing created tests, e.g. **/*DiffblueTest*.java
# DIFFBLUE_TEST_FILE_GLOB_PATTERN    : the pattern matching file names containing created tests, e.g. **/*DiffblueTest*.java
# DIFFBLUE_TEST_FILE_REGEX_PATTERN   : the regex matching class names containing created tests, e.g. .*DiffblueTest.*\.java
# DIFFBLUE_TEST_CLASS_GLOB_PATTERN   : the pattern matching file names containing created tests, e.g. **/*DiffblueTest**
# DIFFBLUE_TEST_CLASS_REGEX_PATTERN  : the regex matching class names containing created tests, e.g. .*DiffblueTest.*
#
# Note: Only the MODULE_PATH can be the empty string, all other variables that evaluate to the empty string will be
# filtered out before being executed.

meta:
  version: 3.1
  # The tool name is used to key the configuration internally. We have two known tool names, either maven or gradle.
  # If one of these is used by a user-provided file, the intent is that the user-provided configuration will supersede
  # the configuration here.
  toolName: ant

cmd:
  # The commands to try to run when executing this build system. Configured on an operating system basis, and tried
  # in turn (when there are multiple entries) until either the list is exhausted or one of the commands works.
  windows:
    - ant.cmd
    - ant.bat
    - ant
  linux:
    - ant
  macos:
    - ant
global:
  # The flags in the global section apply to all the invocations of the commands
  flags:
    - -Dcover=true

  # The timeout for all the phases unless a phase specific timeout value has been set.
  timeout: PT10M

  plugins: ~
    # Plugins aren't supported in the ant build system.

# The phases are named according to `dcover`'s needs and aren't specific to any build system (despite some overlap).
# The idea is that each phase provides a list of build system `goals` which will be combined into a single invocation.
phase:

  # The info phase is used early on to gather information about the structure of the project under test.
  # The dependencies have to have been resolved (i.e. be present on the file system and they should be able to
  # discover the path to them) for this to work correctly.
  info:
    goals:
      - name: ~
        goal: info
        flags: ~

  # The classpath phase is used to compute the classpath including the dependencies of the project under test.
  classpath:
    goals:
      - name: ~
        goal: info
        flags: ~

  # This is used to download the JUnit Launcher jar - shouldn't be needed for ant projects.
  launcher: ~

  # The clean phase is used to remove any compiled class files, reports, etc. from the module under test.
  clean:
    goals:
      - name: ~
        goal: clean
        flags: ~

  # The build phase is used to compile the module under test.
  build:
    goals:
      - name: ~
        goal: compile
        flags: ~

  # The test phase is used to run the module under test's tests. This allows a filter to be specified to
  # include/exclude tests that match patterns, or run a single named test.
  #
  # This assumes that the includes/excludes properties are configured via properties:
  #
  #    <property name="test.includes" value="**/*Test.*"/>
  #    <property name="test.excludes" value="*"/>
  #    <property name="test.excludeTags" value=""/>
  #    <property name="test.excludeTags" value=""/>
  #
  # These can then be used in the junitlauncher element and the attributes of a fileset like this:
  #
  #    <junitlauncher includeTags="${test.includeTags}" excludeTags="${test.excludeTags}">
  #
  #  and
  #
  #  <fileset dir="${class.dir}" includes="${test.includes}" excludes="${test.excludes}"/>
  #
  test:

    # Allow the tests to run for 60 minutes
    timeout: PT60M

    goals:
      - name: ~
        goal: test
        flags:
          - ${DIFFBLUE_TEST_FILTER}

    filter:
      # By default, all tests are executed
      default: ~

      # To execute tests that Diffblue hasn't created (often referred to manual tests in Cover Reports).
      neverDiffblue:
        - -Dtest.excludes=**/*DiffblueTest.*

      # To execute tests that Diffblue hasn't created taking into account the "MaintainedByDiffblue"
      # or "ContributionFromDiffblue" tags
      neverDiffblueTag:
        - -Dtest.excludes=**/*DiffblueTest.*
        - -Dtest.excludeTags=MaintainedByDiffblue,ContributionFromDiffblue

      # To execute only the Diffblue-created tests, then pass this parameter
      onlyDiffblue:
        - -Dtest.includes=**/*DiffblueTest.*

      # To execute only the Diffblue-created tests in non-DiffblueTest classes,
      # using the "MaintainedByDiffblue" or "ContributionFromDiffblue" tags, then pass this parameter
      onlyDiffblueTag:
        - -Dtest.excludes=**/*DiffblueTest.*
        - -Dtest.includeTags=MaintainedByDiffblue,ContributionFromDiffblue

      # To run a single test, apply this option
      named:
        - -Dtest.includes=**/${DIFFBLUE_TEST_FILE}.*

  # The coverage phase measures the coverage of the tests. It's executed a number of times with different filters
  # applied (to measure the coverage of all, non-diffblue, and diffblue tests).
  #
  # This assumes that the includes/excludes properties are configured via properties:
  #
  #    <property name="test.includes" value="**/*Test.*"/>
  #    <property name="test.excludes" value="*"/>
  #    <property name="test.excludeTags" value=""/>
  #    <property name="test.excludeTags" value=""/>
  #
  # These can then be used in the junitlauncher element and the attributes of a fileset like this:
  #
  #    <junitlauncher includeTags="${test.includeTags}" excludeTags="${test.excludeTags}">
  #
  #  and
  #
  #  <fileset dir="${class.dir}" includes="${test.includes}" excludes="${test.excludes}"/>
  #
  coverage:
    timeout: PT60M
    goals:

      - name: ~
        goal: test
        flags:
          - ${DIFFBLUE_TEST_FILTER}

    filter:
      # By default, all tests are executed
      default: ~

      # To execute tests that Diffblue hasn't created (often referred to manual tests in Cover Reports).
      neverDiffblue:
        - -Dtest.excludes=**/*DiffblueTest.*

      # To execute tests that Diffblue hasn't created taking into account the "MaintainedByDiffblue"
      # or "ContributionFromDiffblue" tags
      neverDiffblueTag:
        - -Dtest.excludes=**/*DiffblueTest.*
        - -Dtest.excludeTags=MaintainedByDiffblue,ContributionFromDiffblue

      # To execute only the Diffblue-created tests, then pass this parameter
      onlyDiffblue:
        - -Dtest.includes=**/*DiffblueTest.*

      # To execute only the Diffblue-created tests in non-DiffblueTest classes,
      # using the "MaintainedByDiffblue" or "ContributionFromDiffblue" tags, then pass this parameter
      onlyDiffblueTag:
        - -Dtest.excludes=**/*DiffblueTest.*
        - -Dtest.includeTags=MaintainedByDiffblue,ContributionFromDiffblue

      # To run a single test, apply this option
      named:
        - -Dtest.includes=**/${DIFFBLUE_TEST_FILE}.java

  # The refactor phase is not supported for build systems other than maven or gradle.
  refactor: ~

  # The validate phase checks to make sure that the tests that have been created will work in the project
  validate:
    timeout: PT60M
    goals:
      - name: ~
        goal: clean
        flags: ~

      - name: ~
        goal: test
        flags: ~