UITestAutomation Framework

NOTICE.md

@@ -1322,6 +1322,7 @@ EXHIBIT A -Mozilla Public License.
 - Microsoft.CodeAnalysis.NetAnalyzers 9.0.0
 - Microsoft.Data.Sqlite 9.0.2
 - Microsoft.Diagnostics.Tracing.TraceEvent 3.1.16
+- Microsoft.DotNet.ILCompiler (A)
 - Microsoft.Extensions.DependencyInjection 9.0.2
 - Microsoft.Extensions.Hosting 9.0.2
 - Microsoft.Extensions.Hosting.WindowsServices 9.0.2

PowerToys.sln

@@ -636,6 +636,8 @@ Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "ZoomItModuleInterface", "sr
 EndProject
 Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "ZoomItSettingsInterop", "src\modules\ZoomIt\ZoomItSettingsInterop\ZoomItSettingsInterop.vcxproj", "{CA7D8106-30B9-4AEC-9D05-B69B31B8C461}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "UITestAutomation", "src\common\UITestAutomation\UITestAutomation.csproj", "{A558C25D-2007-498E-8B6F-43405AFAE9E2}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|ARM64 = Debug|ARM64
@@ -2834,6 +2836,18 @@ Global
 		{CA7D8106-30B9-4AEC-9D05-B69B31B8C461}.Release|x64.Build.0 = Release|x64
 		{CA7D8106-30B9-4AEC-9D05-B69B31B8C461}.Release|x86.ActiveCfg = Release|x64
 		{CA7D8106-30B9-4AEC-9D05-B69B31B8C461}.Release|x86.Build.0 = Release|x64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Debug|ARM64.ActiveCfg = Debug|ARM64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Debug|ARM64.Build.0 = Debug|ARM64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Debug|x64.ActiveCfg = Debug|x64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Debug|x64.Build.0 = Debug|x64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Debug|x86.ActiveCfg = Debug|x64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Debug|x86.Build.0 = Debug|x64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Release|ARM64.ActiveCfg = Release|ARM64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Release|ARM64.Build.0 = Release|ARM64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Release|x64.ActiveCfg = Release|x64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Release|x64.Build.0 = Release|x64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Release|x86.ActiveCfg = Release|x64
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2}.Release|x86.Build.0 = Release|x64
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -3069,6 +3083,7 @@ Global
 		{0A84F764-3A88-44CD-AA96-41BDBD48627B} = {DD6E12FE-5509-4ABC-ACC2-3D6DC98A238C}
 		{E4585179-2AC1-4D5F-A3FF-CFC5392F694C} = {DD6E12FE-5509-4ABC-ACC2-3D6DC98A238C}
 		{CA7D8106-30B9-4AEC-9D05-B69B31B8C461} = {DD6E12FE-5509-4ABC-ACC2-3D6DC98A238C}
+		{A558C25D-2007-498E-8B6F-43405AFAE9E2} = {1AFB6476-670D-4E80-A464-657E01DFF482}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {C3A2F9D1-7930-4EF4-A6FC-7EE0A99821D0}

doc/devdocs/UITests.md

@@ -0,0 +1,101 @@
+# UI tests framework
+
+ A specialized UI test framework for PowerToys that makes it easy to write UI tests for PowerToys modules or settings. Let's start writing UI tests!
+
+## Before running tests  
+
+- Install Windows Application Driver v1.2.1 from https://github.com/microsoft/WinAppDriver/releases/tag/v1.2.1 to the default directory (`C:\Program Files (x86)\Windows Application Driver`)
+
+- Enable Developer Mode in Windows settings
+
+## Running tests
+
+- Exit PowerToys if it's running.
+
+- Open `PowerToys.sln` in Visual Studio and build the solution.
+
+- Run tests in the Test Explorer (`Test > Test Explorer` or `Ctrl+E, T`).
+
+
+## How to add the first UI tests for your modules
+
+- Create a new project and add the following references to the project file. Change the OutputPath to your own module's path.
+  ```
+  	<PropertyGroup>
+  		<OutputType>Library</OutputType>
+  		<!-- This is a UI test, so don't run as part of MSBuild -->
+  		<RunVSTest>false</RunVSTest>
+  	</PropertyGroup>
+
+  	<PropertyGroup>
+  		<OutputPath>..\..\..\..\$(Platform)\$(Configuration)\tests\KeyboardManagerUITests\</OutputPath>
+  	</PropertyGroup>
+
+  	<ItemGroup>
+  	    <PackageReference Include="MSTest" />
+  	    <ProjectReference Include="..\..\..\common\UITestAutomation\UITestAutomation.csproj" />
+  	    <Folder Include="Properties\" />
+	</ItemGroup>
+  ```
+- Inherit your test class from UITestBase.
+  >Set Scope: The default scope starts from the PowerToys settings UI. If you want to start from your own module, set the constructor as shown below:
+
+- >Default Scope:
+  ```
+  [TestClass]
+  public class RunFancyZonesTest : UITestBase
+  {
+      public RunFancyZonesTest()
+          : base()
+      {
+      }
+  }
+  ```
+  >Specify Scope:
+  ```
+  [TestClass]
+  public class RunFancyZonesTest : UITestBase
+  {
+      public RunFancyZonesTest()
+          : base(PowerToysModule.FancyZone)
+      {
+      }
+  }
+  ```
+
+- Then you can start using session to perform the UI operations.
+
+**Example**
+```
+namespace UITests_KeyboardManager
+{
+    [TestClass]
+    public class RunKeyboardManagerUITests : UITestBase
+    {
+        [TestMethod]
+        public void OpenKeyboardManagerEditor()
+        {
+            // Open KeyboardManagerEditor
+            Session.FindElement<Button>(By.Name("Remap a key")).Click();
+            Session.Attach(PowerToysModuleWindow.KeyboardManagerKeys);
+
+            // Maximize window
+            var window = Session.FindElement<Window>(By.Name("Remap keys")).Maximize();
+
+            // Click button
+            Session.FindElement<Button>(By.Name("Add key remapping")).Click();
+            Session.FindElement<Element>(By.Name("Row 1, Select:")).FindElement<Button>(By.Name("Select")).Click();
+            Session.FindElement<Window>(By.Name("Select a key on selected keyboard")).FindElement<Button>(By.Name("Cancel")).Click();
+            window.Close();
+
+            // Back to Settings
+            Session.Attach(PowerToysModuleWindow.PowerToysSettings);
+        }
+    }
+}
+```
+
+## Extra tools and information
+
+ **Accessibility Tools**:
+While working on tests, you may need a tool that helps you to view the element's accessibility data, e.g. for finding the button to click. For this purpose, you could use [AccessibilityInsights](https://accessibilityinsights.io/docs/windows/overview) 

