Reorganization and comments in Toolkit.UITests.Shared

Author: imalcolm1

src/Tests/UITests/Toolkit.UITests.Shared/Appium/AppiumTestBase.CrashHandler.cs

@@ -6,6 +6,10 @@ public abstract partial class AppiumTestBase
 {
     private static bool HasAppCrashed = false;
 
+    /// <summary>
+    /// Tests running after a the App has crashed should immediately return inconclusive to avoid wasting time,
+    /// and because it cannot be determined whether they would pass otherwise.
+    /// </summary>
     [TestInitialize]
     public void FailFastIfAppAlreadyCrashed()
     {

src/Tests/UITests/Toolkit.UITests.Shared/Appium/AppiumTestBase.ImageAnalysis.cs

@@ -0,0 +1,53 @@
+using OpenQA.Selenium.Appium;
+using ImageMagick;
+
+namespace Toolkit.UITest.Shared;
+
+public abstract partial class AppiumTestBase
+{
+    /// <summary>
+    /// Takes a screenshot of the parameter element.
+    /// </summary>
+    /// <remarks>
+    /// Appium screenshots work on the entire screen, not just a single element, or even a single window. This means elements
+    /// may be partially or wholly blocked if covered by another element or window. Blue light filters will also affect color
+    /// comparisons because of this.
+    /// </remarks>
+    protected MagickImage GetScreenshot(AppiumElement element)
+    {
+        var screenshot = element.GetScreenshot();
+        return new MagickImage(screenshot.AsByteArray);
+    }
+
+    /// <summary>
+    /// Normalizes pixel values based on platform and device DPI. Normalized values are approximately equivalent to what renders
+    /// on Windows at a screen density of 1 (96 DPI).
+    /// </summary>
+    protected double GetNormalizedPixelValue(int pixels)
+    {
+#if WINDOWS_TEST || ANDROID_TEST
+        return pixels / ScreenDensity;
+#elif IOS_TEST || MAC_TEST
+        // XCUI tests already returns points rather than pixels
+        return pixels;
+#else
+        throw new NotImplementedException("GetNormalizedPixelValue(int) is not implemented for this platform.");
+#endif
+    }
+
+    /// <summary>
+    /// Returns the value corresponding to the target platform of the test runner.
+    /// </summary>
+    protected int PlatformSpecificPixelValue(int windows, int android, int ios, int mac)
+    {
+#if WINDOWS_TEST
+        return windows;
+#elif ANDROID_TEST
+        return android;
+#elif IOS_TEST
+        return ios;
+#elif MAC_TEST
+        return mac;
+#endif
+    }
+}

src/Tests/UITests/Toolkit.UITests.Shared/Appium/AppiumTestBase.Screenshots.cs

@@ -118,33 +118,4 @@ protected string GetElementText(AppiumElement element, TimeSpan? timeout = null)
             throw;
         }
     }
-
-    /// <summary>
-    /// Normalizes pixel values based on platform and device DPI. Normalized values are approximately equivalent to what renders
-    /// on Windows at a screen density of 1 (96 DPI).
-    /// </summary>
-    protected double GetNormalizedPixelValue(int pixels)
-    {
-#if WINDOWS_TEST || ANDROID_TEST
-        return pixels / ScreenDensity;
-#elif IOS_TEST || MAC_TEST
-        // XCUI tests already returns points rather than pixels
-        return pixels;
-#else
-        throw new NotImplementedException("GetNormalizedPixelValue(int) is not implemented for this platform.");
-#endif
-    }
-
-    protected int PlatformSpecificPixelValue(int windows, int android, int ios, int mac)
-    {
-#if WINDOWS_TEST
-        return windows;
-#elif ANDROID_TEST
-        return android;
-#elif IOS_TEST
-        return ios;
-#elif MAC_TEST
-        return mac;
-#endif
-    }
 }

src/Tests/UITests/Toolkit.UITests.Shared/Appium/AppiumTestBase.Utils.cs

@@ -13,7 +13,7 @@
     <Compile Include="$(MSBuildThisFileDirectory)AppiumTestBase.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Appium\AppiumTestBase.CrashHandler.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Appium\AppiumTestBase.Gestures.cs" />
-    <Compile Include="$(MSBuildThisFileDirectory)Appium\AppiumTestBase.Screenshots.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Appium\AppiumTestBase.ImageAnalysis.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Appium\AppiumTestBase.Utils.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Tests\Compass\CompassTests.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Tests\ScaleLine\ScaleLineTests.cs" />