Add markdown file

Author: adinastoll

docs/automated-testing/ui-testing/images/appium-inspector.PNG

@@ -0,0 +1,230 @@
+# UI Tests for a Teams application
+
+## Overview
+In this section we will provide an overview on how one could implement UI tests for a custom Teams application.
+Generally, to ensure a great experience for your end users, you would like to implement automated test which covers your features both in a browser as well as on mobile platforms. In what follows, we will go through learnings we have gained based on previous experience with our customers.
+
+## Web based UI tests 
+To implement web-based UI tests for your Teams application, you can follow the same approach as for testing any other web application with a UI. [UI testing](./README.md) provides good guidance on that. The starting point for your test would be to launch a browser in an automated way (using Selenium, or similar frameworks) and go to https://teams.microsoft.com/. 
+
+If you would like to test a Teams app which was not yet published into the Teams' store, or if you would like to test the DEV/QA version of your app:
+<!-- - Publish the app in a tenant, and use for testing a user which has access to it. In this case, your UI testing focuses on testing your functionalities and threats the Teams' manifest as the *shell* for your code. However, in this case, your test would not catch changes in your [Teams' manifest file](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) (such as: new icons, new names etc).  -->
+- First, using for example [Teams Toolkit](https://github.com/OfficeDev/TeamsFx), package your app based on the [manifest.json](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema). See below an example on how to achieve that:
+```javascript
+npx teamsfx package --env dev --manifest-path ...
+```
+ - Then, implement an automated step which [uploads your custom app](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/deploy-and-publish/apps-upload) into the Teams' of for your test user. 
+```{note}
+The packaging of your app could be done automatically in a pipeline and the output (Zipped file) could be downloaded as part of your UI tests execution.
+```
+If you would like to test the production version of your app which was already published in the store you would first need to automate the installation of the app from Teams' store for your test user.
+
+Once the app was installed, implement selectors to [access your custom app](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/deploy-and-publish/apps-upload#access-your-app) and to perform various actions within the app. 
+
+### Pipeline
+If you are using Selenium and Edge as the browser, consider leveraging the [selenium/standalone-edge](https://hub.docker.com/r/selenium/standalone-edge) Docker image which contains a standalone Selenium server with the Microsoft Edge browser installed. By default, it would run in headless mode, but by setting `START_XVFB` variable to `True`, you can control whether to start a virtual framebuffer server (Xvfb) that allows GUI applications to run without a display. Below is a code snippet which illustrated the usage of the image in a Gitlab pipeline:
+
+```yml
+...
+run-tests-dev:
+  allow_failure: false
+  image: ...
+  environment:
+    name: dev
+  stage: tests
+  services:
+    - name: selenium/standalone-edge:latest
+      alias: selenium
+      variables:
+        START_XVFB: "true"
+        description: "Start Xvfb server"
+...
+```
+
+When running your test, you would need to use the Selenium server URL for remote execution. With the definition from above, the URL would be: http://selenium:4444/wd/hub. The code snipped below illustrated how one could initialize the Selenium driver to point to the remote Selenium server using JavaScript:
+
+```javascript
+var { Builder } = require("selenium-webdriver");
+const edge = require("selenium-webdriver/edge");
+
+var buildEdgeDriver = function () {
+  let builder = new Builder().forBrowser("MicrosoftEdge");
+  builder = builder.usingServer("http://selenium:4444/wd/hub"); 
+  builder.setEdgeOptions(new edge.Options().addArguments("--inprivate"));
+  return builder.build();
+};
+```
+
+## Mobile based UI tests
+Testing your custom Teams application on mobile devices is not as straight forward as for the web-based approach due to its challenging setup.
+Naturally, it implies the usage of actual devices which is generally more complex. Especially running such tests in a CI/CD pipeline can be more difficult and resource-intensive. 
+
+One approach is to use real devices or cloud-based emulators from vendors such as BrowserStack. This requires a license to such vendors. Alternatively, you could use virtual devices hosted in Azure Virtual Machines. 
+
+In what follows, we will provide guidance on how to achieve both. 
+
+<!-- There are two proven ways through which this can still be achieved for Android, based on previous experience with our customers: -->
+
+### 1. Using Android Virtual Devices
+
+This approach enables the creation of Android UI tests using virtual devices. It comes with the advantage of not requiring a paid licenses to certain vendors. However, due to the nature of emulators, compared to real devices, it may prove to be less stable. Always choose the solution that best fits your project requirements and resources. 
+
+Overall setup:
+- [AVD - Android Virtual Devices](https://developer.android.com/studio/run/managing-avds) - which are virtual representation of physical Android devices.
+- [Appium](https://appium.io/) is an open-source project designed to facilitate UI automation of many app platforms, including mobile.
+    - Appium is based on the [W3C WebDriver specification](https://w3c.github.io/webdriver/). 
+    > Note: If you look at these commands in the WebDriver specification, you will notice that they are not defined in terms of any particular programming language. They are not Java commands, or JavaScript commands, or Python commands. Instead, they form part of an HTTP API which can be accessed from within any programming language.
+    - Appium implements a client-server architecture:
+        - The server (consisting of Appium itself along with any drivers or plugins you are using for automation) is connected to the devices under test, and is actually responsible for making automation happen on those devices. [UiAutomator](https://github.com/appium/appium-uiautomator2-driver) driver is compatible with Android platform.
+        - The [client](https://appium.io/docs/en/2.0/intro/clients/) is responsible for sending commands to the server over the network, and receiving responses from the server as a result. You can choose the language of your choice to write the commands. For example, for Javascript [WebDriverIO](https://webdriver.io/) can be used as client.
+        > [Here](https://appium.io/docs/en/2.0/ecosystem/) you can read more about Appium ecosystem
+      - The advantage of this architecture is that it opens the possibility of running the server in a VM, and the client in a pipeline, enabling the tests to be ran automatically on scheduled basis as part of CI/CD pipelines. 
+
+### How to run mobile test locally on a Windows machine 
+In order to run locally such tests, you need two things:
+1. An emulator ([AVD - Android Virtual Devices](https://developer.android.com/studio/run/managing-avds)), which will represent the physical device.
+1. [Appium server](https://appium.io/docs/en/2.1/), which will redirect the commands from the test to your virtual device.
+
+#### a) Steps to create Android Virtual Device:
+1. Install Android Studio from [official link](https://developer.android.com/studio). 
+    > Note: At the time of writing the documentation, the latest version available was Android Studio Giraffe, 2022.3.1 Patch 2 for Window.
+    1. Set ANDROID_HOME environment variable to point to the installation path of Android SDK. i.e. ` C:Users\<user-name>\AppData\Local\Android\Sdk`
+1. Install Java Development Kit (JDK) from [official link](https://www.oracle.com/java/technologies/javase/jdk11-archive-downloads.html). For the most recent devices JDK 9 is required, otherwise JDK 8 is required. Make sure you get the JDK and not the JRE.
+    1. Set JAVA_HOME environment variable to the installation path, i.e. ` C:\Program Files\Java\jdk-11`
+1. Create an AVD (Android Virtual Device):
+    1. Open Android Studio. From the Android Studio welcome screen, select **More Action -> Virtual Device Manager**, as instructed [here](https://developer.android.com/studio/run/managing-avds#:~:text=1%20Open%20the%20AVD%20Manager%20by%20clicking%20Tools,%20settings%2C%20such%20as%20the%20skin.%20See%20More.)
+    1. Click **Create Device**.
+    1. Choose a device definition with **Play Store** enabled. This is important, otherwise Teams cannot be installed on the device.
+    1. Choose a System image from the **Recommended** tab which includes access to Google Play services. You may need to install it before selecting it.
+    1. Start the emulator by clicking on the Run button from the Device Manage screen.
+    1. Manually install Microsoft Teams from Google Playstore on the device. 
+
+####  b) Steps to set up Appium
+- Install `appium`:
+    1. Download NodeJs, if it is not already installed on your machine: [Download | Node.js (nodejs.org)](https://nodejs.org/en/download)
+    1. Install Appium globally: [Install Appium - Appium Documentation](https://appium.io/docs/en/2.0/quickstart/install/)
+    1. Install the UiAutomator2 driver: [Install the UiAutomator2 Driver - Appium Documentation](https://appium.io/docs/en/2.0/quickstart/uiauto2-driver/). Go through the `Set up Android automation requirements` in the documentation, to make sure you have set up everything correctly.
+
+        > [Here](https://appium.io/docs/en/2.0/intro/drivers/) you can read more about Appium Drivers.
+    1. Start appium server by running `appium` command in a command prompt.
+####  Useful commands:
+- To list the emulators that you have previously created, without opening Android Studio:
+    ```cli
+    emulator -list-avds
+    ```
+- To start an emulator, without opening Android Studio:
+    ```cli
+    emulator -avd {name-of-emulator}
+    ```
+- To get the name of your AVD, assuming your emulator is running, you can run:
+    
+    ```cli
+    adb devices
+    ```
+    You should see a response with *List of devices attached*, where your running device will be listed.
+
+### How to set up an Azure VM for running mobile tests in a pipeline
+
+### 1. VM configuration
+This approach essentially hosts a virtual device in a virtual machine. In order to be able to set up the emulator (Android Virtual Device) in an Azure VM, the VM should support [nested virtualization](https://azure.microsoft.com/en-us/blog/nested-virtualization-in-azure/). 
+
+Azure VM configuration which, at the time of writing the documentation, worked successfully with AVD and appium:
+- Operating system: Windows (Windows-10 Pro)
+- VM generation: V1
+- Size: Standard D4ds v5 16 GiB memory
+
+### 2. Enable connection from outside to Appium server on the VM 
+> Note: By default appium server runs on port 4723. The rest of the steps will assume that this is the port where your appium server runs.
+
+In order to be able to reach appium server which runs on the VM from outside, the following steps are needed:
+1. Create an [Inbound Rule](https://learn.microsoft.com/en-us/windows/security/operating-system-security/network-security/windows-firewall/create-an-inbound-port-rule) for port 4723 from within the VM.
+1. Create an Inbound Security Rule in the NSG (Network Security Group) of the VM to be able to connect from that IP address to port 4723.
+    - Find out the IP of the machine on which the tests will run on.
+    - Replace the *Source IP Address* with the IP of your machine.
+
+### 3. Install Android Studio and create AVD inside the VM
+1. Follow the instructions from steps a) and b) in **How to run mobile end to end tests on a Windows machine** section above.
+1. When you launch the emulator, it may show a warning as below and will eventually crash:
+
+    ![failure](./images/warning.png)
+
+    Solution to fix it: 
+    1. [Enable Windows Hypervisor Platform](https://devblogs.microsoft.com/visualstudio/hyper-v-android-emulator-support/)
+    1. [Enable Hyper-V](https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v#enable-the-hyper-v-role-through-settings) (if not enabled by default)
+1. Restart the VM.
+1. Restart the AVD.
+
+
+### How to inspect the Teams app in Azure Virtual Device (AVD)
+Inspecting the app is very useful as you write new tests, as it allows you to find the ID of different elements displayed on the screen - similar to DevTools, which allows you to navigate through the DOM of a web page.
+
+[Appium Inspector](https://inspector.appiumpro.com/) is a very useful tool that allows you to inspect an app runing on an emulator.
+
+> Note: This section assumes that you have already performed the prerequisites from **How to run mobile end to end tests on a Windows machine**
+
+### Steps to inspect Teams app:
+1. Run the appium server with [--alow-cors flag](https://appium.readthedocs.io/en/latest/en/writing-running-appium/server-args/) by running the following command in a terminal:
+    ```
+    appium --allow-cors
+    ```
+2. Go to https://inspector.appiumpro.com and type in the following properties:
+    ```json
+    {
+    "appium:deviceName": "your-emulator-name",
+    "appium:appPackage": "com.microsoft.teams",
+    "appium:appActivity": "com.microsoft.skype.teams.Launcher",
+    "appium:automationName": "UiAutomator2",
+    "platformName": "Android"
+    }
+    ```
+
+    1. "appium:deviceName" - is the name of your emulator. In **Useful commands** sections from above, you can see how to get the name of your AVD.
+    1. "appium:appPackage" - is the name of the package, should be kept to "**com.microsoft.teams**".
+    1. "appium:appActivity"-  is the name of th eactivity in the app that you want to launch, should be kept to "**com.microsoft.skype.teams.Launcher**"
+    1. "appium:automationName" - is the name of the driver you are using, in this case, "**UiAutomator2**"
+
+    If the appium server runs on your local machine at the default portal, then Remote Host and Remote Port can be kept to the default values.
+
+    The configuration should look similar to the printscren below:
+    ![appium-inspector](./images/appium-inspector.png)
+3. Press on **Start Session**.
+    - In the browser, you should see a similar view as below:
+    ![teams-appium-inspector](./images/teams-appium-inspector.png)
+    - You can do any action on the emulator, and if you press on the "Refresh" button in the browser, the left hand side of the Appium Inspector will reflect your app. In the **App Source** you will be able to see the IDs of the elements, so you can write relevant selectors in your tests. 
+
+#### How to connect to Appium server
+We will provide an example on how to achieve this using JavaScript. Similar approach can be followed for other languages.
+Assuming you are using [webdriverio](https://webdriver.io/) as the client, you would need to initialize the remote connection as follows:
+
+```javascript
+ const opts = {
+      port: 4723,
+      hostname: "your-hostname",
+      capabilities: {
+        platformName: "android",
+        "appium:deviceName": "the-name-of-the-virtual-device",
+        "appium:appPackage": "com.microsoft.teams",
+        "appium:appActivity": "com.microsoft.skype.teams.Launcher",
+        "appium:automationName": "the-name-of-the-driver",
+      },
+    };
+
+    // Create a new WebDriverIO instance with the Appium server URL and capabilities
+    await wdio.remote(opts);
+```
+
+1. "port": the port on which the Appium server runs on. By default, it is 4723.
+1. "hostname": the IP of the machine where the Appium sever runs on. If it is running locally, that is 127.0.0.1. If it runs in an Azure VM, it would be the public IP address of the VM. Note: ensure you have followed the steps from **2. Enable connection from outside to Appium server on the VM**.
+1. "platformName": Appium can be used to connect to different platforms (Windows, iOS, Android). In our case, it would be "android".
+1. "appium:deviceName": the name of the Android Virtual Device. See **Useful commands** on how to find the name of the device.
+1. "appium:appPackage": the name of the app's package that you would like to launch. Teams' package name is "com.microsoft.teams".
+1. "appium:appActivity": the activity within Teams that you would like to launch on the device. In our case, we would like just to launch the app. The activity name for launching Teams is called "com.microsoft.skype.teams.Launcher".
+1. "appium:automationName": the name of the driver you are using. Note: Appium can communicate to different platforms. This is achieved by installing a dedicated driver, designed for each platform. In our case, it would be [UiAutomator2](https://github.com/appium/appium-uiautomator2-driver) or [Espresso](https://github.com/appium/appium-espresso-driver), since they are both designed for Android platform. 
+
+### 2. Using BrowserStack
+- BrowserStack does not support out of the box the installation of Teams from the App Store or Play Store. However, there is a workaround, described in [their documentation](https://www.browserstack.com/support/faq/app-automate/app/can-i-install-an-app-from-the-app-store-or-play-store). Therefore, if you choose to go this way, you would first need to implement a step that installs Teams on the cloud-based device, by implementing the workaround described above.
+- You may encounter issues with Google login, as it requires a newly created Google account, in order to log in to the store. To overcome this, make sure to disable 2FA from Google, further described in [Troubleshooting Google login issues](https://www.browserstack.com/docs/app-automate/appium/advanced-features/setup-google-account#nodejs).
+
+
+
+