[Visual Testing] Image comparison functions (#88) +semver: feature

* prepare ImageExtensions and ScreenshotExtensions to be used for visualization feature
* add ImageComparator and VisualizationConfiguration

Author: mialeska

Aquality.Selenium.Core/src/Aquality.Selenium.Core/Applications/Startup.cs

@@ -4,6 +4,7 @@
 using Aquality.Selenium.Core.Localization;
 using Aquality.Selenium.Core.Logging;
 using Aquality.Selenium.Core.Utilities;
+using Aquality.Selenium.Core.Visualization;
 using Aquality.Selenium.Core.Waitings;
 using Microsoft.Extensions.DependencyInjection;
 using System;
@@ -36,6 +37,8 @@ public virtual IServiceCollection ConfigureServices(IServiceCollection services,
             services.AddSingleton<ILoggerConfiguration, LoggerConfiguration>();
             services.AddSingleton<ITimeoutConfiguration, TimeoutConfiguration>();
             services.AddSingleton<IRetryConfiguration, RetryConfiguration>();
+            services.AddSingleton<IVisualizationConfiguration, VisualizationConfiguration>();
+            services.AddSingleton<IImageComparator, ImageComparator>();
             services.AddSingleton<ILocalizationManager, LocalizationManager>();
             services.AddSingleton<ILocalizedLogger, LocalizedLogger>();
             services.AddSingleton<IActionRetrier, ActionRetrier>();

Aquality.Selenium.Core/src/Aquality.Selenium.Core/Aquality.Selenium.Core.csproj

@@ -47,6 +47,7 @@
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="5.0.0" />
     <PackageReference Include="NLog" Version="4.7.10" />
     <PackageReference Include="Selenium.Support" Version="3.141.0" />
-    <PackageReference Include="Selenium.WebDriver" Version="3.141.0" />    
+    <PackageReference Include="Selenium.WebDriver" Version="3.141.0" />
+    <PackageReference Include="System.Drawing.Common" Version="5.0.2" />    
   </ItemGroup>
 </Project>

Aquality.Selenium.Core/src/Aquality.Selenium.Core/Aquality.Selenium.Core.xml

@@ -0,0 +1,23 @@
+namespace Aquality.Selenium.Core.Configurations
+{
+    /// <summary>
+    /// Represents visualization configuration, used for image comparison.
+    /// </summary>
+    public interface IVisualizationConfiguration
+    {
+        /// <summary>
+        /// Default threshold used for image comparison.
+        /// </summary>
+        float DefaultThreshold { get; }
+
+        /// <summary>
+        /// Width of the image resized for comparison.
+        /// </summary>
+        int ComparisonWidth { get; }
+
+        /// <summary>
+        /// Height of the image resized for comparison.
+        /// </summary>
+        int ComparisonHeight { get; }
+    }
+}

Aquality.Selenium.Core/src/Aquality.Selenium.Core/Configurations/IVisualizationConfiguration.cs

@@ -0,0 +1,28 @@
+using Aquality.Selenium.Core.Utilities;
+
+namespace Aquality.Selenium.Core.Configurations
+{
+    /// <summary>
+    /// Represents visualization configuration, used for image comparison.
+    /// Uses <see cref="ISettingsFile"/> as source for configuration values.
+    /// </summary>
+    public class VisualizationConfiguration : IVisualizationConfiguration
+    {
+        private readonly ISettingsFile settingsFile;
+
+        /// <summary>
+        /// Instantiates class using <see cref="ISettingsFile"/> with visualization settings.
+        /// </summary>
+        /// <param name="settingsFile">Settings file.</param>
+        public VisualizationConfiguration(ISettingsFile settingsFile)
+        {
+            this.settingsFile = settingsFile;
+        }
+
+        public float DefaultThreshold => settingsFile.GetValueOrDefault(".visualization.defaultThreshold", 0.012f);
+
+        public int ComparisonWidth => settingsFile.GetValueOrDefault(".visualization.comparisonWidth", 16);
+
+        public int ComparisonHeight => settingsFile.GetValueOrDefault(".visualization.comparisonHeight", 16);
+    }
+}

Aquality.Selenium.Core/src/Aquality.Selenium.Core/Configurations/VisualizationConfiguration.cs

@@ -15,5 +15,10 @@
   },
   "elementCache": {
     "isEnabled": false
+  },
+  "visualization": {
+    "defaultThreshold": 0.012,
+    "comparisonWidth": 16,
+    "comparisonHeight": 16
   }
 }

Aquality.Selenium.Core/src/Aquality.Selenium.Core/Resources/settings.json

@@ -0,0 +1,22 @@
+using Aquality.Selenium.Core.Configurations;
+using System.Drawing;
+
+namespace Aquality.Selenium.Core.Visualization
+{
+    /// <summary>
+    /// Compares images with defined threshold.
+    /// Uses resizing and gray-scaling to simplify comparison.
+    /// Default implementation uses parameters from <see cref="IVisualizationConfiguration"/>.
+    /// </summary>
+    public interface IImageComparator
+    {
+        /// <summary>
+        /// Gets the difference between two images as a percentage
+        /// </summary>
+        /// <param name="thisOne">The first image</param>
+        /// <param name="theOtherOne">The image to compare with</param>
+        /// <param name="threshold">How big a difference will be ignored as a percentage - value between 0 and 1. </param>
+        /// <returns>The difference between the two images as a percentage  - value between 0 and 1.</returns>
+        float PercentageDifference(Image thisOne, Image theOtherOne, float? threshold = null);
+    }
+}