src/common/UITestAutomation/Element/Button.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using OpenQA.Selenium;
+using OpenQA.Selenium.Appium.Windows;
+using OpenQA.Selenium.Interactions;
+using OpenQA.Selenium.Remote;
+using OpenQA.Selenium.Support.Events;
+
+namespace Microsoft.PowerToys.UITest
+{
+    // Represents a button in the UI test framework.
+    public class Button : Element
+    {
+        public Button()
+            : base()
+        {
+        }
+
+        // Gets the type of the button.
+        // Returns:
+        //   string: The control type of the button as a string.
+        public string GetButtonType()
+        {
+            Assert.IsNotNull(WindowsElement, "WindowsElement should not be null");
+            return WindowsElement.GetAttribute("ControlType");
+        }
+    }
+}

src/common/UITestAutomation/Element/By.cs

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Xml.Linq;
+using static OpenQA.Selenium.By;
+
+namespace Microsoft.PowerToys.UITest
+{
+    // This class is a wrapper around OpenQA.Selenium.By
+#pragma warning disable SA1649 // File name should match first type name
+    public class By
+    {
+        private readonly OpenQA.Selenium.By by;
+
+        private By(OpenQA.Selenium.By by)
+        {
+            this.by = by;
+        }
+
+        // Factory methods to create a By object
+        public static By Name(string name) => new By(OpenQA.Selenium.By.Name(name));
+
+        public static By Id(string id) => new By(OpenQA.Selenium.By.Id(id));
+
+        public static By XPath(string xpath) => new By(OpenQA.Selenium.By.XPath(xpath));
+
+        public static By CssSelector(string cssSelector) => new By(OpenQA.Selenium.By.CssSelector(cssSelector));
+
+        public static By LinkText(string linkText) => new By(OpenQA.Selenium.By.LinkText(linkText));
+
+        public static By TagName(string tagName) => new By(OpenQA.Selenium.By.TagName(tagName));
+
+        public OpenQA.Selenium.By ToSeleniumBy() => by;
+    }
+}

src/common/UITestAutomation/Element/Element.cs

