Merge pull request #833 from hassanuz/master

WinAppDriver Documentation & ReadMe changes.
microsoft · Aug 27, 2019 · c33c66b · c33c66b
2 parents 755e338 + 3f66a02
commit c33c66b
Show file tree

Hide file tree

Showing 10 changed files with 539 additions and 267 deletions.
diff --git a/Docs/AuthoringTestScripts.md b/Docs/AuthoringTestScripts.md
@@ -0,0 +1,75 @@
+## Authoring Your Own Test Script
+
+You can choose any programming language or tools supported by Appium/Selenium to write your test scripts. In the example below, we will author the test script in C# using Microsoft Visual Studio.
+
+### Creating a Test Project
+
+1. Open **Microsoft Visual Studio 2015** or **Microsoft Visual Studio 2017**
+   > **Note**: in Visual Studio 2017 make sure you have the optional **.NET desktop development** workload installed
+2. Create the test project and solution. I.e. Select **New Project > Templates > Visual C# > Test > Unit Test Project**
+3. Once created, select **Project > Manage NuGet Packages... > Browse** and search for **Appium.WebDriver**
+4. Install the **Appium.WebDriver** NuGet packages for the test project
+5. Start writing your test (see sample code under [samples](/Samples/))
+
+### Testing a Universal Windows Platform Application
+
+To test a UWP app, simply specify the **Application Id** for the application you want to test in the **app** capabilities entry when you are creating a session. You can also specify launching arguments if your application supports them through **appArguments** capability. Below is an example of creating a test session for Windows **Alarms & Clock** app written in C#:
+
+```c#
+// Launch the Alarms & Clock app
+DesiredCapabilities appCapabilities = new DesiredCapabilities();
+appCapabilities.SetCapability("app", "Microsoft.WindowsAlarms_8wekyb3d8bbwe!App");
+AlarmClockSession = new WindowsDriver<WindowsElement>(new Uri("http://127.0.0.1:4723"), appCapabilities);
+
+// Use the session to control the app
+AlarmClockSession.FindElementByAccessibilityId("AddAlarmButton").Click();
+AlarmClockSession.FindElementByAccessibilityId("AlarmNameTextBox").Clear();
+```
+
+> You can find the **Application Id** of your application in the generated `AppX\vs.appxrecipe` file under `RegisteredUserModeAppID` node. E.g. `c24c8163-548e-4b84-a466-530178fc0580_scyf5npe3hv32!App`
+
+### Testing a Classic Windows Application
+
+To test a classic Windows app, specify the **full executable path** for the app under test in the **app** capabilities entry when creating a new session. Similar with modern (UWP) app, you can specify launching arguments through **appArguments** capability. But unlike modern apps, you can also specify the app working directory for a classic app through "appWorkingDir" capability. Below is an example of creating a test session for the **Notepad** app that opens `MyTestFile.txt` in `C:\MyTestFolder\`.
+
+```c#
+// Launch Notepad
+DesiredCapabilities appCapabilities = new DesiredCapabilities();
+appCapabilities.SetCapability("app", @"C:\Windows\System32\notepad.exe");
+appCapabilities.SetCapability("appArguments", @"MyTestFile.txt");
+appCapabilities.SetCapability("appWorkingDir", @"C:\MyTestFolder\");
+NotepadSession = new WindowsDriver<WindowsElement>(new Uri("http://127.0.0.1:4723"), appCapabilities);
+
+// Use the session to control the app
+NotepadSession.FindElementByClassName("Edit").SendKeys("This is some text");
+```
+## Inspecting UI Elements
+
+The latest Microsoft Visual Studio version by default includes the Windows SDK with a great tool to inspect the application you are testing. This tool allows you to see every UI element/node that you can query using Windows Application Driver. This **inspect.exe** tool can be found under the Windows SDK folder which is typically `C:\Program Files (x86)\Windows Kits\10\bin\x86`
+
+More detailed documentation on Inspect is available on MSDN <https://msdn.microsoft.com/library/windows/desktop/dd318521(v=vs.85).aspx>.
+## Supported Locators to Find UI Elements
+
+Windows Application Driver supports various locators to find UI element in the application session. The table below shows all supported locator strategies with their corresponding UI element attributes shown in **inspect.exe**.
+
+| Client API                   	| Locator Strategy 	| Matched Attribute in inspect.exe       	| Example      	|
+|------------------------------	|------------------	|----------------------------------------	|--------------	|
+| FindElementByAccessibilityId 	| accessibility id 	| AutomationId                           	| AppNameTitle 	|
+| FindElementByClassName       	| class name       	| ClassName                              	| TextBlock    	|
+| FindElementById              	| id               	| RuntimeId (decimal)                    	| 42.333896.3.1	|
+| FindElementByName            	| name             	| Name                                   	| Calculator   	|
+| FindElementByTagName         	| tag name         	| LocalizedControlType (upper camel case)	| Text         	|
+| FindElementByXPath           	| xpath            	| Any                                    	| //Button[0]  	|
+
+## Supported Capabilities
+
+Below are the capabilities that can be used to create Windows Application Driver session.
+
+| Capabilities       	| Descriptions                                          	| Example                                               	|
+|--------------------	|-------------------------------------------------------	|-------------------------------------------------------	|
+| app                	| Application identifier or executable full path        	| Microsoft.MicrosoftEdge_8wekyb3d8bbwe!MicrosoftEdge   	|
+| appArguments       	| Application launch arguments                          	| https://github.com/Microsoft/WinAppDriver             	|
+| appTopLevelWindow  	| Existing application top level window to attach to    	| `0xB822E2`                                            	|
+| appWorkingDir      	| Application working directory (Classic apps only)     	| `C:\Temp`                                             	|
+| platformName       	| Target platform name                                  	| Windows                                               	|
+| platformVersion    	| Target platform version                               	| 1.0                    
diff --git a/Docs/CI_AzureDevOps.md b/Docs/CI_AzureDevOps.md
@@ -0,0 +1,42 @@
+## WinAppDriver in CI with Azure Pipelines
+
+### Prerequisites to run WinAppDriver in CI
+The following are prequisites for running UI tests with WinAppDriver in Azure DevOps:
+
+ 1. An agent running on Windows 10 configured as interactive is required.
+
+    - The following hosted agents are supported: [HostedVS2019](https://github.com/Microsoft/azure-pipelines-image-generation/blob/master/images/win/Vs2019-Server2019-Readme.md) and [HostedVS2017](https://github.com/Microsoft/azure-pipelines-image-generation/blob/master/images/win/Vs2017-Server2016-Readme.md).
+       - If you wish to use a private agent, please refer to the Azure documentation [here](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/v2-windows?view=azure-devops) on setting one up.
+    - If the hosted agents do not meet your requirement, try using a private agent. More information on this [below](https://github.com/Microsoft/WinAppDriver/wiki/Continuous-Integration-with-WinAppDriver/_edit#getting-started-with-a-sample-build-pipeline). 
+ 1. Use Azure Pipelines - [get started today for free](https://azure.microsoft.com/en-us/pricing/details/devops/azure-pipelines/).  
+
+### WinAppDriver Task for Azure Pipelines 
+There's now a dedicated [WinAppDriver Pipelines Task](https://marketplace.visualstudio.com/items?itemName=WinAppDriver.winappdriver-pipelines-task) available on the Azure Marketplace to help you easily enable and configure WinAppDriver from inside your DevOps Pipeline. To get started, install the WinAppDriver task onto your DevOps organization from [here](https://marketplace.visualstudio.com/acquisition?itemName=WinAppDriver.winappdriver-pipelines-task), or you can search through the **Add Tasks** menu from inside your Pipeline Editor - 
+
+<p align="center"><img src="https://raw.githubusercontent.com/hassanuz/Sandbox/master/snippets/AzurePipelines/Task/downloadTask.PNG" width="700" align="middle"></p>
+
+Once installed, the WinAppDriver task can be added to your pipeline. 
+
+<p align="center"><img src="https://raw.githubusercontent.com/hassanuz/Sandbox/master/snippets/AzurePipelines/Task/pipelineAddTask.PNG" width="700" align="middle"></p>
+
+It is recommended to place the WinAppDriver task in conjunction with a separate Test Runner utility - in this case our pipeline has been pre-equipped with the Visual Studio Test Runner Task to drive the test cases. 
+
+<p align="center"><img src="https://raw.githubusercontent.com/hassanuz/Sandbox/master/snippets/AzurePipelines/Task/startTaskAdded.PNG" width="300" align="middle"></p>
+
+We can now configure the task - you can see that automatically the Task is named to "Start - WinAppDriver". It is not required to pass in any arguments, but it is recommended to set the System Resolution on Agent to **1080P** - this will be especially important to declare on a hosted agent. 
+
+<p align="center"><img src="https://raw.githubusercontent.com/hassanuz/Sandbox/master/snippets/AzurePipelines/Task/startTaskOptions.PNG" width="700" align="middle"></p>
+
+Once configured, it's recommended to add another instance of the WinAppDriver task, this time having it be configured to "Stop" WinAppDriver on the agent. The "Stop- WinAppDriver" instance of the task should be placed after the VS Test task, so that WinAppDriver is terminated on the agent once all the test cases have been executed. 
+
+<p align="center"><img src="https://raw.githubusercontent.com/hassanuz/Sandbox/master/snippets/AzurePipelines/Task/stopTaskOptions.PNG" width="700" align="middle"></p>
+
+Congratulations! Assuming all went well, you can now view the captured WinAppDriver logs from the Summary Panel of the "Close - WinAppDriver" instance of the task. 
+
+<p align="center"><img src="https://raw.githubusercontent.com/hassanuz/Sandbox/master/snippets/AzurePipelines/Task/ResultsSummary.PNG" width="700" align="middle"></p>
+
+And the WinAppDriver logs,
+
+<p align="center"><img src="https://raw.githubusercontent.com/hassanuz/Sandbox/master/snippets/AzurePipelines/Task/Results.PNG" width="700" align="middle"></p>
+
+Finally after you've finished with all the steps above, don't forget to add the finishing touches to your repository by embedding the official [Azure Pipelines status badge](https://docs.microsoft.com/en-us/azure/devops/pipelines/create-first-pipeline?view=azure-devops&tabs=tfs-2018-2#add-a-status-badge-to-your-repository)!