diff --git a/Docs/source/pages/alttester-editor.md b/Docs/source/pages/alttester-editor.md index 40f07211a..61f3a19af 100644 --- a/Docs/source/pages/alttester-editor.md +++ b/Docs/source/pages/alttester-editor.md @@ -57,6 +57,10 @@ In the following sections you can see a breakdown of all the sections in the GUI Will add "ALTTESTER" to the scripting define symbols. This is usually done automatically when entering in play mode or building the application. This option is not recommended if you are developing your application but can be used if you are on a branch where you only write tests. +- *Keep AltTester® prefab in scene*: + + When enabled, if the AltTester® Prefab is already present as a root object in the active scene it will be kept untouched — no new prefab is created. If the prefab is not present in the scene, it will be inserted automatically. When this option is disabled (default), the prefab is removed and recreated on each Play/Stop cycle, matching the previous behavior. + - *AltTester® Server Host* Refers to the host the AltTester® Server is listening on. @@ -67,6 +71,11 @@ In the following sections you can see a breakdown of all the sections in the GUI Refers to the port the AltTester® Server is listening on. You can change this value and make a new app build if you want to use another port. +- *App Name* + + Refers to the name used to identify the app on the AltTester® Server. + You can change this value and make a new app build if you want to use another app name. + - *Reset Connection Data* In case you are building your app on the same device but you do not want to start the new build with the connection data from the old build, you will want to check this box. Even if you managed to connect to the old build with different data, your new build will use the host, port, app name, and secure mode specified in the Build Settings. @@ -86,7 +95,11 @@ In the following sections you can see a breakdown of all the sections in the GUI - MacOS: Press Ctrl + Opt + T - Mobile (Android/iOS): Hold three fingers on the screen for one second. -- *Secure Mode (WSS)* +- *Show Native Popup Option* [Non-GPL] + + Determines whether the native popup is displayed at startup on Android, iOS, and WebGL platforms. This popup allows changing connection data through Appium or Selenium. + +- *Secure Mode (WSS)* [Non-GPL] Enables or disables secure communication between the instrumented application and the AltTester® Server. diff --git a/Docs/source/pages/alttester-with-appium.md b/Docs/source/pages/alttester-with-appium.md index d6663f58f..a40a20ed4 100644 --- a/Docs/source/pages/alttester-with-appium.md +++ b/Docs/source/pages/alttester-with-appium.md @@ -1,6 +1,15 @@ -# Running tests together with Appium +# Running tests together with Appium / Selenium -When it comes to mobile automation testing, there are many different choices for a test tool. One popular option is [Appium](http://appium.io), an open source project which enables running automated tests on both **Android** and **iOS** devices. +AltTester® Unity SDK can be used together with different automation frameworks depending on your target platform: + +- **[Appium](http://appium.io)** for mobile automation testing on **Android** and **iOS** devices +- **[Selenium](https://www.selenium.dev/)** for **WebGL-based** builds running in web browsers + +Both are open source projects that enable automated testing and can be used alongside AltTester® Unity SDK to handle platform-specific interactions and operations that AltTester® Unity SDK cannot perform directly. + +## Appium - Mobile Testing (Android & iOS) + +When it comes to mobile automation testing, [Appium](http://appium.io) is a popular choice for automating tests on both **Android** and **iOS** devices. No registration is needed and you can either download the latest version of the standalone app [here](https://github.com/appium/appium-desktop/releases/), or you can install the cli version by running: @@ -11,16 +20,16 @@ No registration is needed and you can either download the latest version of the > appium & # start appium ``` -We've created an example python project which can be found [here](https://github.com/alttester-test-examples/Python-Android-with-Appium-AltTrashCat-) which hopefully can get you started on your own projects. Using it will also automatically install the requirements needed for running the tests. More details about it [below](#alttester-unity-sdk-with-appium-example). +We've created an example Python project which can be found [here](https://github.com/alttester-test-examples/Python-Android-with-Appium-AltTrashCat-) This project demonstrates a working setup and includes the necessary dependencies. More details about it [below](#alttester-unity-sdk-with-appium-example). -## Why use Appium together with AltTester® Unity SDK +### Why use Appium together with AltTester® Unity SDK There's a couple of reasons/scenarios for which you would want to use both of these frameworks: - By itself, AltTester® Unity SDK cannot launch an app on a device. If you want to run tests in a pipeline, or by using [cloud services](./alttester-with-cloud), you can either create a script which will start your app, or you can use Appium before the tests execution; - AltTester® Unity SDK cannot perform some types of actions, such as interacting with any native popups your app might have, or putting the app in the background and resuming it. In any of these cases you can use Appium to do the things that AltTester® Unity SDK can't. -## AltTester® Unity SDK with Appium example +### AltTester® Unity SDK with Appium example After you cloned our example project, there are a couple of things you need to check before running the tests: @@ -59,3 +68,87 @@ The script will install any requirements that are missing from your machine (exc 3. The Appium driver needs to be created before the reverse port forwarding needed by AltTester® Unity SDK is done. This is because Appium clears any other reverse port forwarding when it starts. ``` + +## Selenium - WebGL Testing + +[Selenium](https://www.selenium.dev/) is a powerful automation framework for web browsers. When running AltTester® Unity SDK on WebGL builds, Selenium allows you to automate browser interactions and handle web-specific operations that complement AltTester® Unity SDK's game automation capabilities. + +### Why use Selenium together with AltTester® Unity SDK + +There are several scenarios where you would want to use Selenium with AltTester® Unity SDK for WebGL builds: + +- By itself, AltTester® Unity SDK cannot handle browser-specific operations such as opening new tabs, managing cookies, or interacting with browser dialogs; +- Selenium provides robust browser management and can handle native browser popups and dialogs that AltTester® Unity SDK cannot interact with; +- You can use Selenium to perform cross-browser testing of your WebGL builds on different browsers (Chrome, Firefox, Safari, Edge, etc.); +- Selenium allows you to automate tasks before launching your WebGL application, such as logging in on a web page or navigating to a specific URL. + +## Connection settings popup for Appium / Selenium flows + +When running AltTester® Unity SDK builds in the cloud and driving them with Appium or Selenium, you might not know in advance which app name to use from your test scripts to connect to the correct instrumented instance. To address this, AltTester® Unity SDK provides an optional native connection settings popup that can be shown in the app. + +The popup allows you to: + +- Enter the AltTester® Server host; +- Enter the AltTester® Server port; +- Enter the app name that will be used by the tests when connecting; +- Check "Don't show this again" to prevent the popup from appearing on subsequent launches. + +Because the popup is built using native UI elements, you can fully interact with it from Appium or Selenium: locate the fields and buttons using your preferred locator strategy (for example accessibility id, xpath, or text), type the desired host, port and app name values, and confirm the dialog before starting your AltTester® tests. + +Whether this popup is shown or not is controlled by a dedicated setting in AltTester® Unity SDK. Enable this setting when you want the popup to appear (for example in cloud/Appium/Selenium runs where connection details are provided dynamically), and disable it when you prefer to configure connection parameters directly in your game or test code without any additional UI. + +### Examples: identifying and interacting with the popup in Appium / Selenium + +```eval_rst + +.. tabs:: + + .. tab:: Appium + Below is a simple example that shows how you can identify and fill in the connection settings popup with Appium before starting your AltTester® tests. + + .. tabs:: + .. tab:: C# + + .. literalinclude:: ../_static/examples~/appium/csharp-appium.cs + :language: c# + + .. tab:: Java + + .. literalinclude:: ../_static/examples~/appium/java-appium.java + :language: java + + .. tab:: Python + + .. literalinclude:: ../_static/examples~/appium/python-appium.py + :language: py + + .. tab:: Robot + + .. literalinclude:: ../_static/examples~/appium/robot-appium.robot + :language: robot + + .. tab:: Selenium + Below is a simple example that shows how you can identify and fill in the connection settings popup with Selenium before starting your AltTester® tests. + + .. tabs:: + .. tab:: C# + + .. literalinclude:: ../_static/examples~/selenium/csharp-selenium.cs + :language: c# + + .. tab:: Java + + .. literalinclude:: ../_static/examples~/selenium/java-selenium.java + :language: java + + .. tab:: Python + + .. literalinclude:: ../_static/examples~/selenium/python-selenium.py + :language: py + + .. tab:: Robot + + .. literalinclude:: ../_static/examples~/selenium/robot-selenium.robot + :language: robot + +``` diff --git a/Docs/source/pages/alttester-with-cloud.md b/Docs/source/pages/alttester-with-cloud.md index 185c69eb5..7d7dfbcaa 100644 --- a/Docs/source/pages/alttester-with-cloud.md +++ b/Docs/source/pages/alttester-with-cloud.md @@ -92,7 +92,7 @@ set BROWSERSTACK_APP_ID_SDK_201="yourAppId" In your code project, you need to install a Selenium WebDriver extension for Appium and C# Bindings for BrowserStack Local. Example: ``` -dotnet add package Appium.WebDriver --version 4.4.0 +dotnet add package Appium.WebDriver --version 8.2.0 dotnet add package BrowserStackLocal --version 2.3.0 ``` @@ -128,11 +128,11 @@ In this file add code that will: browserstackOptions.Add("local", "true"); browserstackOptions.Add("userName", BROWSERSTACK_USERNAME); browserstackOptions.Add("accessKey", BROWSERSTACK_ACCESS_KEY); - capabilities.AddAdditionalCapability("bstack:options", browserstackOptions); - capabilities.AddAdditionalCapability("platformName", "android"); - capabilities.AddAdditionalCapability("platformVersion", "11.0"); - capabilities.AddAdditionalCapability("appium:deviceName", "Samsung Galaxy S21"); - capabilities.AddAdditionalCapability("appium:app", BROWSERSTACK_APP_ID_SDK_201); + capabilities.AddAdditionalAppiumOption("bstack:options", browserstackOptions); + capabilities.PlatformName = "android"; + capabilities.AddAdditionalAppiumOption("platformVersion", "11.0"); + capabilities.DeviceName = "Samsung Galaxy S21"; + capabilities.App = BROWSERSTACK_APP_ID_SDK_201; .. tab:: iOS @@ -147,11 +147,11 @@ In this file add code that will: browserstackOptions.Add("local", "true"); browserstackOptions.Add("userName", BROWSERSTACK_USERNAME); browserstackOptions.Add("accessKey", BROWSERSTACK_ACCESS_KEY); - capabilities.AddAdditionalCapability("bstack:options", browserstackOptions); - capabilities.AddAdditionalCapability("platformName", "ios"); - capabilities.AddAdditionalCapability("platformVersion", "16"); - capabilities.AddAdditionalCapability("appium:deviceName", "iPhone 14"); - capabilities.AddAdditionalCapability("appium:app", BROWSERSTACK_APP_ID_SDK_201); + capabilities.AddAdditionalAppiumOption("bstack:options", browserstackOptions); + capabilities.PlatformName = "ios"; + capabilities.AddAdditionalAppiumOption("platformVersion", "16"); + capabilities.DeviceName = "iPhone 14"; + capabilities.App = BROWSERSTACK_APP_ID_SDK_201; ``` - configure the local testing connection @@ -176,13 +176,13 @@ In this file add code that will: .. code-block:: C# - appiumDriver = new AndroidDriver(new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capabilities); + appiumDriver = new AndroidDriver(new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capabilities); .. tab:: iOS .. code-block:: C# - appiumDriver = new IOSDriver(new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capabilities); + appiumDriver = new IOSDriver(new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capabilities); ``` - initialize AltDriver @@ -352,11 +352,11 @@ In this file add code that will: browserstackOptions.Add("local", "true"); browserstackOptions.Add("userName", BROWSERSTACK_USERNAME); browserstackOptions.Add("accessKey", BROWSERSTACK_ACCESS_KEY); - capabilities.AddAdditionalCapability("bstack:options", browserstackOptions); - capabilities.AddAdditionalCapability("platformName", "android"); - capabilities.AddAdditionalCapability("platformVersion", "11.0"); - capabilities.AddAdditionalCapability("appium:deviceName", "Samsung Galaxy S21"); - capabilities.AddAdditionalCapability("appium:app", BROWSERSTACK_APP_ID_SDK_201); + capabilities.AddAdditionalAppiumOption("bstack:options", browserstackOptions); + capabilities.PlatformName = "android"; + capabilities.AddAdditionalAppiumOption("platformVersion", "11.0"); + capabilities.DeviceName = "Samsung Galaxy S21"; + capabilities.App = BROWSERSTACK_APP_ID_SDK_201; .. tab:: iOS @@ -371,11 +371,11 @@ In this file add code that will: browserstackOptions.Add("local", "true"); browserstackOptions.Add("userName", BROWSERSTACK_USERNAME); browserstackOptions.Add("accessKey", BROWSERSTACK_ACCESS_KEY); - capabilities.AddAdditionalCapability("bstack:options", browserstackOptions); - capabilities.AddAdditionalCapability("platformName", "ios"); - capabilities.AddAdditionalCapability("platformVersion", "16"); - capabilities.AddAdditionalCapability("appium:deviceName", "iPhone 14"); - capabilities.AddAdditionalCapability("appium:app", BROWSERSTACK_APP_ID_SDK_201); + capabilities.AddAdditionalAppiumOption("bstack:options", browserstackOptions); + capabilities.PlatformName = "ios"; + capabilities.AddAdditionalAppiumOption("platformVersion", "16"); + capabilities.DeviceName = "iPhone 14"; + capabilities.App = BROWSERSTACK_APP_ID_SDK_201; ``` @@ -400,13 +400,13 @@ In this file add code that will: .. code-block:: C# - appiumDriver = new AndroidDriver(new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capabilities); + appiumDriver = new AndroidDriver(new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capabilities); .. tab:: iOS .. code-block:: C# - appiumDriver = new IOSDriver(new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capabilities); + appiumDriver = new IOSDriver(new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capabilities); ``` @@ -517,15 +517,145 @@ SauceLabs provides **automated testing solutions** for web and mobile applicatio You can create a free trial SauceLabs account where you get 2000 credits per week (which is enough to run some test suites multiple times on their free devices and emulators). -One of the [architectural changes from v2.0.0](https://alttester.com/alttester-desktop-2-0-0-alttester-unity-sdk-2-0-0-recorder-support-for-webgl-and-architectural-changes/) is that the AltTester® Server module is incorporated in AltTester® Desktop. In order to be able to execute tests, we need to have an **AltTester® Desktop app running and publicly reachable**/accessible so that the AltDriver that is instantiated in the tests and **the instrumented app can connect to the AltTester® Server**. +One of the [architectural changes from v2.0.0](https://alttester.com/alttester-desktop-2-0-0-alttester-unity-sdk-2-0-0-recorder-support-for-webgl-and-architectural-changes/) is that the AltTester® Server module is incorporated in AltTester® Desktop. In order to be able to execute tests, both the AltDriver instantiated in the tests and the instrumented app need to connect to the **AltTester® Server**. -### SauceLabs C# project example +There are two ways to set up this connection between your tests, the AltTester® Server and the Sauce Labs cloud device: + +- **Sauce Connect Proxy tunnel (recommended)** — run AltTester® Desktop locally and let the Sauce Connect tunnel forward the cloud device's `localhost` back to your machine. No public VM is required and the build keeps the default AltTester® connection settings. +- **AltTester® Desktop on a public VM** — host AltTester® Desktop on a publicly reachable virtual machine that the cloud device connects to directly. + +### SauceLabs C# project example using Sauce Connect Proxy (recommended) You can download our example project from [here](https://github.com/alttester/EXAMPLES-CSharp-Cloud-Services-AltTrashCat/tree/saucelabs_example). Also, for more details check [this article](https://alttester.com/sauce-labs-integration-execute-alttester-based-c-tests/) from our Blog. - -At the moment of creating this section of the documentation for the case of having the AltTester® Desktop app running on the same machine where the tests are running the instrumented app was not able to connect to localhost successfully, due to the fact that the -[Sauce Connect Tunnel Proxy](https://docs.saucelabs.com/secure-connections/sauce-connect/setup-configuration/basic-setup/) implementation was not yet compatible with the WebSocket used in AltTester® Server. But more recently, SauceLabs confirmed that WebSocket communication is now working for tunnel connections between tests and cloud devices. For this reason, we are now working on running the tests using **Sauce Connect Tunnel Proxy** and we will provide setup instructions shortly. +With this setup you run **AltTester® Desktop locally** and use [Sauce Connect Proxy](https://docs.saucelabs.com/secure-connections/sauce-connect-5/) to bridge the cloud device to your machine. You do **not** need a public virtual machine and you do **not** need to rebuild your app with a specific IP — the build keeps the default AltTester® connection settings (host `127.0.0.1`, port `13000`). + +This works because Sauce Connect is started with the `--proxy-localhost allow` flag, which lets the instrumented app on the cloud device reach `localhost:13000` on your machine through the tunnel. Both the instrumented app and the `AltDriver` in your tests then connect to the same AltTester® Server. + +```eval_rst +.. note:: + The ``--proxy-localhost allow`` flag is essential. Without it the cloud device cannot reach the AltTester® Server running on your machine and the driver will not connect. +``` + +#### **Prerequisites** + +- An active SauceLabs account +- [Sauce Connect Proxy](https://docs.saucelabs.com/secure-connections/sauce-connect-5/installation/) installed and available in your `PATH` (the `sc` command) +- **AltTester® Desktop** installed and running locally, with the AltTester® Server listening on port `13000` +- A set of C# tests that use AltTester® Unity SDK +- A build instrumented with AltTester® Unity SDK using the **default** connection settings (host `127.0.0.1`, port `13000`) +- .NET and the `Appium.WebDriver` NuGet package + +#### **Steps for running tests on Android and iOS** + +**1. Upload the instrumented build on SauceLabs** + +Upload your instrumented `.apk` / `.ipa` to [Sauce App Storage](https://app.eu-central-1.saucelabs.com/app-management). Note the file name — you will reference it in the `appium:app` capability as `storage:filename=`. + +**2. Set your SauceLabs credentials as environment variables** + +``` +export SAUCE_USERNAME="yourUsername" +export SAUCE_ACCESS_KEY="yourAccessKey" +export SAUCE_APP_URL="storage:filename=" +export SAUCE_REGION="eu-central-1" +``` + +**3. Start the Sauce Connect tunnel with `--proxy-localhost allow`** + +``` +sc run --username $SAUCE_USERNAME --access-key $SAUCE_ACCESS_KEY --region $SAUCE_REGION --tunnel-name alttester-tunnel --proxy-localhost allow +``` + +You can also start and stop the tunnel from your test code — see the `StartTunnel` method in the example project's [BaseTest.cs](https://github.com/alttester/EXAMPLES-CSharp-Cloud-Services-AltTrashCat/blob/saucelabs_example/tests/BaseTest.cs). + +**4. Configure Appium capabilities and Sauce Labs options** + +Route the session through your tunnel by passing the tunnel name in `sauce:options`: + +```eval_rst +.. tabs:: + + .. tab:: Android + + .. code-block:: C# + + AppiumOptions capabilities = new AppiumOptions(); + capabilities.PlatformName = "Android"; + capabilities.App = SAUCE_APP_URL; + capabilities.DeviceName = "Google Pixel.*"; + capabilities.AutomationName = "UiAutomator2"; + + var sauceOptions = new Dictionary(); + sauceOptions.Add("username", SAUCE_USERNAME); + sauceOptions.Add("accessKey", SAUCE_ACCESS_KEY); + sauceOptions.Add("tunnelIdentifier", "alttester-tunnel"); + sauceOptions.Add("tunnelOwner", SAUCE_USERNAME); + sauceOptions.Add("appiumVersion", "latest"); + capabilities.AddAdditionalAppiumOption("sauce:options", sauceOptions); + + .. tab:: iOS + + .. code-block:: C# + + AppiumOptions capabilities = new AppiumOptions(); + capabilities.PlatformName = "iOS"; + capabilities.App = SAUCE_APP_URL; + capabilities.DeviceName = "iPhone 1[5-9].*"; + capabilities.PlatformVersion = "18"; + capabilities.AutomationName = "XCUITest"; + + var sauceOptions = new Dictionary(); + sauceOptions.Add("username", SAUCE_USERNAME); + sauceOptions.Add("accessKey", SAUCE_ACCESS_KEY); + sauceOptions.Add("tunnelIdentifier", "alttester-tunnel"); + sauceOptions.Add("tunnelOwner", SAUCE_USERNAME); + sauceOptions.Add("appiumVersion", "latest"); + capabilities.AddAdditionalAppiumOption("sauce:options", sauceOptions); +``` + +**5. Start the Appium driver** + +Point the driver at the Sauce Labs hub for your region: + +```eval_rst +.. tabs:: + + .. tab:: Android + + .. code-block:: C# + + appiumDriver = new AndroidDriver(new Uri($"https://ondemand.{SAUCE_REGION}.saucelabs.com:443/wd/hub"), capabilities); + + .. tab:: iOS + + .. code-block:: C# + + appiumDriver = new IOSDriver(new Uri($"https://ondemand.{SAUCE_REGION}.saucelabs.com:443/wd/hub"), capabilities); +``` + +**6. Connect the AltDriver** + +Because the tunnel forwards localhost, the `AltDriver` connects with its **default** host and port — no custom IP needed: + +```c# +altDriver = new AltDriver(); +``` + +```eval_rst +.. note:: + On a freshly installed build the app needs a few seconds to launch and register with the AltTester® Server before the driver can attach. If you get a ``NoAppConnectedException``, increase the connect timeout (for example ``new AltDriver(connectTimeout: 10)``) or retry the connection in a loop until the app connects. +``` + +**7. Run the tests** + +Make sure AltTester® Desktop is running locally and the tunnel is up, then run: + +``` +dotnet test +``` + +### SauceLabs C# project example using AltTester® Desktop on a public VM In this example, the AltTester® Desktop app is running on a **public virtual machine**, which **can be accessed by the instrumented app** installed on a device in the cloud. @@ -582,7 +712,7 @@ Before running any tests, you are required to [upload the build to the designate - install Appium WebDriver ``` - dotnet add package Appium.WebDriver --version 4.4.0 + dotnet add package Appium.WebDriver --version 8.2.0 ``` **3. Set your SauceLabs credentials as environment variables** @@ -615,14 +745,14 @@ In this file add code that will: .. code-block:: C# AppiumOptions options = new AppiumOptions(); - options.AddAdditionalCapability("platformName", "Android"); - options.AddAdditionalCapability("appium:app","storage:filename="); + options.PlatformName = "Android"; + options.App = "storage:filename="; - options.AddAdditionalCapability("appium:deviceName", "Samsung Galaxy S10 WQHD GoogleAPI Emulator"); + options.DeviceName = "Samsung Galaxy S10 WQHD GoogleAPI Emulator"; - options.AddAdditionalCapability("appium:platformVersion", "11.0"); - options.AddAdditionalCapability("appium:deviceOrientation", "portrait"); - options.AddAdditionalCapability("appium:automationName", "UiAutomator2"); + options.PlatformVersion = "11.0"; + options.AddAdditionalAppiumOption("appium:deviceOrientation", "portrait"); + options.AutomationName = "UiAutomator2"; var sauceOptions = new Dictionary(); sauceOptions.Add("appiumVersion", "2.0.0"); @@ -630,7 +760,7 @@ In this file add code that will: sauceOptions.Add("accessKey", SAUCE_ACCESS_KEY); sauceOptions.Add("build", ""); sauceOptions.Add("name", "Test " + DateTime.Now.ToString("dd.MM - HH:mm")); - options.AddAdditionalCapability("sauce:options", sauceOptions); + options.AddAdditionalAppiumOption("sauce:options", sauceOptions); .. tab:: iOS @@ -639,17 +769,17 @@ In this file add code that will: AppiumOptions options = new AppiumOptions(); - options.AddAdditionalCapability("platformName", "iOS"); - options.AddAdditionalCapability("appium:app", "storage:filename="); + options.PlatformName = "iOS"; + options.App = "storage:filename="; - options.AddAdditionalCapability("appium:deviceName", "iPhone XR"); + options.DeviceName = "iPhone XR"; - options.AddAdditionalCapability("appium:platformVersion", "16"); + options.PlatformVersion = "16"; - options.AddAdditionalCapability("appium:deviceOrientation", "portrait"); + options.AddAdditionalAppiumOption("appium:deviceOrientation", "portrait"); - options.AddAdditionalCapability("appium:automationName", "XCUITest"); + options.AutomationName = "XCUITest"; var sauceOptions = new Dictionary(); sauceOptions.Add("appiumVersion", "2.0.0"); @@ -657,7 +787,7 @@ In this file add code that will: sauceOptions.Add("accessKey", SAUCE_ACCESS_KEY); sauceOptions.Add("build", ""); sauceOptions.Add("name", "Test " + DateTime.Now.ToString("dd.MM - HH:mm")); - options.AddAdditionalCapability("sauce:options", sauceOptions); + options.AddAdditionalAppiumOption("sauce:options", sauceOptions); ``` @@ -672,13 +802,13 @@ In this file add code that will: .. code-block:: C# - appiumDriver = new AndroidDriver(new Uri("https://ondemand.eu-central-1.saucelabs.com:443/wd/hub"), options); + appiumDriver = new AndroidDriver(new Uri("https://ondemand.eu-central-1.saucelabs.com:443/wd/hub"), options); .. tab:: iOS .. code-block:: C# - appiumDriver = new IOSDriver(new Uri("https://ondemand.eu-central-1.saucelabs.com:443/wd/hub"), options); + appiumDriver = new IOSDriver(new Uri("https://ondemand.eu-central-1.saucelabs.com:443/wd/hub"), options); ``` @@ -701,7 +831,7 @@ In this file add code that will: ``` - add method to keep Appium alive - - in this context, Appium is only used to install the application and access it on the BrowserStack test device - after that, AltTester® SDK picks up the connection and carries out the tests + - in this context, Appium is only used to install the application and access it on the Sauce Labs test device - after that, AltTester® SDK picks up the connection and carries out the tests - you should add an action that keeps Appium alive in the `TearDown` method of the framework to ensure that Appium is used after every test. Here is an example: ```eval_rst @@ -899,7 +1029,7 @@ Check [this article](https://alttester.com/running-c-tests-with-alttester-on-aws ``` - install necessary packages - run the following commands in your project`s terminal: ```c# - dotnet add package Appium.WebDriver --version 4.4.0 + dotnet add package Appium.WebDriver --version 8.2.0 dotnet add package Selenium.WebDriver --version 3.141.0 ``` - add Namespaces specific to Appium @@ -918,13 +1048,13 @@ Check [this article](https://alttester.com/running-c-tests-with-alttester-on-aws .. code-block:: C# - AndroidDriver appiumDriver; + AndroidDriver appiumDriver; .. tab:: iOS .. code-block:: C# - IOSDriver appiumDriver; + IOSDriver appiumDriver; ``` - define Appium Capabilities ```eval_rst @@ -934,18 +1064,18 @@ Check [this article](https://alttester.com/running-c-tests-with-alttester-on-aws .. code-block:: C# - capabilities.AddAdditionalCapability("device", "Android"); - capabilities.AddAdditionalCapability("platformName", "Android"); - capabilities.AddAdditionalCapability("appActivity", "com.unity3d.player.UnityPlayerActivity"); + capabilities.AddAdditionalAppiumOption("device", "Android"); + capabilities.PlatformName = "Android"; + capabilities.AddAdditionalAppiumOption("appActivity", "com.unity3d.player.UnityPlayerActivity"); .. tab:: iOS .. code-block:: C# - capabilities.AddAdditionalCapability("device", "iOS"); - capabilities.AddAdditionalCapability("platformName", "iOS"); - capabilities.AddAdditionalCapability("appPackage", "fi.altom.trashcat"); - capabilities.AddAdditionalCapability("autoAcceptAlerts" ,true); + capabilities.AddAdditionalAppiumOption("device", "iOS"); + capabilities.PlatformName = "iOS"; + capabilities.AddAdditionalAppiumOption("appPackage", "fi.altom.trashcat"); + capabilities.AddAdditionalAppiumOption("autoAcceptAlerts" ,true); ``` - driver initialization and wait ```eval_rst @@ -959,7 +1089,7 @@ Check [this article](https://alttester.com/running-c-tests-with-alttester-on-aws .. code-block:: C# - appiumDriver = new AndroidDriver(appiumUri, capabilities, TimeSpan.FromSeconds(300)); + appiumDriver = new AndroidDriver(appiumUri, capabilities, TimeSpan.FromSeconds(300)); .. tab:: iOS @@ -969,7 +1099,7 @@ Check [this article](https://alttester.com/running-c-tests-with-alttester-on-aws .. code-block:: C# - appiumDriver = new IOSDriver(appiumUri, capabilities, TimeSpan.FromSeconds(300)); + appiumDriver = new IOSDriver(appiumUri, capabilities, TimeSpan.FromSeconds(300)); ``` - cleanup - the `DisposeAppium()` teardown method is called after the tests are complete. It quits the Appium driver - if using the **remote connection** in order to connect to AltTester® Desktop, don`t forget to add the IP/URL of the remote VM when defining AltDriver: @@ -1006,7 +1136,7 @@ Keep in mind that the setup is different for Android and iOS. - install necessary packages for running the C# tests ``` - dotnet add package NUnit --version 3.13.3 - - dotnet add package AltTester-Driver -- version 2.2.6 + - dotnet add package AltTester-Driver --version 2.3.2 - dotnet add package Selenium.WebDriver -- version 3.141.0 - dotnet add package NUnit3TestAdapter --version 4.4.2 ``` @@ -1230,7 +1360,7 @@ Based on your option to connect to AltTester® Desktop you need to set the AltTe - we need the Selenium Webdriver extension for Appium to establish a connection between our test script and the target mobile application - the other package, JunitXml.TestLogger is required to have test results generated and parsed nicely in BitBar’s UI. ``` - dotnet add package Appium.WebDriver --version 4.3.1 + dotnet add package Appium.WebDriver --version 8.2.0 dotnet add package JunitXml.TestLogger --version 3.0.134 ``` - after installing the packages, you can see them in `.csproj` (check the [example repository](https://github.com/alttester/EXAMPLES-CSharp-BitBar-AltTrashCat/blob/server-side-android-localhost/TestAlttrashCSharp.csproj)) @@ -1269,20 +1399,20 @@ Based on your option to connect to AltTester® Desktop you need to set the AltTe .. code-block:: C# - public AndroidDriver appiumDriver; + public AndroidDriver appiumDriver; .. code-block:: C# string appPath = System.Environment.CurrentDirectory + "/../../../application.apk"; - capabilities.AddAdditionalCapability("appium:app", appPath); - capabilities.AddAdditionalCapability("appium:deviceName", "Android Phone"); - capabilities.AddAdditionalCapability("platformName", "Android"); - capabilities.AddAdditionalCapability("automationName", "UIAutomator2"); - capabilities.AddAdditionalCapability("newCommandTimeout", 2000); + capabilities.App = appPath; + capabilities.DeviceName = "Android Phone"; + capabilities.PlatformName = "Android"; + capabilities.AddAdditionalAppiumOption("automationName", "UIAutomator2"); + capabilities.AddAdditionalAppiumOption("newCommandTimeout", 2000); .. code-block:: C# - appiumDriver = new AndroidDriver(new Uri("http://localhost:4723/wd/hub"), capabilities, TimeSpan.FromSeconds(36000)); + appiumDriver = new AndroidDriver(new Uri("http://localhost:4723/wd/hub"), capabilities, TimeSpan.FromSeconds(36000)); .. tab:: iOS @@ -1292,21 +1422,21 @@ Based on your option to connect to AltTester® Desktop you need to set the AltTe .. code-block:: C# - public IOSDriver appiumDriver; + public IOSDriver appiumDriver; .. code-block:: C# - capabilities.AddAdditionalCapability("appium:deviceName", "Apple iPhone SE 2020 A2296 13.4.1"); - capabilities.AddAdditionalCapability("platformName", "iOS"); - capabilities.AddAdditionalCapability("appium:automationName", "XCUITest"); - capabilities.AddAdditionalCapability("appium:bundleId", "fi.altom.trashcat"); - capabilities.AddAdditionalCapability("platformVersion", "13.4"); - capabilities.AddAdditionalCapability("autoAcceptAlerts","true"); - capabilities.AddAdditionalCapability("newCommandTimeout", 2000); + capabilities.DeviceName = "Apple iPhone SE 2020 A2296 13.4.1"; + capabilities.PlatformName = "iOS"; + capabilities.AutomationName = "XCUITest"; + capabilities.AddAdditionalAppiumOption("appium:bundleId", "fi.altom.trashcat"); + capabilities.AddAdditionalAppiumOption("platformVersion", "13.4"); + capabilities.AddAdditionalAppiumOption("autoAcceptAlerts","true"); + capabilities.AddAdditionalAppiumOption("newCommandTimeout", 2000); .. code-block:: C# - appiumDriver = new IOSDriver(new Uri("http://localhost:4723/wd/hub"), capabilities, TimeSpan.FromSeconds(36000)); + appiumDriver = new IOSDriver(new Uri("http://localhost:4723/wd/hub"), capabilities, TimeSpan.FromSeconds(36000)); ``` - initialize AltDriver: @@ -1454,8 +1584,8 @@ After you finish setting up the build, you need to use the **Archive** option to - we need the Selenium Webdriver extension for Appium to establish a connection between our test script and the target mobile application - in case you have not done it so far, add the AltTester-Driver package as well ```c# - dotnet add package Appium.WebDriver --version 4.3.1 - dotnet add package AltTester-Driver --version 2.2.6 + dotnet add package Appium.WebDriver --version 8.2.0 + dotnet add package AltTester-Driver --version 2.3.2 ``` - after installing the packages, you can see them in `.csproj` (check the [example repository](https://github.com/alttester/EXAMPLES-CSharp-BitBar-AltTrashCat/blob/client-side-ios/TestAlttrashCSharp.csproj)) @@ -1505,25 +1635,25 @@ After you finish setting up the build, you need to use the **Archive** option to .. code-block:: C# - public AndroidDriver appiumDriver; + public AndroidDriver appiumDriver; .. code-block:: C# - capabilities.AddAdditionalCapability("platformName", "Android"); - capabilities.AddAdditionalCapability("appium:deviceName", "Android"); - capabilities.AddAdditionalCapability("automationName", "UIAutomator2"); - capabilities.AddAdditionalCapability("newCommandTimeout", 2000); + capabilities.PlatformName = "Android"; + capabilities.DeviceName = "Android"; + capabilities.AddAdditionalAppiumOption("automationName", "UIAutomator2"); + capabilities.AddAdditionalAppiumOption("newCommandTimeout", 2000); .. code-block:: C# - capabilities.AddAdditionalCapability("bitbar_apiKey", BITBAR_APIKEY); - capabilities.AddAdditionalCapability("bitbar_project", "client-side: AltTester® Server on custom host; Android"); - capabilities.AddAdditionalCapability("bitbar_testrun", "Start Page Tests on Samsung"); - capabilities.AddAdditionalCapability("bitbar_app", BITBAR_APP_ID_SDK_202); + capabilities.AddAdditionalAppiumOption("bitbar_apiKey", BITBAR_APIKEY); + capabilities.AddAdditionalAppiumOption("bitbar_project", "client-side: AltTester® Server on custom host; Android"); + capabilities.AddAdditionalAppiumOption("bitbar_testrun", "Start Page Tests on Samsung"); + capabilities.AddAdditionalAppiumOption("bitbar_app", BITBAR_APP_ID_SDK_202); .. code-block:: C# - appiumDriver = new AndroidDriver(new Uri("http://localhost:4723/wd/hub"), capabilities, TimeSpan.FromSeconds(36000)); + appiumDriver = new AndroidDriver(new Uri("http://localhost:4723/wd/hub"), capabilities, TimeSpan.FromSeconds(36000)); .. tab:: iOS @@ -1533,25 +1663,25 @@ After you finish setting up the build, you need to use the **Archive** option to .. code-block:: C# - public IOSDriver appiumDriver; + public IOSDriver appiumDriver; .. code-block:: C# - capabilities.AddAdditionalCapability("platformName", "iOS"); - capabilities.AddAdditionalCapability("appium:deviceName", "Apple iPhone SE 2020 A2296 13.4.1"); - capabilities.AddAdditionalCapability("appium:automationName", "XCUITest"); - capabilities.AddAdditionalCapability("appium:bundleId", "fi.altom.trashcat"); + capabilities.PlatformName = "iOS"; + capabilities.DeviceName = "Apple iPhone SE 2020 A2296 13.4.1"; + capabilities.AutomationName = "XCUITest"; + capabilities.AddAdditionalAppiumOption("appium:bundleId", "fi.altom.trashcat"); .. code-block:: C# - capabilities.AddAdditionalCapability("bitbar_apiKey", BITBAR_APIKEY); - capabilities.AddAdditionalCapability("bitbar_project", "client-side: AltTester® Server on custom host; iOS"); - capabilities.AddAdditionalCapability("bitbar_testrun", "Start Page Tests on Apple iPhone SE 2020 A2296 13.4.1"); - capabilities.AddAdditionalCapability("bitbar_app", BITBAR_APP_ID_SDK_202_IPA); + capabilities.AddAdditionalAppiumOption("bitbar_apiKey", BITBAR_APIKEY); + capabilities.AddAdditionalAppiumOption("bitbar_project", "client-side: AltTester® Server on custom host; iOS"); + capabilities.AddAdditionalAppiumOption("bitbar_testrun", "Start Page Tests on Apple iPhone SE 2020 A2296 13.4.1"); + capabilities.AddAdditionalAppiumOption("bitbar_app", BITBAR_APP_ID_SDK_202_IPA); .. code-block:: C# - appiumDriver = new IOSDriver(new Uri(""http://localhost:4723/wd/hub""), capabilities) + appiumDriver = new IOSDriver(new Uri(""http://localhost:4723/wd/hub""), capabilities) ``` ```eval_rst diff --git a/Docs/source/pages/examples.md b/Docs/source/pages/examples.md index 7536790cc..b0e752cdf 100644 --- a/Docs/source/pages/examples.md +++ b/Docs/source/pages/examples.md @@ -42,7 +42,7 @@ We plan to add more examples in the near future. * C# tests [LeanTouch](https://github.com/alttester/EXAMPLES-NewInputSystem--LeanTouch-CSharp) * C# tests [RollABall](https://github.com/alttester/EXAMPLES-NewInputSystem--RollABall-CSharp) -**4.** Example test projects for AltTester® Unity SDK for a project that uses UIToolkit: +**4.** Example test projects for AltTester® Unity SDK for a project that uses UIToolkit [Non-GPL]: * C# tests [DragonCrasher](https://github.com/alttester/Example-CSharp-Standalone-DragonCrasher): This project demonstrates how to write and run automated tests using AltTester® in a Unity project that utilizes UI Toolkit. It includes pre-written tests that interact with Unity UI elements and validate behaviors. Follow the provided setup instructions to build the project and execute the tests. diff --git a/Docs/source/pages/known-issues.rst b/Docs/source/pages/known-issues.rst index b2ad08598..7dca8cc6c 100644 --- a/Docs/source/pages/known-issues.rst +++ b/Docs/source/pages/known-issues.rst @@ -30,6 +30,15 @@ resolution until this issue is fixed. **Affects**: AltUnity Tester v1.7.* and AltTester® Unity SDK v1.8.* with .NET 6 +Fatal error: Cannot access a disposed object 'System.Net.Sockets.NetworkStream' +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Problem**: While running tests, the app unexpectedly disconnects from AltTester® Server and a ``[Fatal] Cannot access a disposed object. Object name: 'System.Net.Sockets.NetworkStream'.`` error is logged. This happens due to a race condition when the server attempts to send data to a client that has recently disconnected, often triggered by a "reconnection storm" from older versions of the C# Bindings. + +**Workaround**: Update your C# Bindings to version 2.3.1 or higher. This version includes a fix that stabilizes the connection and prevents the reconnection loops that trigger this error. + +**Affects**: AltTester® Unity SDK v2.3.1 (when used with C# Bindings < 2.3.1) + New Input System ---------------- @@ -143,8 +152,8 @@ In BrowserStack can't connect iOS devices with version greater than 16 to AltTes **Affects**: AltTester® Unity SDK v2.x -UI Toolkit ----------- +UI Toolkit [Non-GPL] +-------------------- Input actions become unresponsive after using modifier keys and shifting application focus. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~