Doc: rename filter property Fix STAMP-project#747 (STAMP-project#750)

* doc: rename the property filter used by PIT in pitFilterClassesToKeep * test: rename all the property filter using in test resources * doc: update README and dspot-for-dummies with new name * feat: add an old name field for backward compatibility * refactor: remove deprecated property * doc: update list of properties * style: remove unused imports
jesus-gorronogoitia · Apr 10, 2019 · 618d8f7 · 618d8f7
1 parent 74156da
commit 618d8f7
Show file tree

Hide file tree

Showing 19 changed files with 78 additions and 79 deletions.
diff --git a/README.md b/README.md
@@ -336,14 +336,13 @@ Here is the list of configuration properties of DSpot:
 	* 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 ','.
-	* maven.home: 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/.
-	* maven.pre.goals: 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"
+	* 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
-	* baseSha: when using the command-line option-value  `--test diff`, which select tests to be amplified according a diff, you must specify this property.This property should have for value the commit sha of the base branch, _i.e._ the version of the to project to be merged.
 	* 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#
-	* filter: specify the filter 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, PIT will use the following filter: <groupId>.<artifactId>.* which might not match your packages.
+	* 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)).

diff --git a/docs/dspot-for-dummies.md b/docs/dspot-for-dummies.md
@@ -57,7 +57,7 @@ javaVersion=8
 # (optional) path to the output folder, default to "output_diversify"
 outputDirectory=dspot-out/
 # (optional) filter on the package name for mutation analysis ("example" => "example.*")
-filter=eu.stamp.examples.dhell*
+pitFilterClassesToKeep=eu.stamp.examples.dhell*
 ```
 
 2. Execute DSpot
@@ -160,7 +160,7 @@ javaVersion=8
 # (optional) path to the output folder, default to "output_diversify"
 outputDirectory=dspot-out/
 # (optional) filter on the package name for mutation analysis ("example" => "example.*")
-filter=eu.stamp.examples.dhell*
+pitFilterClassesToKeep=eu.stamp.examples.dhell*
 ```
 
 2. Execute DSpot

diff --git a/dspot-maven/src/main/java/eu/stamp_project/GeneratePropertiesMojo.java b/dspot-maven/src/main/java/eu/stamp_project/GeneratePropertiesMojo.java
@@ -58,7 +58,7 @@ public void execute() throws MojoExecutionException, MojoFailureException {
         this.properties.put(ConstantsProperties.SRC_CODE.getName(), this.project.getCompileSourceRoots().get(0));
         this.properties.put(ConstantsProperties.TEST_SRC_CODE.getName(), this.project.getTestCompileSourceRoots().get(0));
         final File testSrcDirectory = new File(this.project.getCompileSourceRoots().get(0));
-        this.properties.put(ConstantsProperties.FILTER.getName(), buildFilter(testSrcDirectory));
+        this.properties.put(ConstantsProperties.PIT_FILTER_CLASSES_TO_KEEP.getName(), buildFilter(testSrcDirectory));
         this.output();
     }
 

diff --git a/dspot/src/main/java/eu/stamp_project/utils/program/ConstantsProperties.java b/dspot/src/main/java/eu/stamp_project/utils/program/ConstantsProperties.java
@@ -3,7 +3,6 @@
 import eu.stamp_project.utils.AmplificationHelper;
 
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.List;
 import java.util.function.Function;
 import java.util.stream.Collectors;
@@ -107,18 +106,6 @@ public class ConstantsProperties {
                     "path to second version"
             );
 
