Package rife.bld.extension

Class PitestOperation

java.lang.Object
rife.bld.operations.AbstractOperation<T>
rife.bld.operations.AbstractProcessOperation<PitestOperation>
rife.bld.extension.PitestOperation
public class PitestOperation extends AbstractProcessOperation<PitestOperation>
Mutation testing and coverage with PIT.
Since:
1.0
Author:
Erik C. Thauvin

  • Field Details

  • Constructor Details

    • PitestOperation

      public PitestOperation()

  • Method Details

    • argLine

      public PitestOperation argLine(String line)
      Line arguments for child JVMs.
      Parameters:
      line - the line arguments
      Returns:
      this operation instance

    • avoidCallsTo

      public PitestOperation avoidCallsTo(Collection<String> avoidCallsTo)
      List of packages and classes which are to be considered outside the scope of mutation. Any lines of code containing calls to these classes will not be mutated.

      If a list is not explicitly supplied then PIT will default to a list of common logging packages as follows

      • java.util.logging
      • org.apache.log4j
      • org.slf4j
      • org.apache.commons.logging

      If the feature FLOGCALL is disabled, this parameter is ignored and logging calls are also mutated.

      Parameters:
      avoidCallsTo - the list of packages
      Returns:
      this operation instance
      See Also:

    • avoidCallsTo

      public PitestOperation avoidCallsTo(String... avoidCallTo)
      List of packages and classes which are to be considered outside the scope of mutation. Any lines of code containing calls to these classes will not be mutated.

      If a list is not explicitly supplied then PIT will default to a list of common logging packages as follows

      • java.util.logging
      • org.apache.log4j
      • org.slf4j
      • org.apache.commons.logging

      If the feature FLOGCALL is disabled, this parameter is ignored and logging calls are also mutated.

      Parameters:
      avoidCallTo - one or more packages
      Returns:
      this operation instance
      See Also:

    • classPath

      public PitestOperation classPath(String... path)
      List of packages and classes which are to be considered outside the scope of mutation. Any lines of code containing calls to these classes will not be mutated.

      If a list is not explicitly supplied then PIT will default to a list of common logging packages as follows

      • java.util.logging
      • org.apache.log4j
      • org.slf4j
      • org.apache.commons.logging

      If the feature FLOGCALL is disabled, this parameter is ignored and logging calls are also mutated. Additional classpath entries to use when looking for tests and mutable code.

      Parameters:
      path - one or more paths
      Returns:
      this operation instance
      See Also:

    • classPath

      public PitestOperation classPath(Collection<String> path)
      Additional classpath entries to use when looking for tests and mutable code.
      Parameters:
      path - the list of paths
      Returns:
      this operation instance
      See Also:

    • classPathFile

      public PitestOperation classPathFile(String file)
      File with a list of additional classpath elements (one per line).
      Parameters:
      file - the file
      Returns:
      this operation instance

    • coverageThreshold

      public PitestOperation coverageThreshold(int threshold)
      Line coverage threshold below which the build will fail. This is an integer percent (0-100) that represents the fraction of the project covered by the tests.
      Parameters:
      threshold - the threshold
      Returns:
      this operation instance

    • detectInlinedCode

      public PitestOperation detectInlinedCode(boolean isDetectInlinedCode)
      Flag to indicate if PIT should attempt to detect the inlined code generated by the java compiler in order to implement finally blocks. Each copy of the inlined code would normally be mutated separately, resulting in multiple identical looking mutations. When inlined code detection is enabled PIT will attempt to spot inlined code and create only a single mutation that mutates all affected instructions simultaneously.

      The algorithm cannot easily distinguish between inlined copies of code, and genuine duplicate instructions on the same line within a finally block.

      In the case of any doubt PIT will act cautiously and assume that the code is not inlined.

      This will be detected as two separate inlined instructions 

       finally {
   int++;
   int++;
 }
      But this will look confusing so PIT will assume no in-lining is taking place. 
       finally {
   int++; int++;
 }
      This sort of pattern might not be common with integer addition, but things like string concatenation are likely to produce multiple similar instructions on the same line.

      Defaults to true

      Parameters:
      isDetectInlinedCode - true or false
      Returns:
      this operation instance

    • excludedClasses

      public PitestOperation excludedClasses(String... excludedClass)
      List of globs to match against class names. Matching classes will be excluded from mutation.
      Parameters:
      excludedClass - the excluded classws
      Returns:
      this operation instance
      See Also:

    • excludedClasses

      public PitestOperation excludedClasses(Collection<String> excludedClasses)
      List of globs to match against class names. Matching classes will be excluded from mutation.
      Parameters:
      excludedClasses - the excluded classes
      Returns:
      this operation instance
      See Also:

    • excludedGroups

      public PitestOperation excludedGroups(String... excludedGroup)
      List of TestNG groups/JUnit categories to include in mutation analysis. Note that only class level categories are supported.
      Parameters:
      excludedGroup - one or more excluded groups
      Returns:
      this operation instance
      See Also:

    • excludedGroups

      public PitestOperation excludedGroups(Collection<String> excludedGroups)
      List of TestNG groups/JUnit categories to include in mutation analysis. Note that only class level categories are supported.
      Parameters:
      excludedGroups - the excluded groups
      Returns:
      this operation instance
      See Also:

    • excludedMethods

      public PitestOperation excludedMethods(String... excludedMethod)
      List of globs to match against method names. Methods matching the globs will be excluded from mutation.
      Parameters:
      excludedMethod - one or more excluded methods
      Returns:
      this operation instance
      See Also:

    • excludedMethods

      public PitestOperation excludedMethods(Collection<String> excludedMethods)
      List of globs to match against method names. Methods matching the globs will be excluded from mutation.
      Parameters:
      excludedMethods - the excluded methods
      Returns:
      this operation instance
      See Also:

    • excludedTests

      public PitestOperation excludedTests(String... excludedTest)
      List of globs to match against test class names. Matching tests will not be run (note if a test suite includes an excluded class, then it will “leak” back in).
      Parameters:
      excludedTest - one ore more excluded tests
      Returns:
      this operation instance
      See Also:

    • excludedTests

      public PitestOperation excludedTests(Collection<String> excludedTests)
      List of globs to match against test class names. Matching tests will not be run (note if a test suite includes an excluded class, then it will “leak” back in).
      Parameters:
      excludedTests - the excluded tests
      Returns:
      this operation instance
      See Also:

    • executeConstructProcessCommandList

      protected List<String> executeConstructProcessCommandList()
      Part of the AbstractProcessOperation.execute() operation, constructs the command list to use for building the process.
      Specified by:
      executeConstructProcessCommandList in class AbstractProcessOperation<PitestOperation>

    • fromProject

      public PitestOperation fromProject(BaseProject project)
      Configures the operation from a BaseProject.
      Specified by:
      fromProject in class AbstractProcessOperation<PitestOperation>
      Parameters:
      project - the project to configure the operation from
      Since:
      1.5

    • exportLineCoverage

      public PitestOperation exportLineCoverage(boolean jsExport)
      Whether or not to dump per test line coverage data to disk.

      Defaults to false

      Parameters:
      jsExport - true or false
      Returns:
      this operation instance

    • failWhenNoMutations

      public PitestOperation failWhenNoMutations(boolean isFail)
      Whether to throw an error when no mutations found.

      Defaults to true

      Parameters:
      isFail - true or false
      Returns:
      this operation instance

    • features

      public PitestOperation features(Collection<String> feature)
      List of features to enable/disable
      Parameters:
      feature - the list of features
      Returns:
      this operation instance
      See Also:

    • features

      public PitestOperation features(String... feature)
      List of features to enable/disable
      Parameters:
      feature - one or more features
      Returns:
      this operation instance
      See Also:

    • historyInputLocation

      public PitestOperation historyInputLocation(String path)
      Path to a file containing history information for incremental analysis.
      Parameters:
      path - the path
      Returns:
      this operation instance

    • historyOutputLocation

      public PitestOperation historyOutputLocation(String path)
      Path to write history information for incremental analysis. May be the same as historyInputLocation(String)
      Parameters:
      path - the path
      Returns:
      this operation instance

    • includeLaunchClasspath

      public PitestOperation includeLaunchClasspath(boolean isLaunchClasspath)
      Indicates if the PIT should try to mutate classes on the classpath with which it was launched. If not supplied this flag defaults to true. If set to false only classes found on the paths specified by the classPath

      Defaults to true

      Parameters:
      isLaunchClasspath - true or false
      Returns:
      this operation instance

    • includedGroups

      public PitestOperation includedGroups(String... includedGroup)
      list of TestNG groups/JUnit categories to include in mutation analysis. Note that only class level categories are supported.
      Parameters:
      includedGroup - one or more included groups
      Returns:
      this operation instance
      See Also:

    • includedGroups

      public PitestOperation includedGroups(Collection<String> includedGroups)
      list of TestNG groups/JUnit categories to include in mutation analysis. Note that only class level categories are supported.
      Parameters:
      includedGroups - the list of included groups
      Returns:
      this operation instance
      See Also:

    • jvmArgs

      public PitestOperation jvmArgs(String... args)
      Argument string to use when PIT launches child processes. This is most commonly used to increase the amount of memory available to the process, but may be used to pass any valid JVM argument.
      Parameters:
      args - one or moe args
      Returns:
      this operation instance
      See Also:

    • jvmArgs

      public PitestOperation jvmArgs(Collection<String> args)
      Argument string to use when PIT launches child processes. This is most commonly used to increase the amount of memory available to the process, but may be used to pass any valid JVM argument.
      Parameters:
      args - the list of args
      Returns:
      this operation instance
      See Also:

    • jvmPath

      public PitestOperation jvmPath(String path)
      The path to the java executable to be used to launch test with. If none is supplied defaults to the one pointed to by JAVA_HOME.
      Parameters:
      path - the path
      Returns:
      this operation instance

    • mutableCodePaths

      public PitestOperation mutableCodePaths(String... path)
      List of classpaths which should be considered to contain mutable code. If your build maintains separate output directories for tests and production classes this parameter should be set to your code output directory in order to avoid mutating test helper classes etc.

      If no mutableCodePath is supplied PIT will default to considering anything not defined within a jar or zip file as being a candidate for mutation.

      PIT will always attempt not to mutate test classes even if they are defined on a mutable path.

      Parameters:
      path - one or one paths
      Returns:
      this operation instance
      See Also:

    • mutableCodePaths

      public PitestOperation mutableCodePaths(Collection<String> paths)
      List of classpaths which should be considered to contain mutable code. If your build maintains separate output directories for tests and production classes this parameter should be set to your code output directory in order to avoid mutating test helper classes etc.

      If no mutableCodePath is supplied PIT will default to considering anything not defined within a jar or zip file as being a candidate for mutation.

      PIT will always attempt not to mutate test classes even if they are defined on a mutable path.

      Parameters:
      paths - the list of paths
      Returns:
      this operation instance
      See Also:

    • mutationThreshold

      public PitestOperation mutationThreshold(int threshold)
      Mutation score threshold below which the build will fail. This is an integer percent (0-100) that represents the fraction of killed mutations out of all mutations.

      Please bear in mind that your build may contain equivalent mutations. Careful thought must therefore be given when selecting a threshold.

      Parameters:
      threshold - the threshold
      Returns:
      this operation instance

    • mutators

      public PitestOperation mutators(String... mutator)
      List of mutation operators.
      Parameters:
      mutator - one or more mutators
      Returns:
      this operation instance
      See Also:

    • mutators

      public PitestOperation mutators(Collection<String> mutators)
      List of mutation operators.
      Parameters:
      mutators - the list of mutators
      Returns:
      this operation instance
      See Also:

    • outputEncoding

      public PitestOperation outputEncoding(String encoding)
      Output encoding.

      Default is UTF-8.

      Parameters:
      encoding - the encoding
      Returns:
      this operation instance

    • outputFormats

      public PitestOperation outputFormats(String... outputFormat)
      Comma separated list of formats in which to write mutation results as the mutations are analysed. Supported formats are HTML, XML, CSV.

      Defaults to HTML.

      Parameters:
      outputFormat - one or more output formats
      Returns:
      this operation instance
      See Also:

    • outputFormats

      public PitestOperation outputFormats(Collection<String> outputFormats)
      Comma separated list of formats in which to write mutation results as the mutations are analysed. Supported formats are HTML, XML, CSV.

      Defaults to HTML.

      Parameters:
      outputFormats - the list of output formats
      Returns:
      this operation instance
      See Also:

    • reportDir

      public PitestOperation reportDir(String dir)
      Output directory for the reports.
      Parameters:
      dir - the directory
      Returns:
      this operation instance

    • skipFailingTests

      public PitestOperation skipFailingTests(boolean isSkipFail)
      whether to ignore failing tests when computing coverage.

      Default is false

      Parameters:
      isSkipFail - true or false
      Returns:
      this operation instance

    • sourceDirs

      public PitestOperation sourceDirs(String... dir)
      The folder(s) containing the source code.
      Parameters:
      dir - one or more directories
      Returns:
      this operation instance
      See Also:

    • sourceDirs

      public PitestOperation sourceDirs(Collection<String> dirs)
      The folder(s) containing the source code.
      Parameters:
      dirs - the list of directories
      Returns:
      this operation instance
      See Also:

    • targetClasses

      public PitestOperation targetClasses(Collection<String> targetClass)
      The classes to be mutated. This is expressed as a list of globs.

      For example:

      • com.myompany.*
      • com.mycompany.package.*, com.mycompany.packageB.Foo, com.partner.*

      Parameters:
      targetClass - the list of target classes
      Returns:
      this operation instance
      See Also:

    • targetClasses

      public PitestOperation targetClasses(String... targetClass)
      The classes to be mutated. This is expressed as a list of globs.

      For example:

      • com.myompany.*
      • com.mycompany.package.*, com.mycompany.packageB.Foo, com.partner.*

      Parameters:
      targetClass - one or more target classes
      Returns:
      this operation instance
      See Also:

    • targetTests

      public PitestOperation targetTests(String... test)
      A comma separated list of globs can be supplied to this parameter to limit the tests available to be run. If this parameter is not supplied then any test fixture that matched targetClasses may be used, it is however recommended that this parameter is always explicitly set.

      This parameter can be used to point PIT to a top level suite or suites. Custom suites such as ClassPathSuite are supported.

      Parameters:
      test - one ore more tests
      Returns:
      this operation instance
      See Also:

    • targetTests

      public PitestOperation targetTests(Collection<String> tests)
      A comma separated list of globs can be supplied to this parameter to limit the tests available to be run. If this parameter is not supplied then any test fixture that matched targetClasses may be used, it is however recommended that this parameter is always explicitly set.

      This parameter can be used to point PIT to a top level suite or suites. Custom suites such as ClassPathSuite are supported.

      Parameters:
      tests - the list of tests
      Returns:
      this operation instance
      See Also:

    • threads

      public PitestOperation threads(int threads)
      The number of threads to use when mutation testing.
      Parameters:
      threads - the threads count
      Returns:
      this operation instance

    • timeoutConst

      public PitestOperation timeoutConst(int factor)
      Constant amount of additional time to allow a test to run for (after the application of the timeoutFactor) before considering it to be stuck in an infinite loop.

      Defaults to 4000

      Parameters:
      factor - the factor amount
      Returns:
      this operation instance

    • timeoutFactor

      public PitestOperation timeoutFactor(double factor)
      A factor to apply to the normal runtime of a test when considering if it is stuck in an infinite loop.

      Defaults to 1.25

      Parameters:
      factor - the factor
      Returns:
      this operation instance

    • timestampedReports

      public PitestOperation timestampedReports(boolean isTimestamped)
      By default, PIT will create a date and time stamped folder for its output each time it is run. This can can make automation difficult, so the behaviour can be suppressed by passing false.

      Defaults to false

      Parameters:
      isTimestamped - true or false
      Returns:
      this operation instance

    • useClasspathJar

      public PitestOperation useClasspathJar(boolean isUseClasspathJar)
      Support large classpaths by creating a classpath jar.

      Defaults to false

      Parameters:
      isUseClasspathJar - true or false
      Returns:
      this operation instance

    • verbose

      public PitestOperation verbose(boolean isVerbose)
      Output verbose logging.

      Defaults to false

      Parameters:
      isVerbose - true or false
      Returns:
      this operation instance