Doc: improve diff test selection documentation FIX #768

README.md

@@ -314,35 +314,50 @@ Each command line options is translated into an option for the maven plugin. You
     * `--output-path output` gives `-Doutput-path=output`
 
 For options that take list, the used separator is a comma `,`, whatever the platform you use.
-
+
+### Specific options for dspot-maven
+
+* `path-to-test-list-csv`: Enable the selection of the test to be amplified from a csv file.
+    This parameter is a path that must point to a csv file that list test classes and their test methods in the following format:
+    test-class-name;test-method-1;test-method-2;test-method-3;...
+    If this parameter is used, DSpot will ignore the value used in the parameter test and cases
+    It is recommended to use an absolute path
+    Such files can be computed by the dedicated module [dspot-diff-test-selection](https://github.com/STAMP-project/dspot/tree/master/dspot-diff-test-selection).
+
+* `path-to-second-version`: Allows to specify the path to the second version through command line, rather than using properties file.
+    This parameter is the same than [ConstantsProperties#PATH_TO_SECOND_VERSION](https://github.com/STAMP-project/dspot/blob/master/dspot/src/main/java/eu/stamp_project/utils/program/ConstantsProperties.java#L97)
+    If this parameter is used, DSpot will ignore the value used in the properties file.
+    It is recommended to use an absolute path.
+
+    To be used, maven options must be precede by a `-D` and must be separated from their value with `=`, _e.g._ `-Dpath-to-test-list-csv=testsThatExecuteTheChange.csv` 
 
 ### Configuration
 
 Here is the list of configuration properties of DSpot:
 
 * Required properties
-	* project: specify the path to the root of the project. This path can be either absolute (recommended) or relative to the working directory of the DSpot process. We consider as root of the project folder that contain the top-most parent in a multi-module project.
+	* `project`: specify the path to the root of the project. This path can be either absolute (recommended) or relative to the working directory of the DSpot process. We consider as root of the project folder that contain the top-most parent in a multi-module project.
 * Optional properties
-	* targetModule: specify the module to be amplified. This value must be a relative path from the property project. If your project is multi-module, you must use this property because DSpot works at module level.
-	* src: specify the relative path from project/targetModule of the folder that contain sources (.java).(default: src/main/java/)
-	* testSrc: specify the relative path from project/targetModule of the folder that contain test sources (.java).(default: src/test/java/)
-	* classes: specify the relative path from project/targetModule of the folder that contain binaries of the source program (.class).(default: target/classes/)
-	* testclasses: specify the relative path from project/targetModule of the folder that contain binaries of the test source program (.class).(default: target/test-classes/)
-	* additionalClasspathElements: specify additional classpath elements. (_e.g._ a jar file) This value should be a list of relative paths from project/targetModule. Elements of the list must be separated by a comma ','.
-	* systemProperties: specify system properties. This value should be a list of couple property;value, separated by a comma ','. For example, systemProperties=admin=toto,passwd=tata. This define two system properties.
-	* outputDirectory: specify a path folder for the output.
-	* delta: specify the delta value for the assertions of floating-point numbers. If DSpot generates assertions for float, it uses Assert.assertEquals(expected, actual, delta). This property specify the delta value.(default: 0.1)
-	* excludedClasses: specify the full qualified name of excluded test classes. Each qualified name must be separated by a comma ','. These classes won't be amplified, nor executed during the mutation analysis, if the PitMutantScoreSelector is used.This property can be valued by a regex.
-	* excludedTestCases: specify the list of test cases to be excluded. Each is the name of a test case, separated by a comma ','.
-	* mavenHome: specify the maven home directory. This property is redundant with the command line option `--maven-home`. This property has the priority over the command line. If this property is not specified, nor the command line option `--maven-home,` `DSpot` will first look in both MAVEN_HOME and M2_HOME environment variables. If these variables are not set, DSpot will look for a maven home at default locations /usr/share/maven/, /usr/local/maven-3.3.9/ and /usr/share/maven3/.
-	* mavenPreGoals: specify pre goals to run before executing test with maven.This property will used as follow: the elements, separated by a comma,must be valid maven goals and they will be placed just before the "test" goal, _e.g._maven.pre.goals=preGoal1,preGoal2 will give "mvn preGoal1 preGoal2 test"
-	* folderPath: when using the ChangeDetectorSelector or the command-line option-value `--test diff`, you must specify this property. This property should have for value the path to the root of the second version of the project. It is recommended to give an absolute path
-	* automaticBuilderName: specify the type of automatic builder. This properties is redundant with the command line option `--automatic-builder`. It should have also the same value: (MavenBuilder | GradleBuilder). This property has the priority over the command line.
-	* pitVersion: specify the version of PIT to use.(default: 1.4.0)
-	* jvmArgs: specify JVM args to use when executing the test, PIT or other java process. This arguments should be a list, separated by a comma ',', _e.g._ jvmArgs=Xmx2048m,-Xms1024m',-Dis.admin.user=admin,-Dis.admin.passwd=$2pRSid#
-	* pitFilterClassesToKeep: specify the filter of classes to keep used by PIT. If you use PitMutantScoreSelector, we recommend you to set this property to your top-most package. This value will allow PIT to mutant all your code. However, if you want to restrict the scope of the mutation, you can specify a custom regex. If you do not specify any value, DSpot will compute a filter of classes to keep on the fly, trying to match the most of your classes, _i.e._ your top-most package.
-	* descartesVersion: specify the version of pit-descartes to use.(default: 1.2.4)
-	* descartesMutators: specify the list of descartes mutators to be used separated by comma. Please refer to the descartes documentation for more details: https://github.com/STAMP-project/pitest-descartes
+	* `targetModule`: specify the module to be amplified. This value must be a relative path from the property project. If your project is multi-module, you must use this property because DSpot works at module level.
+	* `src`: specify the relative path from project/targetModule of the folder that contain sources (.java).(default: src/main/java/)
+	* `testSrc`: specify the relative path from project/targetModule of the folder that contain test sources (.java).(default: src/test/java/)
+	* `classes`: specify the relative path from project/targetModule of the folder that contain binaries of the source program (.class).(default: target/classes/)
+	* `testClasses`: specify the relative path from project/targetModule of the folder that contain binaries of the test source program (.class).(default: target/test-classes/)
+	* `additionalClasspathElements`: specify additional classpath elements. (_e.g._ a jar file) This value should be a list of relative paths from project/targetModule. Elements of the list must be separated by a comma ','.
+	* `systemProperties`: specify system properties. This value should be a list of couple property;value, separated by a comma ','. For example, systemProperties=admin=toto,passwd=tata. This define two system properties.
+	* `outputDirectory`: specify a path folder for the output.
+	* `delta`: specify the delta value for the assertions of floating-point numbers. If DSpot generates assertions for float, it uses Assert.assertEquals(expected, actual, delta). This property specify the delta value.(default: 0.1)
+	* `excludedClasses`: specify the full qualified name of excluded test classes. Each qualified name must be separated by a comma ','. These classes won't be amplified, nor executed during the mutation analysis, if the PitMutantScoreSelector is used.This property can be valued by a regex.
+	* `excludedTestCases`: specify the list of test cases to be excluded. Each is the name of a test case, separated by a comma ','.
+	* `mavenHome`: specify the maven home directory. This property is redundant with the command line option `--maven-home`. This property has the priority over the command line. If this property is not specified, nor the command line option `--maven-home,` `DSpot` DSpot will first look in both MAVEN_HOME and M2_HOME environment variables. If these variables are not set, DSpot will look for a maven home at default locations /usr/share/maven/, /usr/local/maven-3.3.9/ and /usr/share/maven3/.
+	* `mavenPreGoals`: specify pre goals to run before executing test with maven.This property will used as follow: the elements, separated by a comma,must be valid maven goals and they will be placed just before the "test" goal, _e.g._maven.pre.goals=preGoal1,preGoal2 will give "mvn preGoal1 preGoal2 test"
+	* `pathToSecondVersion`: when using the ChangeDetectorSelector, you must specify this property. This property should have for value the path to the root of the second version of the project. It is recommended to give an absolute path
+	* `automaticBuilderName`: specify the type of automatic builder. This properties is redundant with the command line option `--automatic-builder`. It should have also the same value: (MavenBuilder | GradleBuilder). This property has the priority over the command line.
+	* `pitVersion`: specify the version of PIT to use.(default: 1.4.0)
+	* `jvmArgs`: specify JVM args to use when executing the test, PIT or other java process. This arguments should be a list, separated by a comma ',', _e.g._ jvmArgs=Xmx2048m,-Xms1024m',-Dis.admin.user=admin,-Dis.admin.passwd=$2pRSid#
+	* `pitFilterClassesToKeep`: specify the filter of classes to keep used by PIT. If you use PitMutantScoreSelector, we recommend you to set this property to your top-most package. This value will allow PIT to mutant all your code. However, if you want to restrict the scope of the mutation, you can specify a custom regex. If you do not specify any value, DSpot will compute a filter of classes to keep on the fly, trying to match the most of your classes, _i.e._ your top-most package.
+	* `descartesVersion`: specify the version of pit-descartes to use.(default: 1.2.4)
+	* `descartesMutators`: specify the list of descartes mutators to be used separated by comma. Please refer to the descartes documentation for more details: https://github.com/STAMP-project/pitest-descartes
 You can find an example of properties file [here](https://github.com/STAMP-project/dspot/blob/master/dspot/src/test/resources/sample/sample.properties)).
 
 #### Amplifiers (-a | --amplifiers)

dspot-diff-test-selection/src/main/java/eu/stamp_project/diff_test_selection/configuration/Options.java

@@ -5,6 +5,9 @@
 import eu.stamp_project.diff_test_selection.diff.DiffComputer;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import spoon.reflect.declaration.CtClass;
+import spoon.reflect.reference.CtExecutableReference;
+import spoon.reflect.visitor.filter.TypeFilter;
 
 import java.io.File;
 import java.util.Arrays;

dspot-diff-test-selection/src/main/java/eu/stamp_project/diff_test_selection/maven/DiffTestSelectionMojo.java

@@ -16,6 +16,12 @@ public class DiffTestSelectionMojo extends AbstractMojo {
     @Parameter(defaultValue = "${project}", required = true, readonly = true)
     private MavenProject project;
 
+    /**
+     *	[Mandatory] Specify the path to root directory of the project in the first version.
+     */
+    @Parameter(property = "path-dir-first-version")
+    private String pathDirFirstVersion;
+
     /**
      *	[Mandatory] Specify the path to root directory of the project in the second version.
      */

dspot-diff-test-selection/src/test/resources/tavern/src/main/resources/tavern.properties

@@ -10,5 +10,4 @@ javaVersion=8
 filter=fr.inria.stamp.*
 #path to the output folder
 outputDirectory=output
-configPath=src/main/resources/tavern.properties
-folderPath=../tavern-refactor
+pathToSecondVersion=../tavern-refactor

dspot-maven/src/main/java/eu/stamp_project/DSpotMojo.java

@@ -84,7 +84,7 @@ public class DSpotMojo extends AbstractMojo {
     private Integer maxTestAmplified;
 
     /**
-     * [optional] fully qualified names of test classes to be amplified. If the value is all, DSpot will amplify the whole test suite. You can also use regex to describe a set of test classes. By default, DSpot selects all the tests (value all). You can use the value diff, to select tests according to a diff between two versions of the same program. Be careful, using --test diff, you must specify both properties folderPath and baseSha.
+     * [optional] fully qualified names of test classes to be amplified. If the value is all, DSpot will amplify the whole test suite. You can also use regex to describe a set of test classes. By default, DSpot selects all the tests (value all).
      */
     @Parameter(defaultValue = "all", property = "test")
     private List<String> test;

dspot/src/main/java/eu/stamp_project/utils/program/ConstantsProperties.java

@@ -96,14 +96,15 @@ public class ConstantsProperties {
 
     public static final InputConfigurationProperty PATH_TO_SECOND_VERSION =
             new InputConfigurationProperty(
-                    "folderPath",
-                    "when using the ChangeDetectorSelector7" +
+                    "pathToSecondVersion",
+                    "when using the ChangeDetectorSelector" +
                             ", you must specify this property. " +
                             "This property should have for value the path to the root of " +
                             "the second version of the project. " +
                             "It is recommended to give an absolute path",
                     "",
-                    "path to second version"
+                    "path to second version",
+                    "folderPath"
             );
 
     public static final InputConfigurationProperty AUTOMATIC_BUILDER_NAME =
@@ -258,7 +259,7 @@ public static void main(String[] args) {
         inputConfigurationProperties.add(PIT_FILTER_CLASSES_TO_KEEP);
         inputConfigurationProperties.add(DESCARTES_VERSION);
         inputConfigurationProperties.add(DESCARTES_MUTATORS);
-        System.out.println("* Required properties" +
+        final String output = "* Required properties" +
                 AmplificationHelper.LINE_SEPARATOR +
                 getRequiredProperties.apply(inputConfigurationProperties)
                         .map(InputConfigurationProperty::toString)
@@ -273,24 +274,28 @@ public static void main(String[] args) {
                         .map(wrapOptionWithQuote)
                         .collect(Collectors.joining(AmplificationHelper.LINE_SEPARATOR)) +
                 AmplificationHelper.LINE_SEPARATOR +
-                "You can find an example of properties file [here](https://github.com/STAMP-project/dspot/blob/master/dspot/src/test/resources/sample/sample.properties)).");
+                "You can find an example of properties file [here](https://github.com/STAMP-project/dspot/blob/master/dspot/src/test/resources/sample/sample.properties)).";
+        System.out.println(output);
     }
 
     private final static Function<String, String> wrapOptionWithQuote = s -> {
         final String[] split = s.split(" ");
+        List<String> wrappedSplit = new ArrayList<>();
         for (int i = 0; i < split.length; i++) {
             if (split[i].startsWith("--")) {
                 if (split[i].endsWith(".")) {
-                    split[i] = "`" + split[i].substring(0, split[i].length() - 1) + "`.";
+                    wrappedSplit.add("`" + split[i].substring(0, split[i].length() - 1) + "`.");
                 } else {
-                    split[i] = "`" + split[i] + "`";
+                    wrappedSplit.add("`" + split[i] + "`");
                     if (i + 1 < split.length) {
-                        split[i+1] = "`" + split[i+1] + "`";
+                        wrappedSplit.add("`" + split[i+1] + "`");
                     }
                 }
+            } else {
+                wrappedSplit.add(split[i]);
             }
         }
-        return String.join(" ", split);
+        return String.join(" ", wrappedSplit);
     };
 
     private final static Function<List<InputConfigurationProperty>, Stream<InputConfigurationProperty>> getRequiredProperties =

dspot/src/main/java/eu/stamp_project/utils/program/InputConfigurationProperty.java

@@ -95,6 +95,6 @@ private String get(Properties properties, String keyToUse) {
      */
     @Override
     public String toString() {
-        return "\t* " + this.name + ": " + this.description + (this.hasDefaultValue() ? "(default: " + this.defaultValue + ")" : "");
+        return "\t* `" + this.name + "`: " + this.description + (this.hasDefaultValue() ? "(default: " + this.defaultValue + ")" : "");
     }
 }

dspot/src/test/resources/multiple-pom/deep-pom-modules.properties

@@ -7,6 +7,4 @@ testSrc=src/test/java/
 outputDirectory=target/trash/
 javaVersion=8
 pitFilterClassesToKeep=HelloWorld
-
-configPath=src/test/resources/multiple-pom/deep-pom-modules.properties
-folderPath=src/test/resources/multiple-pom_1/
+pathToSecondVersion=src/test/resources/multiple-pom_1/

dspot/src/test/resources/multiple-pom_1/deep-pom-modules.properties

@@ -7,6 +7,4 @@ testSrc=src/test/java/
 outputDirectory=target/trash/
 javaVersion=8
 pitFilterClassesToKeep=HelloWorld
-
-configPath=src/test/resources/multiple-pom/deep-pom-modules.properties
-folderPath=src/test/resources/multiple-pom_1/
+pathToSecondVersion=src/test/resources/multiple-pom_1/

dspot/src/test/resources/regression/test-projects_0/test-projects.properties

@@ -10,5 +10,4 @@ javaVersion=8
 pitFilterClassesToKeep=example.*
 #path to the output folder
 outputDirectory=target/trash/
-configPath=src/test/resources/regression/test-projects_0/test-projects.properties
-folderPath=src/test/resources/regression/test-projects_1/
+pathToSecondVersion=src/test/resources/regression/test-projects_1/