#15 Improving unit test coverage

butterfly-extensions-api/src/main/java/com/paypal/butterfly/extensions/api/DoubleCondition.java

@@ -14,18 +14,28 @@
  * for example). For conditions
  * based on evaluating a single file see {@link SingleCondition}.
  * For conditions based on multiple files see {@link MultipleConditions}
+ * <br>
+ * <strong>Important:</strong> it returns true if both files don't exist,
+ * and it returns false if only one of them exists.
  *
+ * @author facarvalho
  * @see SingleCondition
  * @see MultipleConditions
- *
- * @author facarvalho
  */
 public abstract class DoubleCondition<T extends DoubleCondition> extends UtilityCondition<T> {
 
     // The name of the transformation context attribute
     // that refers to the file to be compared against the baseline file
     private String attribute;
 
+    // TODO
+    // Rename attribute to compareAttribute
+
+    // TODO
+    // Add a new instance variable called compareRelative, to be used as an alternative to compareAttribute,
+    // pointing directly to the comparison file, relative to the transformed application folder,
+    // and without the need for a transformation context attribute.
+
     /**
      * Condition to determine if a transformation utility
      * should be executed or not. Every
@@ -34,23 +44,22 @@ public abstract class DoubleCondition<T extends DoubleCondition> extends Utility
      * is based on two files (when comparing if two XML files are equal
      * for example)
      */
-     public DoubleCondition() {
+    public DoubleCondition() {
     }
 
     /**
-     * Set the name of the transformation context attribute
-     * that refers to the file to be compared against the
-     * baseline file, which is set by regular {@link com.paypal.butterfly.extensions.api.TransformationUtility}
-     * methods, like {@link #relative(String)} or {@link #absolute(String)}
+     * Condition to determine if a transformation utility
+     * should be executed or not. Every
+     * DoubleUtilityCondition subclass result type must always
+     * be boolean. The criteria to this type of condition
+     * is based on two files (when comparing if two XML files are equal
+     * for example)
      *
      * @param attribute the name of the transformation context attribute
      *                  that refers to the file to be compared against the baseline file
-     * @return this utility condition instance
      */
-    public T setAttribute(String attribute) {
-        checkForBlankString("attribute", attribute);
-        this.attribute = attribute;
-        return (T) this;
+    public DoubleCondition(String attribute) {
+        setAttribute(attribute);
     }
 
     /**
@@ -66,13 +75,34 @@ public String getAttribute() {
         return attribute;
     }
 
+    /**
+     * Set the name of the transformation context attribute
+     * that refers to the file to be compared against the
+     * baseline file, which is set by regular {@link com.paypal.butterfly.extensions.api.TransformationUtility}
+     * methods, like {@link #relative(String)} or {@link #absolute(String)}
+     *
+     * @param attribute the name of the transformation context attribute
+     *                  that refers to the file to be compared against the baseline file
+     * @return this utility condition instance
+     */
+    public T setAttribute(String attribute) {
+        checkForBlankString("attribute", attribute);
+        this.attribute = attribute;
+        return (T) this;
+    }
+
     @Override
-    protected ExecutionResult execution(File transformedAppFolder, TransformationContext transformationContext) {
+    protected TUExecutionResult execution(File transformedAppFolder, TransformationContext transformationContext) {
         try {
             File baselineFile = getAbsoluteFile(transformedAppFolder, transformationContext);
             File comparisonFile = getComparisonFile(transformationContext);
 
-            boolean result = compare(baselineFile, comparisonFile);
+            boolean result = false;
+            if (baselineFile.exists() && comparisonFile.exists()) {
+                result = compare(baselineFile, comparisonFile);
+            } else if (!baselineFile.exists() && !comparisonFile.exists()) {
+                result = true;
+            }
 
             return TUExecutionResult.value(this, result);
         } catch (TransformationUtilityException e) {
@@ -84,7 +114,7 @@ protected ExecutionResult execution(File transformedAppFolder, TransformationCon
      * Returns true only if the compared files meet the comparison
      * criteria established and implemented by the subclass
      *
-     * @param baselineFile the baseline file used for comparison
+     * @param baselineFile   the baseline file used for comparison
      * @param comparisonFile the file to be compared against the baseline file
      * @return this utility condition instance
      */

butterfly-utilities/src/main/java/com/paypal/butterfly/utilities/conditions/CompareFiles.java

@@ -1,14 +1,17 @@
 package com.paypal.butterfly.utilities.conditions;
 
 import com.paypal.butterfly.extensions.api.DoubleCondition;
+import com.paypal.butterfly.extensions.api.TUExecutionResult;
+import com.paypal.butterfly.extensions.api.TransformationContext;
 import com.paypal.butterfly.extensions.api.exception.TransformationUtilityException;
 import org.apache.commons.io.FileUtils;
 
 import java.io.File;
 import java.io.IOException;
 
 /**
- * Compares two files and returns true only if their contents are identical.
+ * Compares two files and returns true if the content of the files are equal,
+ * or if they both don't exist. Returns false otherwise.
  * <br>
  * See {@link com.paypal.butterfly.extensions.api.DoubleCondition} to find out how to set the baseline and the comparison files
  *
@@ -18,6 +21,28 @@ public class CompareFiles extends DoubleCondition<CompareFiles> {
 
     private static final String DESCRIPTION = "Compare file %s to another one, return true only if their contents are equal";
 
+    /**
+     * Compares two files and returns true if the content of the files are equal,
+     * or if they both don't exist. Returns false otherwise.
+     * <br>
+     * See {@link com.paypal.butterfly.extensions.api.DoubleCondition} to find out how to set the baseline and the comparison files
+     */
+    public CompareFiles(){
+    }
+
+    /**
+     * Compares two files and returns true if the content of the files are equal,
+     * or if they both don't exist. Returns false otherwise.
+     * <br>
+     * See {@link com.paypal.butterfly.extensions.api.DoubleCondition} to find out how to set the baseline and the comparison files
+     *
+     * @param attribute the name of the transformation context attribute
+     *                  that refers to the file to be compared against the baseline file
+     */
+    public CompareFiles(String attribute){
+        super(attribute);
+    }
+
     @Override
     protected boolean compare(File baselineFile, File comparisonFile) {
         try {
@@ -32,4 +57,9 @@ public String getDescription() {
         return String.format(DESCRIPTION, getRelativePath());
     }
 
+    @Override
+    protected TUExecutionResult execution(File transformedAppFolder, TransformationContext transformationContext) {
+        return super.execution(transformedAppFolder, transformationContext);
+    }
+
 }

butterfly-utilities/src/main/java/com/paypal/butterfly/utilities/conditions/CompareXMLFiles.java

@@ -1,6 +1,8 @@
 package com.paypal.butterfly.utilities.conditions;
 
 import com.paypal.butterfly.extensions.api.DoubleCondition;
+import com.paypal.butterfly.extensions.api.TUExecutionResult;
+import com.paypal.butterfly.extensions.api.TransformationContext;
 import com.paypal.butterfly.extensions.api.exception.TransformationUtilityException;
 import org.custommonkey.xmlunit.XMLUnit;
 import org.w3c.dom.Document;
@@ -13,9 +15,10 @@
 import java.io.IOException;
 
 /**
- * Compares two XML files and returns true only
-if their contents are equal. Attribute orders, comments and white
- * spaces are ignored during the comparison.
+ * Compares two XML files and returns true if their contents are equal,
+ * or if both files don't exist. Returns false otherwise.
+ * Attribute orders, comments and white spaces are ignored during the comparison.
+ * It results in error if any of the two files is not a well formed XML file.
  * <br>
  * See {@link DoubleCondition}
  * to find out how to set the baseline and the comparison files
@@ -26,6 +29,34 @@ public class CompareXMLFiles extends DoubleCondition<CompareXMLFiles> {
 
     private static final String DESCRIPTION = "Compare XML file %s to another one, return true only if their contents are equal";
 
+    /**
+     * Compares two XML files and returns true if their contents are equal,
+     * or if both files don't exist. Returns false otherwise.
+     * Attribute orders, comments and white spaces are ignored during the comparison.
+     * It results in error if any of the two files is not a well formed XML file.
+     * <br>
+     * See {@link DoubleCondition}
+     * to find out how to set the baseline and the comparison files
+     */
+    public CompareXMLFiles() {
+    }
+
+    /**
+     * Compares two XML files and returns true if their contents are equal,
+     * or if both files don't exist. Returns false otherwise.
+     * Attribute orders, comments and white spaces are ignored during the comparison.
+     * It results in error if any of the two files is not a well formed XML file.
+     * <br>
+     * See {@link DoubleCondition}
+     * to find out how to set the baseline and the comparison files
+     *
+     * @param attribute the name of the transformation context attribute
+     *                  that refers to the file to be compared against the baseline file
+     */
+    public CompareXMLFiles(String attribute) {
+        setAttribute(attribute);
+    }
+
     @Override
     protected boolean compare(File baselineFile, File comparisonFile) {
         try {
@@ -49,10 +80,15 @@ protected boolean compare(File baselineFile, File comparisonFile) {
 
             return XMLUnit.compareXML(baselineXml, comparisonXml).similar();
         } catch (SAXException | IOException | ParserConfigurationException e) {
-            throw new TransformationUtilityException("An exception has happened when comparing the two XML files", e);
+            throw new TransformationUtilityException("An exception happened when comparing the two XML files", e);
         }
     }
 
+    @Override
+    protected TUExecutionResult execution(File transformedAppFolder, TransformationContext transformationContext) {
+        return super.execution(transformedAppFolder, transformationContext);
+    }
+
     @Override
     public String getDescription() {
         return String.format(DESCRIPTION, getRelativePath());

butterfly-utilities/src/main/java/com/paypal/butterfly/utilities/file/FindFile.java

@@ -85,7 +85,7 @@ protected TUExecutionResult execution(File transformedAppFolder, TransformationC
         File searchRootFolder = getAbsoluteFile(transformedAppFolder, transformationContext);
 
         if (!searchRootFolder.exists()) {
-            String details = String.format("No file named '%s' has been found by %s", fileName, getName());
+            String details = String.format("The specified search root folder does not exist");
             if (failIfNotFound) {
                 TransformationUtilityException e = new TransformationUtilityException(details);
                 return TUExecutionResult.error(this, e);

butterfly-utilities/src/main/java/com/paypal/butterfly/utilities/file/FindFiles.java

@@ -7,6 +7,7 @@
 import org.apache.commons.io.filefilter.AbstractFileFilter;
 import org.apache.commons.io.filefilter.IOFileFilter;
 import org.apache.commons.io.filefilter.TrueFileFilter;
+import org.apache.commons.lang3.StringUtils;
 
 import java.io.File;
 import java.util.ArrayList;
@@ -34,7 +35,7 @@
  */
 public class FindFiles extends TransformationUtility<FindFiles> {
 
-    private static final String DESCRIPTION = "Find files whose name and/or path match regular expression and are under folder %s%s";
+    private static final String DESCRIPTION = "Find files whose name and/or path match regular expression and are under %s%s";
 
     private String nameRegex;
     private String pathRegex;
@@ -45,12 +46,8 @@ public FindFiles() {
 
     /**
      * Utility to find files based on a regular expression
-     * against the file name and/or the file path. The search might be
-     * recursive (including sub-folders) or not. If a file path regular
-     * expression is set, then the search will be automatically and
-     * necessarily recursive.
-     * If no file path regular expression is set, then the search
-     * is not recursive by default, but it may be set to as well.
+     * against the file name. The search might be
+     * recursive (including sub-folders) or not.
      * <br>
      * The root directory from where the search should take place
      * can be defined by {@link #relative(String)},
@@ -69,12 +66,22 @@ public FindFiles(String nameRegex, boolean recursive) {
 
     /**
      * Utility to find files based on a regular expression
-     * against the file name and/or the file path. The search might be
-     * recursive (including sub-folders) or not. If a file path regular
+     * against the file name and the file path. Because a file path regular
      * expression is set, then the search will be automatically and
      * necessarily recursive.
-     * If no file path regular expression is set, then the search
-     * is not recursive by default, but it may be set to as well.
+     * <br>
+     * <strong>Important notes:</strong>
+     * <ul>
+     *      <li>Use forward slash as file separator. If the OS
+     *      used during transformation execution uses another character
+     *      as file separator, that will be automatically converted
+     *      by this utility</li>
+     *      <li>Setting this to a non null value automatically sets
+     *      recursive property to true</li>
+     *      <li>This regular expression will be evaluated against
+     *      the file path <strong>starting from the search root
+     *      directory</strong></li>
+     * </ul>
      * <br>
      * The root directory from where the search should take place
      * can be defined by {@link #relative(String)},
@@ -182,7 +189,11 @@ public boolean isRecursive() {
 
     @Override
     public String getDescription() {
-        return String.format(DESCRIPTION, getRelativePath(), (recursive ? " and sub-folders" : " only (not including sub-folders)"));
+        String folder = getRelativePath();
+        if (StringUtils.isBlank(folder) || ".".equals(folder)) {
+            folder = "the root folder";
+        }
+        return String.format(DESCRIPTION, folder, (recursive ? " and sub-folders" : " only (not including sub-folders)"));
     }
 
     @Override

butterfly-utilities/src/main/java/com/paypal/butterfly/utilities/file/LoadFile.java

@@ -1,6 +1,5 @@
 package com.paypal.butterfly.utilities.file;
 
-import com.paypal.butterfly.extensions.api.ExecutionResult;
 import com.paypal.butterfly.extensions.api.TUExecutionResult;
 import com.paypal.butterfly.extensions.api.TransformationContext;
 import com.paypal.butterfly.extensions.api.TransformationUtility;
@@ -16,6 +15,7 @@
  * Loads a resource from the classpath, writes it to a temporary file,
  * and then returns a {@link File} reference to it, which is saved in the transformation
  * context. The file is written to a temporary folder to be defined by the OS.
+ * If no resource file is found, an error is returned.
  *
  * @author facarvalho
  */
@@ -25,9 +25,27 @@ public class LoadFile extends TransformationUtility<LoadFile> {
 
     private String resource;
 
+    /**
+     * Loads a resource from the classpath, writes it to a temporary file,
+     * and then returns a {@link File} reference to it, which is saved in the transformation
+     * context. The file is written to a temporary folder to be defined by the OS.
+     * If no resource file is found, an error is returned.
+     */
     public LoadFile() {
     }
 
+    /**
+     * Loads a resource from the classpath, writes it to a temporary file,
+     * and then returns a {@link File} reference to it, which is saved in the transformation
+     * context. The file is written to a temporary folder to be defined by the OS.
+     * If no resource file is found, an error is returned.
+     *
+     * @param resource the name of the resource in the classpath
+     */
+    public LoadFile(String resource) {
+        setResource(resource);
+    }
+
     /**
      * Sets the name of the resource in the classpath. The syntax
      * here is the same as the one used in {@link ClassLoader#getResource(String)}
@@ -57,7 +75,7 @@ public String getDescription() {
 
     @SuppressFBWarnings("NP_ALWAYS_NULL_EXCEPTION")
     @Override
-    protected ExecutionResult execution(File transformedAppFolder, TransformationContext transformationContext) {
+    protected TUExecutionResult execution(File transformedAppFolder, TransformationContext transformationContext) {
         TUExecutionResult result = null;
         InputStream inputStream = null;
         IOException ioException = null;