add new feature and config param "saveCurrentImageIfFailure"

Author: Neubert, Sebastian

module/VisualCeption.php

@@ -19,6 +19,7 @@ class VisualCeption extends \Codeception\Module
     private $referenceImageDir;
 
     private $maximumDeviation = 0;
+    private $saveCurrentImageIfFailure = false;
 
     private $webDriver = null;
     private $webDriverModule = null;
@@ -71,6 +72,11 @@ public function seeVisualChanges ($identifier, $elementID = null, $excludeElemen
             if ($deviationResult["deviation"] <= $this->maximumDeviation) {
                 $compareScreenshotPath = $this->getDeviationScreenshotPath($identifier);
                 $deviationResult["deviationImage"]->writeImage($compareScreenshotPath);
+
+                if ($this->saveCurrentImageIfFailure === true) {
+                    $saveCurrentImagePath = $this->getDeviationScreenshotPath($identifier, 'current');
+                    $deviationResult['currentImage']->writeImage($saveCurrentImagePath);
+                }
                 $this->assertTrue(false, "The deviation of the taken screenshot is too low (" . $deviationResult["deviation"] . "%).\nSee $compareScreenshotPath for a deviation screenshot.");
             }
         }
@@ -94,6 +100,11 @@ public function dontSeeVisualChanges ($identifier, $elementID = null, $excludeEl
             if ($deviationResult["deviation"] > $this->maximumDeviation) {
                 $compareScreenshotPath = $this->getDeviationScreenshotPath($identifier);
                 $deviationResult["deviationImage"]->writeImage($compareScreenshotPath);
+
+                if ($this->saveCurrentImageIfFailure === true) {
+                    $saveCurrentImagePath = $this->getDeviationScreenshotPath($identifier, 'current.');
+                    $deviationResult['currentImage']->writeImage($saveCurrentImagePath);
+                }
                 $this->assertTrue(false, "The deviation of the taken screenshot is too high (" . $deviationResult["deviation"] . "%).\nSee $compareScreenshotPath for a deviation screenshot.");
             }
         }
@@ -148,7 +159,12 @@ private function getDeviation ($identifier, $elementID, array $excludeElements =
 
         $deviation = round($compareResult[1] * 100, 2);
         $this->debug("The deviation between the images is ". $deviation . " percent");
-        return array ("deviation" => $deviation, "deviationImage" => $compareResult[0]);
+
+        return array (
+            "deviation" => $deviation,
+            "deviationImage" => $compareResult[0],
+            "currentImage" => $compareResult['currentImage'],
+        );
     }
 
     /**
@@ -164,6 +180,10 @@ private function init ()
             $this->maximumDeviation = $this->config["maximumDeviation"];
         }
 
+        if (array_key_exists('saveCurrentImageIfFailure', $this->config)) {
+            $this->saveCurrentImageIfFailure = (boolean) $this->config["saveCurrentImageIfFailure"];
+        }
+
         if (array_key_exists('referenceImageDir', $this->config)) {
             $this->referenceImageDir = $this->config["referenceImageDir"];
         } else {
@@ -313,12 +333,14 @@ private function resetHideElementsForScreenshot(array $excludeElements)
      * @param $identifier identifies your test object
      * @return string Path of the deviation image
      */
-    private function getDeviationScreenshotPath ($identifier)
+    private function getDeviationScreenshotPath ($identifier, $alternativePrefix = '')
     {
         $debugDir = \Codeception\Configuration::logDir() . 'debug/';
-        return $debugDir . 'compare.' . $this->getScreenshotName($identifier);
+        $prefix = ( $alternativePrefix === '') ? 'compare.' : $alternativePrefix;
+        return $debugDir . $prefix . $this->getScreenshotName($identifier);
     }
 
+
     /**
      * Compare two images by its identifiers.
      * If the reference image doesn't exists
@@ -329,13 +351,13 @@ private function getDeviationScreenshotPath ($identifier)
      */
     private function compare ($identifier)
     {
-        $currentImagePath = $this->getScreenshotPath($identifier);
         $expectedImagePath = $this->getExpectedScreenshotPath($identifier);
+        $currentImagePath = $this->getScreenshotPath($identifier);
 
         if (! file_exists($expectedImagePath)) {
             $this->debug("Copying image (from $currentImagePath to $expectedImagePath");
             copy($currentImagePath, $expectedImagePath);
-            return array (null, 0);
+            return array (null, 0, null);
         } else {
             return $this->compareImages($expectedImagePath, $currentImagePath);
         }
@@ -366,8 +388,11 @@ private function compareImages ($image1, $image2)
 
         try {
             $result = $imagick1->compareImages($imagick2, \Imagick::METRIC_MEANSQUAREERROR);
-            $result[0]->setImageFormat("png");
-        } catch (\ImagickException $e) {
+            $result[0]->setImageFormat('png');
+            $result['currentImage'] = clone $imagick2;
+            $result['currentImage']->setImageFormat('png');
+        }
+        catch (\ImagickException $e) {
             $this->debug("IMagickException! could not campare image1 ($image1) and image2 ($image2).\nExceptionMessage: " . $e->getMessage());
             $this->fail($e->getMessage() . ", image1 $image1 and image2 $image2.");
         }

readme.md

@@ -47,10 +47,14 @@ VisualCeption:
     referenceImageDir: /home/codeception/referenceImages/ # Path to the reference folder (optional, standard is 
                                                           # <datadir>/VisualCeption/)
     maximumDeviation: 5                                   # deviation in percent
+    saveCurrentImageIfFailure: true                       # if true, VisualCeption saves the current
+                                                          # image in debug dir (default: false)
 ```
 
 * **referenceImageDir** VisualCeption uses an "old" image for calculating the deviation. These images have to be stored in the system. This is the corresponding directory.
-* **maximumDeviation** When comparing two images the deviation will be calculated. If this deviation is greater than the maximum deviation the test will fail. 
+* **maximumDeviation** When comparing two images the deviation will be calculated. If this deviation is greater than the maximum deviation the test will fail.
+* **saveCurrentImageIfFailure** When the test fails, the current image will be saved too, so it's easier to change the reference image with this one. The image will appear beside the compare image with the prefix "current."
+
 
 ## Usage
 

test/integration/tests/acceptance.suite.yml

@@ -23,4 +23,5 @@ modules:
             capabilities:
                 webStorageEnabled: true
         VisualCeption:
-            maximumDeviation: 0
+            maximumDeviation: 0
+            saveCurrentImageIfFailure: true