-    @Deprecated
-    public static final InputConfigurationProperty BASE_SHA =
-            new InputConfigurationProperty(
-                    "baseSha",
-                    "when using the command-line option-value  `--test diff`, " +
-                            "which select tests to be amplified according a diff, " +
-                            "you must specify this property." +
-                            "This property should have for value the commit sha of the base branch, " +
-                            "i.e. the version of the to project to be merged.",
-                    ""
-            );
-
     public static final InputConfigurationProperty AUTOMATIC_BUILDER_NAME =
             new InputConfigurationProperty(
                     "automaticBuilderName",
@@ -138,7 +125,7 @@ public class ConstantsProperties {
 
     public static final InputConfigurationProperty MAVEN_HOME =
             new InputConfigurationProperty(
-                    "maven.home",
+                    "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. " +
@@ -147,19 +134,21 @@ public class ConstantsProperties {
                             "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/.",
                     "",
-                    "maven installation"
+                    "maven installation",
+                    "maven.home"
             );
 
     public static final InputConfigurationProperty MAVEN_PRE_GOALS =
             new InputConfigurationProperty(
-                    "maven.pre.goals",
+                    "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\"",
                     "",
-                    "maven pre goals"
-            );
+                    "maven pre goals",
+                    "maven.pre.goals"
+                    );
 
     public static final InputConfigurationProperty DELTA_ASSERTS_FLOAT =
             new InputConfigurationProperty(
@@ -171,16 +160,17 @@ public class ConstantsProperties {
                     "0.1"
             );
 
-    public static final InputConfigurationProperty FILTER =
+    public static final InputConfigurationProperty PIT_FILTER_CLASSES_TO_KEEP =
             new InputConfigurationProperty(
-                    "filter",
-                    "specify the filter used by PIT. " +
+                    "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, PIT will use the following filter: <groupId>.<artifactId>.* " +
-                            "which might not match your packages.",
-                    ""
+                            "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.",
+                    "",
+                    "",
+                    "filter"
             );
 
     public static final InputConfigurationProperty PIT_VERSION =
@@ -262,32 +252,28 @@ public static void main(String[] args) {
         inputConfigurationProperties.add(MAVEN_HOME);
         inputConfigurationProperties.add(MAVEN_PRE_GOALS);
         inputConfigurationProperties.add(PATH_TO_SECOND_VERSION);
-        inputConfigurationProperties.add(BASE_SHA);
         inputConfigurationProperties.add(AUTOMATIC_BUILDER_NAME);
         inputConfigurationProperties.add(PIT_VERSION);
         inputConfigurationProperties.add(JVM_ARGS);
-        inputConfigurationProperties.add(FILTER);
+        inputConfigurationProperties.add(PIT_FILTER_CLASSES_TO_KEEP);
         inputConfigurationProperties.add(DESCARTES_VERSION);
         inputConfigurationProperties.add(DESCARTES_MUTATORS);
-        System.out.println(new StringBuilder().append("* Required properties")
-                .append(AmplificationHelper.LINE_SEPARATOR)
-                .append(
-                        getRequiredProperties.apply(inputConfigurationProperties)
-                                .map(InputConfigurationProperty::toString)
-                                .collect(Collectors.joining(AmplificationHelper.LINE_SEPARATOR))
-                )
-                .append(AmplificationHelper.LINE_SEPARATOR)
-                .append("* Optional properties")
-                .append(AmplificationHelper.LINE_SEPARATOR)
-                .append(getOptionalProperties.apply(inputConfigurationProperties)
+        System.out.println("* Required properties" +
+                AmplificationHelper.LINE_SEPARATOR +
+                getRequiredProperties.apply(inputConfigurationProperties)
+                        .map(InputConfigurationProperty::toString)
+                        .collect(Collectors.joining(AmplificationHelper.LINE_SEPARATOR)) +
+                AmplificationHelper.LINE_SEPARATOR +
+                "* Optional properties" +
+                AmplificationHelper.LINE_SEPARATOR +
+                getOptionalProperties.apply(inputConfigurationProperties)
                         .map(InputConfigurationProperty::toString)
                         .map(s -> s.replaceAll("i\\.e\\.", "_i.e._"))
                         .map(s -> s.replaceAll("e\\.g\\.", "_e.g._"))
                         .map(wrapOptionWithQuote)
-                        .collect(Collectors.joining(AmplificationHelper.LINE_SEPARATOR)))
-                .append(AmplificationHelper.LINE_SEPARATOR)
-                .append("You can find an example of properties file [here](https://github.com/STAMP-project/dspot/blob/master/dspot/src/test/resources/sample/sample.properties)).")
-                .toString());
+                        .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)).");
     }
 
     private final static Function<String, String> wrapOptionWithQuote = s -> {
@@ -304,7 +290,7 @@ public static void main(String[] args) {
                 }
             }
         }
-        return Arrays.stream(split).collect(Collectors.joining(" "));
+        return String.join(" ", split);
     };
 
     private final static Function<List<InputConfigurationProperty>, Stream<InputConfigurationProperty>> getRequiredProperties =

