jMonkeyEngine#2279 Clean up javadocs and return to requiring absolute…

… equality (now that pipeline runs works again)

jme3-screenshot-tests/src/main/java/org/jmonkeyengine/screenshottests/testframework/App.java

@@ -37,6 +37,7 @@
 import com.jme3.math.ColorRGBA;
 
 /**
+ * The app used for the tests. AppState(s) are used to inject the actual test code.
  * @author Richard Tingle (aka richtea)
  */
 public class App extends SimpleApplication {

jme3-screenshot-tests/src/main/java/org/jmonkeyengine/screenshottests/testframework/ExtentReportExtension.java

@@ -44,6 +44,8 @@
 import java.util.Optional;
 
 /**
+ * This creates the Extent report and manages the test lifecycle
+ *
  * @author Richard Tingle (aka richtea)
  */
 public class ExtentReportExtension implements BeforeAllCallback, AfterAllCallback, TestWatcher, BeforeTestExecutionCallback{
@@ -64,6 +66,10 @@ public void beforeAll(ExtensionContext context) {
 
     @Override
     public void afterAll(ExtensionContext context) {
+        /*
+        * this writes the entire report after each test class. This sucks but I don't think there is
+        * anywhere else I can hook into the lifecycle of the end of all tests to write the report.
+        */
         extent.flush();
     }
 

jme3-screenshot-tests/src/main/java/org/jmonkeyengine/screenshottests/testframework/ScreenshotTest.java

@@ -96,7 +96,7 @@ public void run(){
         AppSettings settings = new AppSettings(true);
         settings.setResolution(resolution.getWidth(), resolution.getHeight());
         settings.setAudioRenderer(null); // Disable audio (for headless)
-        settings.setUseInput(false);
+        settings.setUseInput(false); //while it will run with inputs on it causes non-fatal errors.
 
         String imageFilePrefix = baseImageFileName == null ? calculateImageFilePrefix() : baseImageFileName;
 
@@ -107,8 +107,7 @@ public void run(){
     private String calculateImageFilePrefix(){
         StackTraceElement[] stackTrace = Thread.currentThread().getStackTrace();
 
-        // The element at index 2 is the caller of this method
-        // (0 is getStackTrace, 1 is getCallerInfo, 2 is the caller of getCallerInfo etc)
+        // The element at index 2 is the caller of this method, so at 3 should be the test class
         if (stackTrace.length > 3) {
             StackTraceElement caller = stackTrace[3];
             return caller.getClassName() + "." + caller.getMethodName();

jme3-screenshot-tests/src/main/java/org/jmonkeyengine/screenshottests/testframework/ScreenshotTestBase.java

@@ -44,6 +44,12 @@
 @Tag("integration")
 public abstract class ScreenshotTestBase{
 
+    /**
+     * Initialises a screenshot test. The resulting object should be configured (if neccessary) and then started
+     * by calling {@link ScreenshotTest#run()}.
+     * @param initialStates
+     * @return
+     */
     public ScreenshotTest screenshotTest(AppState... initialStates){
         return new ScreenshotTest(initialStates);
     }

jme3-screenshot-tests/src/main/java/org/jmonkeyengine/screenshottests/testframework/TestDriver.java

@@ -216,7 +216,7 @@ private Integer extractNumber(Path path){
 
                 if(!Files.exists(expectedImage)){
                     try{
-                        Path savedImage = saveGeneratedImageToSavedImages(generatedImage, thisFrameBaseImageFileName);
+                        Path savedImage = saveGeneratedImageToChangedImages(generatedImage, thisFrameBaseImageFileName);
                         attachImage("New image:", thisFrameBaseImageFileName + ".png", savedImage);
                         String message = "Expected image not found, is this a new test? If so collect the new image from the step artefacts";
                         if(failureMessage==null){ //only want the first thing to go wrong as the junit test fail reason
@@ -238,7 +238,7 @@ private Integer extractNumber(Path path){
                     }
                 } else {
                     //save the generated image to the build directory
-                    Path savedImage = saveGeneratedImageToSavedImages(generatedImage, thisFrameBaseImageFileName);
+                    Path savedImage = saveGeneratedImageToChangedImages(generatedImage, thisFrameBaseImageFileName);
 
                     attachImage("Expected", thisFrameBaseImageFileName + "_expected.png", expectedImage);
                     attachImage("Actual", thisFrameBaseImageFileName + "_actual.png", savedImage);
@@ -287,7 +287,11 @@ private static void clearTemporaryFolder(Path temporaryFolder){
         }
     }
 
-    private static Path saveGeneratedImageToSavedImages(Path generatedImage, String imageFileName) throws IOException{
+    /**
+     * Saves the image with the exact file name it needs to go into the resources directory to be a new reference image
+     * if the instigator of the change wants to accept this as the new "correct" state.
+     */
+    private static Path saveGeneratedImageToChangedImages(Path generatedImage, String imageFileName) throws IOException{
         Path savedImage = Paths.get("build/changed-images/" + imageFileName + ".png");
         Files.createDirectories(savedImage.getParent());
         Files.copy(generatedImage, savedImage, StandardCopyOption.REPLACE_EXISTING);
@@ -300,7 +304,7 @@ private static Path saveGeneratedImageToSavedImages(Path generatedImage, String
      * may be committed to the repository it is important to keep them as small as possible and worth the extra CPU time
      * to do so
      */
-    public static void aggressivelyCompressImage(Path path) throws IOException {
+    private static void aggressivelyCompressImage(Path path) throws IOException {
         // Load your image
         BufferedImage image = ImageIO.read(path.toFile());
 
@@ -322,18 +326,28 @@ public static void aggressivelyCompressImage(Path path) throws IOException {
         writer.dispose();
     }
 
-    public static void attachImage(String title, String fileName, Path originalImage) throws IOException{
+    /**
+     * Attaches the image to the report. A copy of the image is made in the report directory
+     */
+    private static void attachImage(String title, String fileName, Path originalImage) throws IOException{
         ExtentTest test = ExtentReportExtension.getCurrentTest();
         Files.copy(originalImage.toAbsolutePath(), Paths.get("build/reports/" + fileName), StandardCopyOption.REPLACE_EXISTING);
         test.addScreenCaptureFromPath(fileName, title);
     }
 
-    public static void attachImage(String title, String fileName, BufferedImage originalImage) throws IOException{
+    /**
+     * Attaches the image to the report. The image is written to the report directory
+     */
+    private static void attachImage(String title, String fileName, BufferedImage originalImage) throws IOException{
         ExtentTest test = ExtentReportExtension.getCurrentTest();
         ImageIO.write(originalImage, "png", Paths.get("build/reports/" + fileName).toFile());
         test.addScreenCaptureFromPath(fileName, title);
     }
 
+    /**
+     * Tests that the images are the same. If they are not the same it will return false (which may fail the test
+     * depending on the test type). Different sizes are so fatal that they will immediately fail the test.
+     */
     private static boolean imagesAreTheSame(BufferedImage img1, BufferedImage img2) {
         if (img1.getWidth() != img2.getWidth() || img1.getHeight() != img2.getHeight()) {
             ExtentReportExtension.getCurrentTest().createNode("Image 1 size : " + img1.getWidth() + "x" + img1.getHeight());
@@ -343,14 +357,18 @@ private static boolean imagesAreTheSame(BufferedImage img1, BufferedImage img2)
 
         for (int y = 0; y < img1.getHeight(); y++) {
             for (int x = 0; x < img1.getWidth(); x++) {
-                if (!pixelsApproximatelyEqual(img1.getRGB(x, y),img2.getRGB(x, y))) {
+                if (img1.getRGB(x, y)  != img2.getRGB(x, y)){
                     return false;
                 }
             }
         }
         return true;
     }
 
+    /**
+     * Creates an image that highlights the differences between the two images. The reference image is shown
+     * dully in grey with blue, yellow, orange and red showing where pixels are different.
+     */
     private static BufferedImage createComparisonImage(BufferedImage img1, BufferedImage img2) {
         BufferedImage comparisonImage = new BufferedImage(img1.getWidth(), img1.getHeight(), BufferedImage.TYPE_INT_ARGB);
 
@@ -401,16 +419,6 @@ public static int getWashedOutPixel(BufferedImage img, int x, int y, float alpha
         return (a << 24) | (r << 16) | (g << 8) | b;
     }
 
-    private static boolean pixelsApproximatelyEqual(int pixel1, int pixel2){
-        if(pixel1 == pixel2){
-            return true;
-        }
-
-        int pixelDifference = getMaximumComponentDifference(pixel1, pixel2);
-
-        return pixelDifference <= PixelSamenessDegree.SAME.getMaximumAllowedDifference();
-    }
-
     private static PixelSamenessDegree categorisePixelDifference(int pixel1, int pixel2){
         if(pixel1 == pixel2){
             return PixelSamenessDegree.SAME;

jme3-screenshot-tests/src/main/java/org/jmonkeyengine/screenshottests/testframework/TestResolution.java

@@ -32,7 +32,7 @@
 package org.jmonkeyengine.screenshottests.testframework;
 
 /**
- * The size the test should be run at. Try to keep it small to reduce teh file size of the screenshots saved into the
+ * The size the test should be run at. Try to keep it small to reduce the file size of the screenshots saved into the
  * repository.
  *
  * @author Richard Tingle (aka richtea)