Aquality.Selenium.Core/src/Aquality.Selenium.Core/Visualization/IImageComparator.cs

@@ -0,0 +1,116 @@
+using Aquality.Selenium.Core.Configurations;
+using System;
+using System.Drawing;
+
+namespace Aquality.Selenium.Core.Visualization
+{
+    /// <summary>
+    /// Compares images with defined threshold.
+    /// Uses resizing and gray-scaling to simplify comparison.
+    /// Uses parameters from <see cref="IVisualizationConfiguration"/>.
+    /// Special thanks to https://www.codeproject.com/Articles/374386/Simple-image-comparison-in-NET
+    /// </summary>
+    public class ImageComparator : IImageComparator
+    {
+        private const int ThresholdDivisor = 255;
+        private readonly IVisualizationConfiguration visualizationConfiguration;
+
+        public ImageComparator(IVisualizationConfiguration visualizationConfiguration)
+        {
+            this.visualizationConfiguration = visualizationConfiguration;
+        }
+
+        private float DefaultThreshold => visualizationConfiguration.DefaultThreshold;
+        private int ComparisonHeight => visualizationConfiguration.ComparisonHeight;
+        private int ComparisonWidth => visualizationConfiguration.ComparisonWidth;
+
+        /// <summary>
+        /// Gets the difference between two images as a percentage
+        /// </summary>
+        /// <param name="thisOne">The first image</param>
+        /// <param name="theOtherOne">The image to compare with</param>
+        /// <param name="threshold">How big a difference will be ignored as a percentage - value between 0 and 1. 
+        /// If the value is null, the default value is got from <see cref="IVisualizationConfiguration"/>.</param>
+        /// <returns>The difference between the two images as a percentage  - value between 0 and 1.</returns>
+        /// <remarks>See https://web.archive.org/web/20130208001434/http://tech.pro:80/tutorial/660/csharp-tutorial-convert-a-color-image-to-grayscale for more details.</remarks>
+        public virtual float PercentageDifference(Image thisOne, Image theOtherOne, float? threshold = null)
+        {
+            var thresholdValue = threshold ?? DefaultThreshold;
+            if (thresholdValue < 0 || thresholdValue > 1)
+            {
+                throw new ArgumentOutOfRangeException(nameof(threshold), thresholdValue, "Threshold should be between 0 and 1");
+            }
+
+            var byteThreshold = Convert.ToByte(thresholdValue * ThresholdDivisor);
+            return PercentageDifference(thisOne, theOtherOne, byteThreshold);
+        }
+
+        /// <summary>
+        /// Gets the difference between two images as a percentage
+        /// </summary>
+        /// <param name="thisOne">The first image</param>
+        /// <param name="theOtherOne">The image to compare with</param>
+        /// <param name="threshold">How big a difference (out of 255) will be ignored - the default is 3.</param>
+        /// <returns>The difference between the two images as a percentage</returns>
+        /// <remarks>See https://web.archive.org/web/20130208001434/http://tech.pro:80/tutorial/660/csharp-tutorial-convert-a-color-image-to-grayscale for more details</remarks>
+        protected virtual float PercentageDifference(Image thisOne, Image theOtherOne, byte threshold = 3)
+        {
+            var differences = GetDifferences(thisOne, theOtherOne);
+
+            int diffPixels = 0;
+
+            foreach (byte b in differences)
+            {
+                if (b > threshold) { diffPixels++; }
+            }
+
+            return diffPixels / ((float)ComparisonWidth * ComparisonHeight);
+        }
+
+        /// <summary>
+        /// Finds the differences between two images and returns them in a double-array
+        /// </summary>
+        /// <param name="thisOne">The first image</param>
+        /// <param name="theOtherOne">The image to compare with</param>
+        /// <returns>the differences between the two images as a double-array</returns>
+        protected virtual byte[,] GetDifferences(Image thisOne, Image theOtherOne)
+        {
+            var firstGray = GetResizedGrayScaleValues(thisOne);
+            var secondGray = GetResizedGrayScaleValues(theOtherOne);
+
+            var differences = new byte[ComparisonWidth, ComparisonHeight];
+            for (int y = 0; y < ComparisonHeight; y++)
+            {
+                for (int x = 0; x < ComparisonWidth; x++)
+                {
+                    differences[x, y] = (byte)Math.Abs(firstGray[x, y] - secondGray[x, y]);
+                }
+            }
+
+            return differences;
+        }
+
+        /// <summary>
+        /// Gets the lightness of the image in sections (by default 256 sections, 16x16)
+        /// </summary>
+        /// <param name="img">The image to get the lightness for</param>
+        /// <returns>A double-array (16x16 by default) containing the lightness of the sections(256 by default)</returns>
+        protected virtual byte[,] GetResizedGrayScaleValues(Image img)
+        {
+            using (var thisOne = (Bitmap)img.Resize(ComparisonWidth, ComparisonHeight).GetGrayScaleVersion())
+            {
+                byte[,] grayScale = new byte[thisOne.Width, thisOne.Height];
+
+                for (int y = 0; y < thisOne.Height; y++)
+                {
+                    for (int x = 0; x < thisOne.Width; x++)
+                    {
+                        grayScale[x, y] = (byte)Math.Abs(thisOne.GetPixel(x, y).R);
+                    }
+                }
+
+                return grayScale;
+            }
+        }
+    }
+}