Added Exception to test bootstrap

Author: Nils Langner

.travis.yml

@@ -16,8 +16,8 @@ matrix:
 
 before_script:
   - printf "\n" | pecl install imagick
-  - wget http://selenium.googlecode.com/files/selenium-server-standalone-2.35.0.jar
-  - java -jar selenium-server-standalone-2.35.0.jar -port 4444 >/dev/null 2>&1 &
+  - wget http://selenium-release.storage.googleapis.com/2.41/selenium-server-standalone-2.41.0.jar
+  - java -jar selenium-server-standalone-2.41.0.jar -port 4444 >/dev/null 2>&1 &
   - cd test/integration/
   - mkdir tests/_log
   - php codecept${CODECEPT_VERSION}.phar build

module/VisualCeption.php

@@ -1,6 +1,7 @@
 <?php
 
 namespace Codeception\Module;
+use Codeception\Module\ImageDeviationException;
 
 /**
  * Class VisualCeption
@@ -19,6 +20,7 @@ class VisualCeption extends \Codeception\Module
     private $referenceImageDir;
 
     private $maximumDeviation = 0;
+    private $saveCurrentImageIfFailure = false;
 
     private $webDriver = null;
     private $webDriverModule = null;
@@ -76,6 +78,12 @@ public function seeVisualChanges($identifier, $elementID = null, $excludeElement
             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);
+                }
+
                 throw new ImageDeviationException("The deviation of the taken screenshot is too low (" . $deviationResult["deviation"] . "%).\nSee $compareScreenshotPath for a deviation screenshot.",
                     $this->getExpectedScreenshotPath($identifier),
                     $this->getScreenshotPath($identifier),
@@ -102,6 +110,12 @@ public function dontSeeVisualChanges($identifier, $elementID = null, $excludeEle
             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);
+                }
+
                 throw new ImageDeviationException("The deviation of the taken screenshot is too hight (" . $deviationResult["deviation"] . "%).\nSee $compareScreenshotPath for a deviation screenshot.",
                     $this->getExpectedScreenshotPath($identifier),
                     $this->getScreenshotPath($identifier),
@@ -110,22 +124,12 @@ public function dontSeeVisualChanges($identifier, $elementID = null, $excludeEle
         }
     }
 
-    /**
-     * Inject jQuery.js to the actual site
-     */
-    public function wantToUseJQuery()
-    {
-        $jQueryString = file_get_contents(__DIR__ . "/jquery.js");
-        $this->webDriver->executeScript($jQueryString);
-        $this->webDriver->executeScript('jQuery.noConflict();');
-    }
-
     /**
      * Hide an element to set the visibility to hidden
      *
      * @param $elementSelector String of jQuery Element selector, set visibility to hidden
      */
-    public function hideElement($elementSelector)
+    private function hideElement($elementSelector)
     {
         $this->webDriver->executeScript('
             if( jQuery("' . $elementSelector . '").length > 0 ) {
@@ -140,7 +144,7 @@ public function hideElement($elementSelector)
      *
      * @param $elementSelector String of jQuery Element selector, set visibility to visible
      */
-    public function showElement($elementSelector)
+    private function showElement($elementSelector)
     {
         $this->webDriver->executeScript('
             if( jQuery("' . $elementSelector . '").length > 0 ) {
@@ -153,8 +157,8 @@ public function showElement($elementSelector)
     /**
      * Compares the two images and calculate the deviation between expected and actual image
      *
-     * @param $identifier Identifies your test object
-     * @param $elementID DOM ID of the element, which should be screenshotted
+     * @param string $identifier Identifies your test object
+     * @param string $elementID DOM ID of the element, which should be screenshotted
      * @param array $excludeElements Element names, which should not appear in the screenshot
      * @return array Includes the calculation of deviation in percent and the diff-image
      */
@@ -168,8 +172,14 @@ private function getDeviation($identifier, $elementID, array $excludeElements =
         unlink($this->getScreenshotPath($identifier));
 
         $deviation = round($compareResult[1] * 100, 2);
-        $this->debug("The deviation between the images is " . $deviation . " percent");
-        return array("deviation" => $deviation, "deviationImage" => $compareResult[0]);
+
+        $this->debug("The deviation between the images is ". $deviation . " percent");
+
+        return array (
+            "deviation" => $deviation,
+            "deviationImage" => $compareResult[0],
+            "currentImage" => $compareResult['currentImage'],
+        );
     }
 
     /**
@@ -185,6 +195,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 {
@@ -202,7 +216,7 @@ private function init()
      * The method inject the
      * JQuery Framework and uses the "noConflict"-mode to get the width, height and offset params.
      *
-     * @param $elementId DOM ID of the element, which should be screenshotted
+     * @param string $elementId DOM ID of the element, which should be screenshotted
      * @return array coordinates of the element
      */
     private function getCoordinates($elementId)
@@ -341,12 +355,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
@@ -357,13 +373,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, 'currentImage' => null);
         } else {
             return $this->compareImages($expectedImagePath, $currentImagePath);
         }
@@ -394,8 +410,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/codecept1.phar

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

test/integration/codecept2.phar

@@ -0,0 +1,39 @@
+<?php
+
+use Codeception\Module\ImageDeviationException;
+
+class WriteCurrentImageCest
+{
+
+    /**
+     * fail the test. lookup is current image is written
+     */
+    public function writeCurrentImageFile(WebGuy $I, $scenario)
+    {
+        $I->amOnPage("/VisualCeption/seeVisualChanges.php");
+        $I->dontSeeVisualChanges("currentImageIdentifier", "#theblock");
+
+        $I->wait(2);
+
+        // the test has to be called twice for comparison on the travis server
+        // expect failing the test
+
+        $I->amOnPage("/VisualCeption/seeVisualChanges.php");
+        try
+        {
+            $I->dontSeeVisualChanges("currentImageIdentifier", "#theblock");
+        }
+        catch (ImageDeviationException $exception)
+        {
+            $currentImagePath = $exception->getCurrentImage();
+
+            if (is_file( $currentImagePath )) {
+                return true;
+            }
+
+            // @TODO: complete the test, if current.* image is written
+            $scenario->incomplete();
+            throw $exception;
+        }
+    }
+}