@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Collections.ObjectModel;
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using OpenQA.Selenium;
+using OpenQA.Selenium.Appium;
+using OpenQA.Selenium.Appium.Windows;
+using OpenQA.Selenium.Interactions;
+using OpenQA.Selenium.Remote;
+using OpenQA.Selenium.Support.Events;
+using static Microsoft.PowerToys.UITest.UITestBase;
+
+[assembly: InternalsVisibleTo("Session")]
+
+namespace Microsoft.PowerToys.UITest
+{
+    // Represents a basic UI element in the application.
+    public class Element
+    {
+        // WindowsElement and WindowsDriver are components of WinAppDriver that provide underlying element operations.
+        public WindowsElement? WindowsElement { get; set; }
+
+        private WindowsDriver<WindowsElement>? driver;
+
+        public Element() => WindowsElement = null;
+
+        internal void SetWindowsElement(WindowsElement windowsElement) => WindowsElement = windowsElement;
+
+        internal void SetSession(WindowsDriver<WindowsElement> driver) => this.driver = driver;
+
+        // Gets the name of the UI element.
+        // Returns:
+        //   string: The Name attribute of the element.
+        public string GetName() => GetAttribute("Name");
+
+        // Gets the text of the UI element.
+        // Returns:
+        //   string: The Value attribute of the element.
+        public string GetText() => GetAttribute("Value");
+
+        // Gets the automation ID of the UI element.
+        // Returns:
+        //   string: The AutomationID attribute of the element.
+        public string GetAutomationId() => GetAttribute("AutomationId");
+
+        // Gets the class name of the UI element.
+        // Returns:
+        //   string: The ClassName attribute of the element.
+        public string GetClassName() => GetAttribute("ClassName");
+
+        // Gets the help text of the UI element.
+        // Returns:
+        //   string: The HelpText attribute of the element.
+        public string GetHelpText() => GetAttribute("HelpText");
+
+        // Checks if the UI element is enabled.
+        // Returns:
+        //   bool: True if the element is enabled; otherwise, false.
+        public bool IsEnabled() => GetAttribute("IsEnabled") == "True";
+
+        // Checks if the UI element is selected.
+        // Returns:
+        //   bool: True if the element is selected; otherwise, false.
+        public bool IsSelected() => GetAttribute("IsSelected") == "True";
+
+        // Click the UI element
+        public void Click() => PerformAction(actions => actions.Click());
+
+        // Right click the UI element
+        public void RightClick() => PerformAction(actions => actions.ContextClick());
+
+        // Underlying function to get attribute by WindowsElement
+        private string GetAttribute(string attributeName)
+        {
+            Assert.IsNotNull(WindowsElement, "WindowsElement should not be null");
+            return WindowsElement?.GetAttribute(attributeName) ?? string.Empty;
+        }
+
+        public T FindElement<T>(By by, int timeoutMS = 3000)
+            where T : Element, new()
+        {
+            Assert.IsNotNull(WindowsElement, "WindowsElement is null");
+            return FindElementHelper.FindElement<T, AppiumWebElement>(() => WindowsElement.FindElement(by.ToSeleniumBy()), timeoutMS, driver);
+        }
+
+        // Find elements by name
+        public ReadOnlyCollection<T>? FindElements<T>(By by, int timeoutMS = 3000)
+            where T : Element, new()
+        {
+            Assert.IsNotNull(WindowsElement, "WindowsElement is null");
+            return FindElementHelper.FindElements<T, AppiumWebElement>(() => WindowsElement.FindElements(by.ToSeleniumBy()), timeoutMS, driver);
+        }
+
+        // Simulate manual operation
+        private void PerformAction(Action<Actions> action)
+        {
+            var element = WindowsElement;
+            Actions actions = new Actions(driver);
+            actions.MoveToElement(element);
+            action(actions);
+            actions.Build().Perform();
+        }
+    }
+}

src/common/UITestAutomation/Element/FindElementHelper.cs

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Collections.Generic;
+using System.Collections.ObjectModel;
+using System.Linq;
+using System.Runtime.CompilerServices;
+using System.Text;
+using System.Threading.Tasks;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using OpenQA.Selenium;
+using OpenQA.Selenium.Appium;
+using OpenQA.Selenium.Appium.Windows;
+
+[assembly: InternalsVisibleTo("Element")]
+[assembly: InternalsVisibleTo("Session")]
+
+namespace Microsoft.PowerToys.UITest
+{
+    // Helper class for finding elements
+    internal static class FindElementHelper
+    {
+        public static T FindElement<T, TW>(Func<TW> findElementFunc, int timeoutMS, WindowsDriver<WindowsElement>? driver)
+            where T : Element, new()
+        {
+            Assert.IsNotNull(driver, "driver is null");
+            driver.Manage().Timeouts().ImplicitWait = TimeSpan.FromMilliseconds(timeoutMS);
+            var item = findElementFunc() as WindowsElement;
+            Assert.IsNotNull(item, "Can't find this element");
+
+            return NewElement<T>(item, driver);
+        }
+
+        public static ReadOnlyCollection<T>? FindElements<T, TW>(Func<ReadOnlyCollection<TW>> findElementsFunc, int timeoutMS, WindowsDriver<WindowsElement>? driver)
+            where T : Element, new()
+        {
+            Assert.IsNotNull(driver, "driver is null");
+            driver.Manage().Timeouts().ImplicitWait = TimeSpan.FromMilliseconds(timeoutMS);
+            var items = findElementsFunc();
+            var res = items.Select(item =>
+            {
+                var element = item as WindowsElement;
+                if (element != null)
+                {
+                    NewElement<T>(element, driver);
+                }
+
+                return element;
+            }).Where(element => element != null).ToList();
+
+            return new ReadOnlyCollection<T>((IList<T>)res);
+        }
+
+        // Creates a new element of type T.
+        public static T NewElement<T>(WindowsElement element, WindowsDriver<WindowsElement>? driver)
+             where T : Element, new()
+        {
+            T newElement = new T();
+            Assert.IsNotNull(driver, "[FindElementHelper.cs] driver is null");
+            newElement.SetSession(driver);
+            Assert.IsNotNull(element, "[FindElementHelper] element is null");
+            newElement.SetWindowsElement(element);
+            return newElement;
+        }
+    }
+}