diff --git a/dspot/src/main/java/eu/stamp_project/utils/program/InputConfiguration.java b/dspot/src/main/java/eu/stamp_project/utils/program/InputConfiguration.java
@@ -203,9 +203,8 @@ private InputConfiguration(Properties properties) {
 
         this.setOutputDirectory(ConstantsProperties.OUTPUT_DIRECTORY.get(properties))
                 .setDelta(ConstantsProperties.DELTA_ASSERTS_FLOAT.get(properties))
-                .setFilter(ConstantsProperties.FILTER.get(properties))
+                .setFilter(ConstantsProperties.PIT_FILTER_CLASSES_TO_KEEP.get(properties))
                 .setDescartesVersion(ConstantsProperties.DESCARTES_VERSION.get(properties))
-                .setBaseSha(ConstantsProperties.BASE_SHA.get(properties))
                 .setExcludedClasses(ConstantsProperties.EXCLUDED_CLASSES.get(properties))
                 .setPreGoalsTestExecution(ConstantsProperties.MAVEN_PRE_GOALS.get(properties))
                 //.setTimeoutPit(ConstantsProperties.TIMEOUT_PIT.get(properties))
@@ -582,17 +581,6 @@ public InputConfiguration setAbsolutePathToSecondVersionProjectRoot(String absol
         return this;
     }
 
-    private String baseSha;
-
-    public String getBaseSha() {
-        return baseSha;
-    }
-
-    public InputConfiguration setBaseSha(String baseSha) {
-        this.baseSha = baseSha;
-        return this;
-    }
-
     /*
         Amplification and Pit properties
      */

diff --git a/dspot/src/main/java/eu/stamp_project/utils/program/InputConfigurationProperty.java b/dspot/src/main/java/eu/stamp_project/utils/program/InputConfigurationProperty.java
@@ -1,5 +1,8 @@
 package eu.stamp_project.utils.program;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 import java.util.Properties;
 
 /**
@@ -9,16 +12,20 @@
  */
 public class InputConfigurationProperty {
 
+    private static final Logger LOGGER = LoggerFactory.getLogger(InputConfigurationProperty.class);
+
     private final String name;
     private final String description;
     private final String defaultValue;
     private final String naturalLanguageDesignation;
+    private final String oldName;
 
     public InputConfigurationProperty(String name, String description, String defaultValue) {
         this.name = name;
         this.description = description;
         this.defaultValue = defaultValue;
         this.naturalLanguageDesignation = "";
+        this.oldName = "";
     }
 
     public InputConfigurationProperty(String name,
@@ -29,6 +36,15 @@ public InputConfigurationProperty(String name,
         this.description = description;
         this.defaultValue = defaultValue;
         this.naturalLanguageDesignation = naturalLanguageDesignation;
+        this.oldName = "";
+    }
+
+    public InputConfigurationProperty(String name, String description, String defaultValue, String naturalLanguageDesignation, String oldName) {
+        this.name = name;
+        this.description = description;
+        this.defaultValue = defaultValue;
+        this.naturalLanguageDesignation = naturalLanguageDesignation;
+        this.oldName = oldName;
     }
 
     public String getName() {
@@ -56,16 +72,26 @@ private boolean hasDefaultValue() {
     }
 
     public String get(Properties properties) {
+        if (properties.containsKey(this.oldName)) {
+            LOGGER.warn("You used the old name ({}) for {}.", this.oldName, this.getName());
+            LOGGER.warn("The old name will be removed in future versions.");
+            LOGGER.warn("Please, update your properties file.");
+            return this.get(properties, this.oldName);
+        } else {
+            return this.get(properties, this.getName());
+        }
+    }
+
+    private String get(Properties properties, String keyToUse) {
         if (!isRequired()) {
-            return properties.getProperty(this.getName(), this.getDefaultValue());
+            return properties.getProperty(keyToUse, this.getDefaultValue());
         } else {
-            return properties.getProperty(this.getName());
+            return properties.getProperty(keyToUse);
         }
     }
 
     /**
-     * This method return in markdown format a description of the Property
-     * @return
+     * @return This method return in markdown format a description of the Property
      */
     @Override
     public String toString() {

diff --git a/dspot/src/test/resources/catalog.properties b/dspot/src/test/resources/catalog.properties
@@ -9,6 +9,6 @@ javaVersion=8
 # (Optional) Path to the output folder, default to "output_diversify"
 outputDirectory=result/all
 # (Optional) Filter on the package name containing tests to be amplified ("example" => "example.*")
-filter=org.ow2.proactive.catalog.*
+pitFilterClassesToKeep=org.ow2.proactive.catalog.*
 classes=build/classes/main/
 testClasses=build/classes/test/**
diff --git a/dspot/src/test/resources/descartes/descartes.properties b/dspot/src/test/resources/descartes/descartes.properties
@@ -2,5 +2,5 @@ project=src/test/resources/descartes
 src=src/main/java/
 testSrc=src/test/java
 javaVersion=8
-filter=eu.stamp_project.stamp.mutationtest.test.*
+pitFilterClassesToKeep=eu.stamp_project.stamp.mutationtest.test.*
 outputDirectory=target/trash/
diff --git a/dspot/src/test/resources/easymock/mock.properties b/dspot/src/test/resources/easymock/mock.properties
@@ -7,6 +7,6 @@ testSrc=src/test/java
 #java version used
 javaVersion=8
 #filter used to amplify specific test cases
-filter=org.baeldung.*
+pitFilterClassesToKeep=org.baeldung.*
 #path to the output folder
 outputDirectory=target/trash/
diff --git a/dspot/src/test/resources/jmockit/mock.properties b/dspot/src/test/resources/jmockit/mock.properties
@@ -7,6 +7,6 @@ testSrc=src/test/java
 #java version used
 javaVersion=8
 #filter used to amplify specific test cases
-filter=org.baeldung.*
+pitFilterClassesToKeep=org.baeldung.*
 #path to the output folder
 outputDirectory=target/trash/
diff --git a/dspot/src/test/resources/mockito/mockito.properties b/dspot/src/test/resources/mockito/mockito.properties
@@ -7,6 +7,6 @@ testSrc=src/test/java
 #java version used
 javaVersion=8
 #filter used to amplify specific test cases
-filter=info.sanaulla.*
+pitFilterClassesToKeep=info.sanaulla.*
 #path to the output folder
 outputDirectory=target/trash/
diff --git a/dspot/src/test/resources/mockito2/mock.properties b/dspot/src/test/resources/mockito2/mock.properties
@@ -7,6 +7,6 @@ testSrc=src/test/java
 #java version used
 javaVersion=8
 #filter used to amplify specific test cases
-filter=org.baeldung.*
+pitFilterClassesToKeep=org.baeldung.*
 #path to the output folder
 outputDirectory=target/trash/
diff --git a/dspot/src/test/resources/multiple-pom/deep-pom-modules.properties b/dspot/src/test/resources/multiple-pom/deep-pom-modules.properties
@@ -6,7 +6,7 @@ src=src/main/java/
 testSrc=src/test/java/
 outputDirectory=target/trash/
 javaVersion=8
-filter=HelloWorld
+pitFilterClassesToKeep=HelloWorld
 
 configPath=src/test/resources/multiple-pom/deep-pom-modules.properties
 folderPath=src/test/resources/multiple-pom_1/
diff --git a/dspot/src/test/resources/multiple-pom_1/deep-pom-modules.properties b/dspot/src/test/resources/multiple-pom_1/deep-pom-modules.properties
@@ -6,7 +6,7 @@ src=src/main/java/
 testSrc=src/test/java/
 outputDirectory=target/trash/
 javaVersion=8
-filter=HelloWorld
+pitFilterClassesToKeep=HelloWorld
 
 configPath=src/test/resources/multiple-pom/deep-pom-modules.properties
 folderPath=src/test/resources/multiple-pom_1/