expecco Wiki (Version 25.x) - Benutzerbeiträge [de]

Release Notes 24.x

2025-02-18T15:56:43Z

Matilk: /* Future Release 24.2 (February 2025) */

See also: [[Release Notes 23.x]]
 

== Future Release 24.2 (February 2025) ==
*Feature: WindowsAutomation: "Mouse Wheel Simulation" support
*Feature: support for "Any" and template typed parameters in testcase (of testplan)
*Feature: negated [[Testplan_Editor/en#Condition_Variables|condition variable]] check
*Feature: edit lock when loading a suite from AIDYMO
*Feature: menu entries to save attachments to disk
*Feature: support for an external XML editor in Settings->External Tools and Attachment
*Feature: [[Testsuite_Editor-Metadata_Editor/en#Include_Flat|flat vs. hierarchical imported menu actions]]
*Feature: The Mobile Testing Plugin has been migrated to use Appium 2, while Appium 1 is still supported. There is a new version of the [[Mobile_Testing_Plugin#Windows|Mobile Testing Supplement]] with Appium 2.
*Fix/Feature: severity level limit is passed on in sub-test plans with the option of tightening the severity level per test plan level
*Fix: Project Difference Viewer showed wrong tab for steps inside the test/demo diagram
*Fix: exchange connection function of diagram editor left an invisible connection at the pin. Lead to wrong output value forwarding during the current session, but cured itself when saving and reloading.
*Fix: inconsistent behavior of the Smalltalk "angle" message fixed; now returns degrees from both Complex and Point instances. To get radians, use the "theta" message. This change only affects any elementary action which calls that method.
*Improvement: function and operation of variable pins ([[Scheme_Editor/en#Variable_Number_of_Pins|Scheme_Editor/Variable_Number_of_Pins]])
*Improvement: change modification date of the project when shrinkwrapping an imported library
*Improvement: less memory allocation during ELF generation
*Improvement: more info in tooltips in browser's "Errors", "Style" and "Special" tabs
*Improvement: stability of websocket connections to AIDYMO/web
*Improvement: Datatypes: Differently named user types on the same primary type or Any can now be defined and stored in a project, but possibly loosing information when loading in older expecco versions. Reimporting a changed datatype definition doesn't rely the name primarily.

== Release 24.1 (2Q 2024) ==
*Feature: [[Expecco_API/en#Global_and_Static_Variables|Static Variables for Python]]
*Feature: Qt-Testing: Logging with log levels <code>DEBUG</code>, <code>INFO</code> and <code>WARN</code> ([[Qt_Inject_Windows/en#Logging|Qt-Logging]])
*Feature: Qt-Testing: Qt-Connections now use the ConnectionManager like the other Gui test technologies
*Feature: WindowsAutomation: Native Touch, Tap, Drag & Drop support now in the base WindowsAutomation Library
*Feature: Show Log and [[Timeline/en|Timeline view]] for testplans
*Feature: Search and Goto Line menu functions in the activity log view
*Feature: [[Embedded Systems C Bridge API|C-Bridge]] now supports SSL connections (encryption and authentication using certificates)
*Feature: [[Testsuite_Editor-ExecutionSettings_Editor/en|Settings for execution]] (thread pool and log activities/pins/info) can now be saved in the test suite settings
*Feature: CSV test report, values for start time, end time and duration added
*Feature: Improved refactoring for compound blocks: "Extract (& Replace) New Compound Action"
*Feature: Enhanced expecco reflection library
*Feature: Logprocessors can be executed for embedded testplans
*Feature: Logging of background actions can be individually enabled and disabled for testplans and nested testplans
*Feature: Support for script actions written in the [[Installing_additional_Frameworks/en#Julia_Installation|Julia]] programming language
*Feature: Powershell actions: support functions for writing to pins, logging, opening dialogs, etc.
*Fix: Current temporary testplan settings (like selected testcases, do-not-execute of pre/post action, etc.) don't get lost anymore when reimporting a library
*Fix: WindowsAutomation: Fix blocking of applications after <Mouse Button Down>
*Fix: asynchronous write to an output pin with no wait() in bridged actions are now detected and reported as error (see Example3 in the [[Expecco_API/en#Asynchronous_and_Callback_Functions|NodeJS API Documentation]])
*Fix: Bridges: Detect (and ignore) invalid requests from forked background bridge threads
*Fix: Acitivity logs of asynchronous events in background actions are now displayed correctly in the background activity log.
*Fix: Qt: Drag and drop improved by revising the "Move mouse event" (Windows)
*Fix: Disabling logs of sub-activities (if successful, if not successful, etc.)

Release Notes 24.x

2025-02-17T09:53:54Z

Matilk: /* Future Release 24.2 (February 2025) */ Appium 2 support

See also: [[Release Notes 23.x]]
 

== Future Release 24.2 (February 2025) ==
*Feature: WindowsAutomation: "Mouse Wheel Simulation" support
*Feature: support for "Any" and template typed parameters in testcase (of testplan)
*Feature: negated [[Testplan_Editor/en#Condition_Variables|condition variable]] check
*Feature: edit lock when loading a suite from AIDYMO
*Feature: menu entries to save attachments to disk
*Feature: support for an external XML editor in Settings->External Tools and Attachment
*Feature: [[Testsuite_Editor-Metadata_Editor/en#Include_Flat|flat vs. hierarchical imported menu actions]]
*Feature: The Mobile Testing Plugin has been migrated to use Appium 2, while Appium 1 is still supported. There is a new version of the [[Mobile_Testing_Plugin#Windows|Mobile Testing Supplement]] with Appium 2.
*Fix/Feature: severity level limit is passed on in sub-test plans with the option of tightening the severity level per test plan level
*Fix: Project Difference Viewer showed wrong tab for steps inside the test/demo diagram
*Fix: exchange connection function of diagram editor left an invisible connection at the pin. Lead to wrong output value forwarding during the current session, but cured itself when saving and reloading.
*Fix: inconsistent behavior of the Smalltalk "angle" message fixed; now returns degrees from both Complex and Point instances. To get radians, use the "theta" message. This change only affects any elementary action which calls that method.
*Improvement: function and operation of variable pins ([[Scheme_Editor/en#Variable_Number_of_Pins|Scheme_Editor/Variable_Number_of_Pins]])
*Improvement: change modification date of the project when shrinkwrapping an imported library
*Improvement: less memory allocation during ELF generation
*Improvement: more info in tooltips in browser's "Errors", "Style" and "Special" tabs
*Improvement: stability of websocket connections to AIDYMO/web

== Release 24.1 (2Q 2024) ==
*Feature: [[Expecco_API/en#Global_and_Static_Variables|Static Variables for Python]]
*Feature: Qt-Testing: Logging with log levels <code>DEBUG</code>, <code>INFO</code> and <code>WARN</code> ([[Qt_Inject_Windows/en#Logging|Qt-Logging]])
*Feature: Qt-Testing: Qt-Connections now use the ConnectionManager like the other Gui test technologies
*Feature: WindowsAutomation: Native Touch, Tap, Drag & Drop support now in the base WindowsAutomation Library
*Feature: Show Log and [[Timeline/en|Timeline view]] for testplans
*Feature: Search and Goto Line menu functions in the activity log view
*Feature: [[Embedded Systems C Bridge API|C-Bridge]] now supports SSL connections (encryption and authentication using certificates)
*Feature: [[Testsuite_Editor-ExecutionSettings_Editor/en|Settings for execution]] (thread pool and log activities/pins/info) can now be saved in the test suite settings
*Feature: CSV test report, values for start time, end time and duration added
*Feature: Improved refactoring for compound blocks: "Extract (& Replace) New Compound Action"
*Feature: Enhanced expecco reflection library
*Feature: Logprocessors can be executed for embedded testplans
*Feature: Logging of background actions can be individually enabled and disabled for testplans and nested testplans
*Feature: Support for script actions written in the [[Installing_additional_Frameworks/en#Julia_Installation|Julia]] programming language
*Feature: Powershell actions: support functions for writing to pins, logging, opening dialogs, etc.
*Fix: Current temporary testplan settings (like selected testcases, do-not-execute of pre/post action, etc.) don't get lost anymore when reimporting a library
*Fix: WindowsAutomation: Fix blocking of applications after <Mouse Button Down>
*Fix: asynchronous write to an output pin with no wait() in bridged actions are now detected and reported as error (see Example3 in the [[Expecco_API/en#Asynchronous_and_Callback_Functions|NodeJS API Documentation]])
*Fix: Bridges: Detect (and ignore) invalid requests from forked background bridge threads
*Fix: Acitivity logs of asynchronous events in background actions are now displayed correctly in the background activity log.
*Fix: Qt: Drag and drop improved by revising the "Move mouse event" (Windows)
*Fix: Disabling logs of sub-activities (if successful, if not successful, etc.)

Mobile Testing Plugin/en

2025-02-17T09:42:58Z

Matilk: /* Windows */ new supplement

[[Mobile_Testing_Plugin|Deutsche Version]] | '''English Version'''

= Introduction =
The ''Mobile Testing Plugin'' adds mechanisms to test and automate Android and iOS devices. This includes both real and emulated devices - it does not matter whether real mobile devices or emulated devices are used. The plugin can (and usually is) used in conjunction with the [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]], which supports the creation of tests. It can also be used to record test procedures.

[http://appium.io/ Appium] is used to connect to the devices. Appium is a free open source framework for testing and automating mobile applications.

We recommend to go through the [[Mobile_Testing_Tutorial/en|Tutorial]] to familiarize yourself with the Mobile Plugin. This tutorial leads step by step through the creation of a test case using an example and explains the necessary basics.

= Installation and Setup =
To use the ''Mobile Testing Plugin'', you must have installed expecco together with the corresponding plugin, and you need the appropriate licenses. expecco communicates with the mobile devices via an Appium server, which either runs on the same computer as expecco, or on a second computer. This must be accessible for expecco.

== Installation Overview ==
'''Computer running expecco:'''
* Java JDK version 8, 9, 10 or 11
'''Computer connected to Android devices :'''
* Appium Server, you can install it via the Mobile Testing Supplement (see below), of which we regularly provide a new version
* Android SDK, you can also get it with the Mobile Testing Supplement
* Java JDK version 8, 9, 10 or 11
'''Computer connected to iOS devices*:'''
* Appium Server, you can install it via the Mobile Testing Supplement for MacOS (see below), of which we regularly provide a new version
* Xcode in a version that supports the iOS version used, available from the Apple App Store
* Java JDK version 8, 9, 10 or 11
* Apple Developer Certificate incl. matching private key (to sign the WebDriverAgent)
* Provisioning Profile for the mobile devices to be used

* Please note that due to the requirements (no connection to non-Apple devices available) iOS devices can only be controlled from a Mac.

Depending on the setup, the above-mentioned computers can also be the same device. expecco can either connect to a remote Appium Server and mobile devices connected to it via the network, or start an Appium Server locally itself and use it with local mobile devices. However, some of expecco's functions that make it easier to create test cases are only available if the mobile devices are connected to the same computer on which expecco is running. A possible setup may therefore look like the following figure:

[[Datei:MobileTestingAufbau.png | 400px]]

The following explains how to install Appium and other necessary applications for Windows and Mac OS.

== Windows ==
The easiest way is to install everything from our Mobile Testing Supplement. However, newer versions do not contain a JDK anymore due to a change in Oracle's license terms, so you have to install it additionally. Of course, you are free to install Appium directly to use the version you want. However, to then be able to start an Appium server with expecco, a suitable batch file must be available and specified in the [[Mobile_Testing_Plugin/en#Plugin_Configuration|settings]]. However, connections can also be established to other running Appium servers.
*'''expecco 24.2''': [https://download.exept.de/transfer/h-expecco-24.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 2.0.1.1]
:Migration to Appium 2. The Appium server starts as default without the path ''wd/hub/''.
:Appium 2.11.0
:Node 20.9.0
:adb 1.0.41 from platform-tools 35.0.1
*expecco 24.1: [https://download.exept.de/transfer/h-expecco-24.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.3]
:Same versions as in the predecessor, but with updated chromedriver versions
*expecco 23.2: [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Same versions as in the predecessor, but with updated chromedriver versions
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Same versions as in the predecessor, but the installer now allows to add Appium to the Autostart.
*expecco 22.2 and 22.1: [https://download.exept.de/transfer/h-expecco-22.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 from platform-tools 33.0.2
:''* We added the capability'' chromedriverStartTimeout ''to Appium, to get a timeout earlier, if Chromedriver cannot be initialized. (see [[#startChromedriverTimeout|Problems and Solutions]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Contains Appium version 1.22.0, Node still is version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Only minor changes compared to the previous version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Compared to the previous version, Appium was updated to version 1.16.0-rc.1 and node 12 is used.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:This installs Appium in the version 1.12.0 and now additionally contains build-tools in the version 28.0.3 in the android-sdk. Apart from this, it is the same as the previous version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:This installs Appium in the version 1.8.1. In addition, an installation of ''Android Debug Bridge'' and ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) is offered. This covers drivers for a broad range of Android devices, and you won't have to install an individual driver for each device. A '''JDK is not contained anymore (due to a change in Oracle's license terms)''', you have to download it on your own, e.g. from [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: same procedure as for expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:This installs a Java JDK Version 8, android-sdk and Appium Version 1.6.4. The supplement also offers a universal adb driver ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]). This driver supports a wide range of Android Devise, and avoids the need to search for individual device-specific drivers.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:It installs a Java JDK version 8, android-sdk and Appium version 1.4.16. During the installation the graphical user interface of Appium is started, you can close this window immediately. The supplement also offers a universal adb driver (ClockworkMod). This combines drivers for a wide range of Android devices so that you do not have to search for and install a separate driver for each device.

If expecco has to use mobile devices that are connected to another computer, you have to start an Appium server there. You can do this by using the file <code>appium_standalone.cmd</code>. The server is then started on default port 4723. If you want to use a different port number, start the server with

appium_standalone.cmd -p <portnummer>

The server is ready, as soon as the line
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
is displayed, where you can read the used port number at the end.

If your Android device is connected to a remote machine,
you may want to see the live screen locally using a tool like
[https://github.com/Genymobile/scrcpy scrcpy].

When Appium is started for the first time – either standalone or by expecco – it may happen that the Windows firewall blocks access to the node server. Allow the access or Appium cannot be started.

== Mac OS ==
Note: the following can be ignored if you do not plan to test iOS (iPhone) devices. The Mac setup is not needed for Android devices.

=== Xcode ===
Automation with iOS devices needs [https://developer.apple.com/xcode/ Xcode]. You can install it from the App Store. Please make sure that the version matches the tested iOS versions.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
This table is only a simplified overview, better see [https://xcodereleases.com/ Xcode releases] or [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode versions] for the exact versions. For new iOS minor versions, there is usually also a new release of Xcode, e.g. for iOS 10.2 you need at least Xcode 8.2, for iOS 10.3 at least Xcode 8.3, etc. So if you are upgrading to a newer iOS version, you will usually need a newer Xcode version as well. Newer versions of Xcode may not run on older operating systems, which in turn may require an operating system upgrade. If you also want to test older iOS versions, it can be useful to install the corresponding Xcode versions in parallel.

=== Appium ===
You can install Appium either as command-line tool or use it with [https://github.com/appium/appium-desktop Appium Desktop], which provides a GUI to start the server. Meanwhile there is also Appium 2.0, which is not tested with expecco yet and therefore not recommended to use.

==== Appium Desktop ====
Download the newest version of [https://github.com/appium/appium-desktop/releases/ Appium Desktop]. For the Mac, it is best to take the dmg file and install it to the applications. When starting ''Appium Server GUI'' you will probably get the error message, that it is not possible for security reasons. In this case, open the context menu of the app file (right click or Ctrl + click) and choose ''Open'' there. Then confirm that you really want to open the application. From now on you can open the application normally.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Since Xcode 14 there are problems with signing the WebDriverAgent, which Appium loads on the device for the automation. This means that no connection is possible with version 1.22.3-4 of Appium Desktop. In newer versions of WebDriverAgent, this problem is solved, but currently there is no version of Appium Desktop using such a new version (as of November 2022). However, you can manually download a new version (e.g. 4.10.2) and replace the files in Appium. To do this, download one of the two archive files (zip or tar.gz) containing the source code from the [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent download page]. Then open and extract this file. Copy the contents of the folder ''WebDriverAgent-4.10.2' to

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

If you navigate there by Finder, make a context click (right click or Ctrl + click) on the application and choose ''Show Package Contents'' from the menu. Replace all files that are already present with the same name.

==== Install Appium using npm ====
You can install Appium using npm (Node Package Manager) as well. To do this, you have to install node/npm first. This can be done using [https://github.com/nvm-sh/nvm nvm] (Node Version Manager), which you can get on Github. If the following installation instructions should not work for you, you will find detailed information in the [https://github.com/nvm-sh/nvm#readme Readme] there.

Open a Terminal window. Then clone the Github repository of nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
and load it
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Then execute
command -v nvm
to see if it works. It should print ''nvm''. If there is no response, execute
touch ~/.zshrc
and try again.

Now you can install node with the following command.
nvm install 16.15.1
As there are problems installing Appium using the newest version of node, we recommend this version.

After node is installed, you can use it to install Appium:
npm install -g appium

The Appium server now simply can be started with the command
appium
The output will then be written directly to the terminal.

This version also has problems with signing the WebDriverAgent, like explained in [[#Appium_Desktop | Appium Desktop]]. Therefore download a newer version of WebDriverAgent in this case as well and replace the old files. You will find them at
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
We provide older versions of Appium via the Mobile Testing Supplement for Mac OS, with which you can easily install it:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.2)]
:Contains Appium version 1.18.3 and uses node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.0)]
:Only a few changes compared to the previous version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.98)]
:Appium is updated to version 1.16.0-rc.1 and node 12 is used.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.96)]
:This version contains Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.94)]
:This version contains Appium 1.8.0.

* expecco 2.11:[http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.0.94)]
:This version contains Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement for Mac OS]
:Diese Version entält Appium 1.4.16.

After you have downloaded the supplement, you can move it to a directory of your choice (e.g. your home directory) and unpack it there. A suitable command in a shell could look like this, adjust the version number accordingly:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

If your default Xcode installation is the one you want to use, you can start Appium directly from the file in the ''bin'' directory with the appropriate version number:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

If you want to use another Xcode than the one configured as default, you have to tell Appium the corresponding path by using the environment variable ''DEVELOPER_DIR''. For example, if you have installed Xcode in ''/Applications/Xcode-11.3.app'', you can start Appium this way:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

To find out what is set as the default Xcode installation on your system, use this command:

xcode-select -p

If Appium cannot find your Xcode installation, a message like this appears:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
In such a case, restart Appium by specifying a valid ''DEVELOPER_DIR''.

==== Signing WebDriverAgent ====
For automation, Appium installs an App called WebDriverAgent on the device and therefore has to be able to sign it. You need an Apple account and a respective certificate for this. For evaluation you can use a free account. This has the disadvantage that created profiles are only valid for one week and must be recreated afterwards. Also be careful when sharing the account, as certificates may be revoked or invalidated by automatic generation. As a result, apps that have already been signed can no longer be used.

If you already have a respective certificate and its associated private key in your keychain on the Mac, you can have the WebDriverAgent automatically signed. If not, it is recommended to set and manage the signing using Xcode.

First, connect the device you want to use to your Mac via USB. Make sure both the Mac and the device are in the same network or there will be problems when connection with Appium. Start Xcode and open ''Preferences''. Go to the Accounts page and create an entry with your account. You can then click on ''Manage Certificates...'' to see the certificates that belong to that account. To run tests, you need an iOS Development Certificate and the associated private key. If you do not already have one, create one. If you already have one, but it is not in your keychain (indicated by "Not in Keychain"), you can import it. You can do that by the [https://support.apple.com/en-us/guide/keychain-access/welcome/mac keychain access] on your Mac, if you have exported it previously from the keychain, where it is stored. The certificate with the associated key should be in the keychain ''Login''. It can be exported from there as PKCS#12 file (typical ending .p12). To import a certificate into your keychain, select the option ''Import objects'' from the ''File'' menu. If you don't know where the certificate is stored, you can also revoke it in Xcode and recreate it in your keychain. However, only do this if you know that the old certificate is no longer in use because it can no longer be used afterwards. Now the keychain should contain an iOS development certificate.


Now open the WebDriverAgent project in Xcode. If you have installed the Mobile Testing Supplement, you will find it in this directory at
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
If you have installed Appium Desktop, you will find it at
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''

You can use the Finder to navigate to the Xcode project file and open it by double clicking. Note, that you have to perform a context click (right click or Ctrl + click) on the Appium Server GUI app and select ''Show Package Contents'' in the menu, to get to its subdirectory.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Select ''WebDriverAgentLib'' and the page ''Signing & Capabilities''. In the section ''Signing'' set the option ''Automatically manage signing'' and then select a team. Now switch to ''WebDriverAgentRunner'' and do the same there.

By setting the team, the errors showing up for WebDriverAgentRunner should disappear. If Xcode should not be able to create a Provisioning Profile matching the Bundle ID ''com.facebook.WebDriverAgentRunner'', you can edit the latter so that it fits your certificate. After that you can quit Xcode or you can, like explained further below, directly start the build in Xcode, so the project will be already built when Appium wants to use it.

If you now connect to your device from expecco, the WebDriverAgent will be installed and started on it and then switch to the app to be tested. You may still have to trust the execution of the WebDriverAgent on the device. It maybe a sign that you have to do this, if the app WebDriverAgent first appears on the device and tries to start, but then is uninstalled again. To trust the execution, open the settings during the connection setup on the device and then the entry ''Device management'' under ''General''. This entry is only visible if a developer app is installed on the device. You may therefore have to wait until the WebDriverAgent is installed before the entry appears. Select the entry of your Apple account and trust it. Since the WebDriverAgent will be uninstalled again if the start did not work, you have to do this during the connection setup. If this is too hectic for you, you can also execute the following code:

xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

or
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

This installs the WebDriverAgent on the device without deleting it again.

If there are problems while installing the WebDriverAgent, you can also try and start the build in Xcode. Make sure the right target ''WebDriverAgent'' is selected. Error messages in Xcode might indicate easier what the problem is about. Sometimes it even helps to try for a second time, if it took too long for the first time and got aborted. It may occur, that you are asked several times during the build to enter the password for the keychain.

[[Datei:WebDriverAgentCodesign.png]]

Read also the documentation of Appium on [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Setting up tests with iOS devices]. Refer to the [https://support.apple.com/en-us/HT204460 Apple documentation] for details on installing and trusting of apps.

Once the WebDriverAgent is installed on the device, it will be reused for later connections und connecting should work faster. The signed version is then already on your Mac as well and doesn't have to be built again. This should speed up the connect with other devices as well. If you know, that the connect has to build and sign the WebDriverAgent first, it is advisable to set the capability ''wdaLaunchTimeout''. This timeout specifies how long Appium waits for the WebDriverAgents to start up on the device and is per default set to 60000 ms. Building often takes a little longer than one minute, so the connect attempt will be canceled. A value of 120000 will be more reliable here.

== Plugin Configuration ==
Before you start, please check the settings of the Mobile Testing Plugin and adjust them if necessary. Select the menu item "''Extras''" → "''Settings''" → "''Extensions''" → "''Mobile Testing''" (see fig.). By default, these paths are found automatically (1). To adjust a path manually, deactivate the corresponding check mark at the right. You'll see a drop-down list with some paths to choose from. If an entered path is wrong or cannot be found, the field is marked red and a message appears. Make sure that all paths are specified correctly.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Plugin Configuration]]

*'''appium''': Enter the path to the executable file with which Appium can be started in the command line. Under Windows this file will usually be called "<code>appium.cmd</code>". This path is used when expecco starts an Appium server.
*'''node''': Enter the path to the executable that starts Node (also called (also called "Node.js"). This path is passed to Appium when a server is started so that Appium can find it independently of the PATH variable. Under Windows this file is usually called "<code>node.exe</code>".
*'''JAVA_HOME''': Enter the path to a JDK (Java Development Kit)here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable. To specify which Java should be used by expecco, set this path in the Java Bridge settings.
*'''ANDROID_HOME''': Enter the path to an Android SDK here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable.
*'''adb''': The path to the adb command. Under Windows the file is called "<code>adb.exe</code>". This file is used by expecco, for example, to get the list of connected devices. This path should be selected automatically, if the command is found in the ANDROID_HOME directory. This is also used by Appium. If expecco and Appium use different versions of adb, conflicts may occur.
*'''android.bat''': This file is only needed to start the AVD and the SDK Manager, which deal with phone emulators. The file in the ANDROID_HOME directory will be selected automatically, if present there.
*'''aapt''': The path to the "aapt" command here. Under Windows this file is called "<code>aapt.exe</code>". expecco uses "aapt" only in the connection editor to read the package and activities of an "apk" file. The file in the ANDROID_HOME directory will be selected automatically, if present there.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | JDK Configuration]]

Starting with expecco 2.11, there is an additional field called ''Team ID''. If you run iOS tests, enter the Team ID of your certificate here. This is used for every iOS connection, unless you change the value in the connection settings in individual cases. For information on how to obtain the team ID, please refer to the section on [[#Signing| signing]] for installations on Mac OS. With expecco 2.10 and older, you can only enter the Team ID as capability for each connection setting separately. However, you must use the [[#Extended_View|extended view]] to do this. Enter the capability ''xcodeOrgId'' here and set the Team ID of the certificate as value.

The server address setting at the bottom of the page refers to the behavior of the connection editor. It checks at the end whether the server address ends in ''/wd/hub'' as this is the usual form. If not, a dialog asks how to react. The defined behavior can be viewed and changed here.

Also switch to the entry ''Java Bridge'' (see figure). Here you have to specify the path to your Java installation, which is used by expecco. Enter a JDK here. If you want to use the one from the Mobile Testing Supplement under Windows, the path is
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
You can also use the system settings.

== Prepare Android Device ==
If you connect an Android device under Windows, you may still need an adb driver for the device. You can usually find a suitable driver on the manufacturer's website. If you have installed the universal driver from the Mobile Testing Supplement, everything should already work for most devices. In some cases, Windows will automatically try to install a driver when you connect the device for the first time. 
'''Attention''': Before you can control a mobile device with the Appium plugin, you have to allow this debugging!

For Android devices, you can find this option in the settings under ''[https://developer.android.com/studio/debug/dev-options Developer Options]'' called ''USB-Debugging''. If the developer options are not displayed, you can unlock them by tapping Build Number seven times in About the Phone.

Also enable the ''Stay awake'' feature to prevent the device from turning off the screen during test creation or execution.

For security reasons, USB debugging must be allowed for each computer individually. When connecting the device to the PC via USB, you must agree to the connection on the device. If you haven't done this for your computer yet, but no corresponding dialog appears on the device, it may help to unplug and reconnect the device. This can happen especially if you have installed the ADB driver while the device was already connected via USB. If this doesn't help either, open the notifications by dragging them from the top of the screen. There you will find the USB connection and you can open the options. Select another type of connection; usually MTP or PTP should work.

You can also test on an emulator. It does not need to be prepared separately, as it is already designed for USB debugging. It is even possible to start an emulator at the beginning of the test.

To check if a device you have connected to your computer can be used, open the [[#Connection_Editor|connection editor]]. The device should be displayed there.

=== Connection via WLAN ===
It is possible to connect to Android devices via Wireless LAN. For devices using Android 11 or newer, this can be done wirelessly, else you have to connect initially via USB. Since expecco 22.1, WiFi connections can be established using the [[Mobile_Testing_Plugin/en#Connection_Editor|Connection Editor]]. It is also possible to do this using a command window.
==== Wireless Connect (Android 11) ====
In the developer options of your device, enable wireless debugging and open its options. You initially have to pair your machine with the device. To do this, choose "''Pair device with pairing code''" to get a pairing code and an IP address with port. Then open a command window (terminal window) on your machine and enter:
<nowiki>adb pair <Device IP Address>:<Pairing Port></nowiki>
where <tt><Device IP Address>:<Pairing Port></tt> is the IP address and port as shown on the device. After that, you will be asked for the pairing code. If everything went right, the popup on the device should have closed and your machine is added to the list of paired devices. Then enter at the command window:
<nowiki>adb connect <Device IP Address>:<Debugging Port></nowiki>
The IP address is the same as for pairing, but the port is different. Both are shown as IP address & Port on the device. The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted. Restarting the device often disables wireless debugging and the used port is changed. The pairing, however, is permanent and has not to be done again the next time you connect.
==== Start via USB ====
First, connect your device via USB. Then open a command window (terminal window) and enter:
<nowiki>adb tcpip 5555</nowiki>
The device listens for a TCP/IP connection on port 5555. If you have several devices connected or emulators running, you have to specify which device you mean. Enter in this case:
<nowiki>adb devices -l</nowiki>
to get a list of all devices, where the first column gives the device's ID.
Then, enter:
<nowiki>adb -s <deviceID> tcpip 5555</nowiki>
with the device identification of the desired device. You can now disconnect the USB connection. Now you have to find out the IP address of your device. You can usually find it somewhere in the device's settings, for example in the Status or WLAN settings of the phone. Then type in:
<nowiki>adb connect <IP address of device></nowiki>
The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> again or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted.

== Preparing an iOS-Device and App ==
Control of iOS devices is only possible via a Mac. Please also read the section [[#Mac_OS|Installation under Mac OS]].

Before you can control a mobile device with the Mobile Testing Plugin, you must allow debugging for iOS devices with iOS 8 or higher. Activate the option "''Enable UI Automation''" under the "''Developer''" menu in the device settings. If you cannot find the "''Developer''" entry in the settings, proceed as follows: Connect the device to the Mac via USB. If necessary, you must still agree to the connection on the device. Start Xcode and then select "''Devices''" from the menu bar at the top of the screen in the "''Window''" menu. A window opens in which a list of the connected devices is displayed. Select your device there. Then the entry "''Developer''" should appear in the settings on the device. You may have to exit the settings and restart.

[[Datei:Alert.png | thumb | 270px | Alert unter iOS]]
It is not possible to establish a connection to the device as long as it shows certain alerts. Such an alert may appear if FaceTime is activated (by displaying a message about SMS charges as shown in the screenshot). Be sure to configure the device so that it does not show such alerts when idle.

=== expecco 2.11 and later ===
You can test any app which is executable or already installed on the device used. If the app is available as a development build, the UDID of the device must be stored in the app. In any case, the WebDriverAgent must be signed for the device. Please read the section about [[#Signing|signing]] under Mac OS.

If you want to use the Home button in a test, you must activate "AssistiveTouch" on the device. You will find this option in the settings under "''General''" > "''Operating Help''" > "''AssistiveTouch''". Then place the menu in the middle of the upper edge of the screen. You can then record pressing the Home button with the corresponding menu entry in the recorder or use the "''Press Home Button''" block directly.

=== expecco 2.10 ===
The app you want to use must be available as a development build. The UDID of the device must also be stored in the app.

=== Sign the development build ===
A development build of an app is only allowed for a limited number of devices and cannot be started on other devices. However, it is possible to exchange the certificate and the usable devices in a development build.

* Evaluation with demo app of eXept:
:We will be happy to provide you with a demo app which is available as a development build and which we can sign for your device. Please send the UDID of your device to your eXept contact person. How to determine the UDID of your device is described in the following section.

* Using your own app for your test device:
:If you receive a development build (IPA file) from the app developers that is approved for your test device, you can use it directly. To do this, you must tell the developers the UDID of your device so they can enter it. '''You can use Xcode to read the UDID of a device'''. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window opens in which a list of the connected devices is displayed. Select your device and search for the ''Identifier'' entry in Properties. The UDID is a 40-digit hexadecimal number.

* Externally developed app for your test device:
:You can also re-sign apps to make them run on other devices. However, this process is complicated and requires access to an Apple Developer account. A documentation on the procedure is currently in preparation.

:For the evaluation we will gladly support you with the re-signing of your app..


For more information about using iOS devices, see also the
[http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Appium documentation].

=== Native iOS-Apps ===
You can also use apps that are already natively present on the device. To do this, you must know their bundle ID and then enter it in the connection settings. Here is a small selection of common apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

You can find further Bundle-IDs [https://github.com/joeblau/apple-bundle-identifiers here].

= Examples =
In the demo test suites for expecco you will also find examples for tests with the Mobile Testing Plugin. To do this, select the option "''Example from File''" on the start screen and open the folder named "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
The test suite contains two simple test plans: "''Simple CalculatorTest''" and "''Complex Calculator and Messaging Test''". Both tests use an Android emulator, which you must start before starting. The apps used in the test are part of the basic equipment of the emulator and therefore no longer need to be installed. Since the apps may differ under every Android version, it is important that your emulator runs under Android 6.0. In addition, the language must be set to English.

; Simple CalculatorTest
: This test connects to the calculator and enters the formula ''2+3''. The result of the calculator is compared with the expected value ''5''.

; Complex Calculator and Messaging Test
: This test connects to the calculator and then opens the message service. There it waits for an incoming message from the number ''15555215556'', in which a formula to be calculated is sent. The message is generated before via a socket at the emulator. When the message arrives, it is opened by the test and its contents are read. Then the calculator is opened again, the received formula is entered and the result is read. The test then switches back to the message service and sends the result as an answer.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
These are part of the tutorial for the Mobile Testing Plugin. The included test case is incomplete and will be added during the tutorial. Please read the section [[#Tutorial|Tutorial]].

= Tutorial =
There is a tutorial describing the basic procedure for creating tests with the Mobile Testing Plugin. It is based on a supplied example consisting of a simple app and an expecco test suite.

You find it on the page [[Mobile_Testing_Tutorial/en|Mobile Testing Tutorial]] in two versions for Android and iOS devices.
*  [[Mobile_Testing_Tutorial/en#First_steps_with_Android|First steps with Android]]
*  [[Mobile_Testing_Tutorial/en#First_steps_with_iOS|First steps with iOS]]

= Dialogs of the Mobile Testing Plugin =
== Connection Editor ==
You can use the Connection Editor to quickly define, change, or establish connections. Depending on the task, the dialog has small differences and is opened differently:
*If you want to establish a connection, access the dialog in the GUI browser by clicking on ''Connect'' and then selecting ''Mobile Testing''.
*To change or copy an existing connection in the GUI browser, select it, right-click and select ''Edit Connection'' or ''Copy Connection'' from the context menu.
*If you do not want to create connection settings for the GUI browser but for use in a test, choose ''Create Connection Settings'' from the Mobile Testing Plugin menu.... This only allows you to create the settings for a connection without creating a connection in the GUI browser.

The Connection Editor menu has several buttons, some of which are only visible when creating connection settings:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#''Delete Settings'': Resets all entries. (Only visible when creating settings.)
#''Load settings from file'': Allows to open a saved settings file (*.csf). Its settings are transferred to the dialog. Entries already made without conflict are retained.
#''Load settings from attachment'': Allows you to open an attachment with connection settings from an open project. These settings are applied to the dialog. Entries already made without conflict are retained.
#''Save settings to file'' and
#''Save settings to attachment'': Here you can save the entered settings to a file (*.csf) or create them as an attachment in an open project. Both options have a delayed menu in which you can choose to save only a certain part of the settings. (Only visible when creating settings.)
#''Advanced View'': Allows you to switch to the advanced view to make additional settings. Read more about this at the end of this chapter. (Only visible when creating settings.)
#''Help'': A help text for the respective step is shown or hidden on the right side.

The dialog is divided into three steps. In the first step you select the device you want to use, in the second step you select which App should be used and in the last step the settings for the Appium server are made.

===Step 1: Select Device ===
In the upper part you will see a list of all connected Appium devices that are detected. With the checkbox below you can hide devices that are detected but not ready. If you want to enter a device that is not connected, you can create it with the corresponding button ''Enter Android device'' or ''Enter iOS device''. However, you need to know the required properties of your device. The device is then created in a second device list and can be selected there. If no list with connected elements can be displayed, various messages are displayed instead:
*No devices found
*:expecco could not find any Android devices.
*:To automatically configure a connection to a device, make sure
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*No available devices found
*:expecco could not find any available Android devices. But not available ones were found, e.g. with the status "unauthorized".
*:To configure a connection to a device automatically, make sure that
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*:To view unavailable devices, enable this option below.
*Connection lost
*:expecco has lost the connection to the adb server. Try to re-establish the connection by clicking on the button.
*Connection failed
*:expecco could not connect to the adb server. Possibly it is not running or the specified path is not correct.
*:Check the adb configuration in the settings and try to start the adb server and establish a connection by clicking on the button.
*Connect ...
*:expecco connects to the adb server. This may take a few seconds.
*Start adb-Server ...
*:expecco starts the adb-Server. This may take a few seconds.

With ''Next'' you get to the next step. If you enter settings for the GUI browser, this is only possible once a device has been selected.

Note on unlocking: In newer Android versions the developer options are no longer offered in the settings at first. If your Android device does not show an entry for "''Developer options''" in the settings, first select the entry "''Phone info''", then "''SoftwareVersionsInfo''" and click on the entry "''BuildVersion''" several times.

==== Manage Chromedrivers ====
If the App you want to automate uses WebViews with Chrome, Appium needs to have access to an appropriate Chromedriver. If you have selected a device in the list, you can use "''Manage Chromedrivers''" to see, which Chrome versions are installed on the device and which Chromedriver versions are provided by expecco. With this dialog you can also download required Chromedriver versions. Beware that there may be several Chrome versions on the device. An App doesn't have to use the version of the installed Chrome browser for its WebViews. The Chromedriver you use should fit your app for everything to work properly. You can also change the path to the Chromedriver in the capabilities generated at the end of the connection editor.

==== Connect WiFi Android Device ====

You can connect to Android devices using WiFi as well. In this case, the device has to be connected to ADB first, see [[Mobile_Testing_Plugin/en#Connection_via_WLAN|Connection via WLAN]]. Since expecco 22.1, the connection editor provides a dialog helping to set this up, which can be used instead of the command window. For devices using Android 11 or newer, you can pair the device with your machine here by specifying the appropriate parameters and then establish the connection by specifying the IP address and port. You can also use this to establish a wireless connection for devices that are connected via USB. When you select the corresponding device in the list, the required information is read out automatically.

Note that establishing a wireless connection is not part of the connection settings. If you want to establish a new connection with the generated settings, you must make sure that the device is connected to ADB with the specified IP address and port so that it can be found. The ADB connection will be lost if the ADB server or the device are restarted. The permission for wireless debugging is also often reset when the device is restarted and the debug port can then change. Therefore, a wireless connection must always be established manually.

===Step 2: Select App===
Here you can enter information about the app to be tested. You can decide if you want to use an app that is already installed on the device or if you want to install an app for the test. Select the appropriate tab above. Depending on whether you selected an Android or an iOS device in the previous step, the required input will change.

*'''Android'''
**''App on Device''
**:If you have selected a connected device in the first step, the packages of all installed apps are automatically retrieved and you can select from the drop-down lists. The installed apps are divided into third-party packages and system packages; select the appropriate package list. This selection does not belong to the settings, but only provides the corresponding package list. You can use the filter to further narrow down the list and then select the desired package. The activities of the selected package are also automatically retrieved and made available as a drop-down list. Select the activity you want to start. As a rule, an activity is automatically entered from the list. If you are not using a connected device, you must enter the package and the activity manually.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. If you are using a local Appium server, you can use the right button to navigate to the App installation file and enter this path. If possible, the corresponding package and the activity are also entered in the fields below. However, this entry is not necessary.

*'''iOS'''
**''App on Device''
**:Specify the bundle ID of an installed app. You can find out the IDs of the installed apps using Xcode, for example. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window will open displaying a list of connected devices. If you select your device, you will see a list of the apps you have installed in the overview.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. For the requirements of apps for real devices, please read the section [[#iOS-Ger.C3.A4t_and_App_Preparing|Preparing an iOS-Device and App]].

In the lower part you can specify whether the app should be reset or uninstalled when the connection is terminated, and whether it should be reset initially. Again, the corresponding capability is not set if you select ''(Default)''. With ''Next'' you get to the next step.

===Step 3: Server Settings===
In the last step, a list of all the capabilities that result from your entries in the previous steps is first displayed in the upper part. If you are familiar with Appium and want to set additional capabilities that are not covered by the connection editor, you can click on ''Edit'' to open the extended view. See the section below for more information.

If you enter settings for the GUI browser, you can enter the ''Connection name'' with which the connection is displayed. This is also the name under which devices can use this connection when it is established. If you leave the field blank, a name will be generated. If the box "''Managed by expecco''" is checked, expecco will start a local Appium server on a free port, or use a free server that has already been started. To use your own server, turn this feature off and enter the appropriate address. You will get the local default address and already used addresses to choose from.

In older expecco versions the box is labeled "''Start on demand''". In this case, you must also enter an address if you want expecco to start the server. expecco then tries to start an Appium server at the given address when connecting, if none is running there yet. This server will then also be shut down when the connection is terminated. This only works for local addresses. Make sure that you only use port numbers that are free. It is best to only use odd port numbers from the standard port 4723. The following port number is also used when establishing a connection, which could otherwise lead to conflicts.

Depending on how you opened the dialog, there are now different buttons to close it. In any case you have the option to save. This opens a dialog where you can either select an open project to save the settings there as an attachment, or choose to save it to a file that you can then specify. Saving does not close the dialog, allowing you to select another option.

If you have opened the editor for establishing a connection, you can finally click on ''Connect'' or ''Start and connect server'', depending on whether the check mark for server start is set. For changing or copying a connection in the GUI Browser, this option is called ''Apply'', since in this case only the connection entry is changed or created, but the connection setup is not started. If necessary, you can do this afterwards via the context menu. If you have changed capabilities of an existing connection, a dialog then prompts you to decide whether these changes should be applied directly by closing the connection and establishing the new connection or not. In this case, the changes only take effect after you reestablish the connection.

To use the connection editor, also read the corresponding section in the respective tutorial in step 1. (Android: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo|Run Demo]], iOS: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo_2|Run Demo]]).

===Extended View===
The extended view of the connection editor can be obtained either by clicking on ''Edit'' in the third step or at any time via the corresponding menu item if you have started the editor via the plugin menu. This view displays a list of all configured Appium Capabilities. You can add, change or remove further entries to this list. To add a capability, select it from the drop-down list of the input field. In this list all known capabilities are sorted into the categories ''Common'', ''Android'' and ''iOS''. If you have selected a capability, a short information text is displayed. You can also enter a capability manually in the field. Then click on ''Add'' to add the capability to the list. There you can set the value in the right column. To delete an entry, select it and click on ''Remove''. With ''Back'' you leave the extended view.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Running Appium Servers ==
In the menu of the Mobile Testing Plugin you will find the entry ''Appium-Server...''. This opens a window with an overview of all Appium servers started by expecco and on which port they are running. By clicking on the icon in the column ''Show Log'' you can view the logfile of the corresponding server. This is deleted when the server is shut down. With the icons in the column ''Exit'' the corresponding server can be terminated. However, this is prevented if expecco still has an open connection via this server. The rightmost column shows for which connection the server is in use. If it reads ''<idle>'', the server is currently not used by expecco.

[[Datei:MobileTestingAppiumServer.png]]

When opening the editor to start an Appium connection, an Appium server is started immediately to speed up the connection process. For this purpose, expecco always keeps one idle running Appium server. Additional running servers however, which are not in use anymore, will be terminated automatically after a while.

In the menu of the Mobile Testing Plugin you will also find the entry ''Close all Connections and Servers''. This is intended for cases where connections or servers cannot be terminated in any other way. If possible, always terminate connections in the GUI browser or by executing a corresponding block. Servers that you have started in the server overview should be terminated there; servers that were started with a connection are automatically terminated with this connection.

Note that only servers started and managed by expecco are listed in the overview. Possible other Appium servers that were started in a different way are not recognized.

== Recorder ==
If the GUI browser is connected to a device, the integrated recorder can be used to record a test section with that device. To start the recorder, select the appropriate connection in the GUI browser and click the Record button. A new window opens for the recorder. The recorded actions are created in the GUI browser work area. It is therefore possible to edit the recorded data in parallel.

[[Datei:MobileTestingRecorder.png|caption|]]

====Components of the Recorder Window====
#'''Continue/Pause Recording''': You can pause the recording by clicking the right icon. You will then see a large pause sign in the view. All actions that you perform now in the recorder are executed, but no blocks are recorded. You can switch back to normal recording mode by clicking the left icon.
#'''Stop Recording''': Stops the recording and closes the recorder window.
#'''Update''': Gets the current image and element tree from the device. This is necessary if the device takes longer to execute an action or if something changes without being triggered by the recorder. Since expecco 21.2, there is an additional submenu here that can be used to enable automatic update by checking for changes in the background (see also ''Automatic Update'' further below).
#'''Follow Mouse''': Select the element under the mouse pointer in the GUI browser.
#'''Element Highlighting''': The element under the mouse is outlined in red.
#'''Show Elements''': Show the borders of all elements in the view.
#'''Tools''': Selection, which tool is used for recording. The selected action is triggered with each click on the view. The following actions are available:
#*Element Actions:
#**Click: Short click on the element under cursor. To determine more precisely which element is used, use the Follow Mouse or Element Highlighting function.
#**Tap with Duration (Element): Similar to click, except that the duration of the click will be recorded as well. This allows the recording of long clicks.
#**Tap with Position (Element): Similar to click, but additionally records the position inside the element. The position can be recorded relative to the element size or, when pressing Ctrl while clicking, as absolute position from the upper left corner of the element.
#**Set Text: Allows to set the text of an input field.
#**Clear Text: Clears the text of an input field.
#*Device Actions:
#**Tap (Screen): Triggers a click at the screen position.
#**Tap with Duration (Screen): Triggers a click at the screen position, which also considers the duration.
#**Swipe: Swipe in a straight line from the point where you press the mouse button until you release it. The duration is also recorded.
#:Please note for this actions that the result may differ on different devices, e.g. with different screen resolutions.
#*Test Flow Blocks
#**Check Attribute: Compares the value of a specified attribute of the element with a predefined value. The result triggers the corresponding output.
#**Assert Attribut: Compares the value of a specified attribute of the element with a predefined value. If the values are not equal, the test fails.
#**Get Attribute: Gets the current value of a specified attribute of the element.
#*Auto
#:If the Auto tool is selected, you can use all actions by specific input methods: ''Click'', ''Tap Element'' and ''Swipe'' still work by clicking, but are distinguished by the duration and movement of the cursor. To trigger a ''Tap'', hold down Ctrl while clicking. The remaining actions are available in a context menu by right-clicking on the element.
#'''Context Actions''': Here you can record actions concerning contexts:
#*Switch to Context: Shows a list of all currently available contexts and you can select to which one you want to switch.
#*Get Current Context: Gets the handle of the current context.
#*Get Context Handles: Gets a list of all currently available contexts.
#'''Softkeys''': Only for Android. Simulates pressing the buttons Back, Home, Menu and Power.
#'''Home Button''': Only for iOS since expecco 2.11. Allows pressing the Home button.Prior to expecco 19.2, it only works if AssistiveTouch is activated and the menu is located in the middle of the upper screen border. From expecco 19.2 on, the function no longer uses AssistiveTouch.
#'''Help''': Opens this online documentation on the general page about [[GuiBrowser_Recorder/en|GUI Browser recorders]].
#'''View''': Shows a screenshot of the device. Actions are triggerd by mouse depending on the selected tool. If a new action can be recorded, the window has a green frame, else it is red.
#'''Resize Window to Image''': Resizes the recorder window so that the screenshot can be displayed completely.
#'''Resize Image to Window''': Scales the screenshot to a size that makes use of the full size of the window.
#'''Adjust Display''': Opens a dialog to adjust the displayed image, if expecco does not show it right. You can correct the scaling or rotate the image by 90°.
#'''Correct Orientation''': Corrects the image if it is upside down. Using the arrow to the right, the image can also be rotated by 90°, if this should ever be necessary. Since expecco 19.1 you find this functionality under ''Adjust Display''. The orientation of the image is irrelevant for the functionality of the recorder, it only works on the elements it receives.
#'''Scaling''': Changes the scaling of the screenshots.
#'''Messages''': Shows the path of the current selected element or other messages. It has a context menu to show a list of previous messages.

====Usage====
Each click in the window triggers an action and is recorded in the workspace of the GUI browser. There you can run, edit, or create a new block from what you have recorded. You find the actions to trigger softkeys directly in the menu bar (see above). To record actions on elements, either change the selection of the tool in the menu bar (see above) and then click on the element or select the corresponding action from the context menu by right-clicking on the corresponding element. For text input it is also possible to place the cursor over the element and enter the text. This opens the input dialog for this action. On how to use the recorder, see also step 2 in the tutorial ([[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_Block_with_the_Recorder|Android]] resp. [[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_block_with_the_Recorder_2|iOS]]).

====Hide elements====
Since expecco 21.2 it is also possible to hide the selected element in the recorder from the context menu. This means that this element cannot be selected from now on. This function is useful for ignoring elements that are in the foreground to be able to access elements below them. To undo this state, you have to find the corresponding element in the tree of the GUI browser, which also has such an entry in the context menu.

====Automatic Update====
The recorder doesn't show a live image of the device, but only a snapshot. Therefore an update is needed after changes to match what is displayed on the device. The recorder updates automatically after executing an action. Since expecco 20.2 there are further automatic updates possible. You can enable the, in the menu "View".

One option is, to check after an action has been executed, if there are further changes after the first update. If so, a second update is triggered. This shall fix the problem, that the recorder is not up to date after an action, because the update has been done too early.

The second option is to enable a periodical update. After a set interval the recorder is automatically updated if there are changes. Thereby the recorder view is mostly up to date, but this causes an overhead regarding the communication to the device.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid Apps and WebViews =
'''!!! IMPORTANT NOTICE - If you have problems switching to the webview, please set the "Default Application - Browser App" in Android Settings to "Chrome" !!!'''

Hybrid apps contain platform native elements as well as other elements that are integrated in a WebView. These elements can also be used, but you first have to switch to the corresponding context. With the block ''Get Current Context'' you get the current context. Initially this is ''NATIVE_APP'', i.e. the context of the native elements. With the block ''Get Context Handles'' you get a collection of all existing contexts. If there is a WebView context, it is called ''WEBVIEW_1'' or ''WEBVIEW_<package>'' with the package of the WebView. Several WebView contexts are also possible. For each WebView context, there is a corresponding WebView element in the native context. You can use the ''Switch to Context'' block to switch to such a context and from now on only have access to the elements in this context.

In the GUI browser, the existing contexts are displayed at the top of the tree as well as the tree of a context is inserted below the corresponding WebView element.

=Customizing XPath using the GUI Browser=
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen ''GTIN-13 (EAN-13)'' und ''Verify'', das Eingabefeld der Zahl ''4006381333986'' und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des GTIN-13-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch ''Pfad überprüfen'' (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit ''Verify Path: OK'' (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit * zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert ''GTIN-13 (EAN-13)'' besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer ''hierarchy'' (für iOS wäre es ''AppiumAUT''), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix ''android.widget.'', das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend ''XCUIElementType'' am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. ''FrameLayout'' ist ein Kindelement von ''hierarchy'', ''LinearLayout'' ist ein Kind von ''FrameLayout'' usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element ''hierarchy'' beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben ''TextView''-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ ''Button'' gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut ''resource-id''. Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut ''name'' verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem @ eingeleitet und der Wert mit einem = in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter ''Test'' eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf ''Lauf''. Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu ''Eigenschaften'', wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

=Problems and Solutions=
== Locators depend on the version or are variable ==
In this case consider to either store the locators (xPath) in a variable or to define a locator mapping inside a screenplay attachment. It is also possible to store just parts of an locator (e.g. locator path of a parent or attribute value) in a variable and add them in the freeze value of the locator pin by "''$(varName)''".

== Invisible UI Elements ==
Note that the [[#Recorder|Recorder]] also considers items that you cannot see on the screen. Therefore, turn on element highlighting or use the follow mouse function and the element tree in the GUI browser to determine if the correct element is used. It can happen, that invisible elements are in front of other elements and cover them, so that the desired element cannot be selected in the recorder. See section [[#Hide_elements|Hide elements]] for a solution to this.

==''org.openqa.selenium.StaleElementReferenceException''==
The error <code>org.openqa.selenium.StaleElementReferenceException</code> occurs whenever an element is used that is no longer there. If that happens during your test and the element should have been there, try using the locator (xPath) instead to fetch the element again.

In some cases this error can also occur even if you already use a locator at the action block. This is because the locator is always resolved first and the corresponding element is fetched and the action is then executed with this element. If the app refreshes the element exactly between the resolving and fetching part and the execution, creating a new element, this error occurs. If it happens at a specific point in your test, your best option is to catch the error and retry.

== iOS: Cable not certified ==
In some cases, when connecting an iOS device via USB, a message appears indicating that the cable used is not certified. In this case, replacing the respective cable is the only solution.

== iOS: Alerts when connecting ==
Make sure that no alerts are open when connecting to an iOS device. Otherwise the connection will fail because the app cannot be brought to the foreground. See also [[#Preparing_an_iOS-Device_and_App|Preparing an iOS-Device and App]].

== iOS: .ipa cannot be installed ==
Note that on iOS simulators no ''.ipa'' files can be installed but only ''.app'' files.

==iOS: First Connect is not working==
If there is not already a signed build of the WebDriverAgent on your Mac, it has to be created during the first connect. Usually, this can take a little longer than one minute. Per default Appium uses a timeout of 60000 ms to wait for the WebDriverAgent to start on the device, so the connect will be canceled in that case. You can set this timeout with the capability ''wdaLaunchTimeout'', e.g. to ''120000''.

Moreover, the signing settings have to be correct. In our experience, the most reliable solution is to set automatic signing in the WebDriverAgent Xcode project an selecting the team there. See the explanation in section [[#Signing_WebDriverAgent|Signing WebDriverAgent]] for that. In this case you should '''not''' use the capabilities ''xcodeConfigFile'' resp. ''xcodeOrgId'' and ''xcodeSigningId'', as they could cause a conflict. Caution: If you have set a Team ID in the Mobile Testing settings, expecco will automatically set this as ''xcodeOrgId''!

Pay attention to your device during the first connect. You might have to agree to the installation by entering your password. On the Mac you might need to enter the password to allow access to the key chain for signing, often several times.

== Android: Device not visible in the connect editor ==
If an Android device connected via USB does not appear in the connection editor, try changing the USB connection type. Usually MTP or PTP should work. Check again, if "USB Debugging" is enabled in the developer options on the device (these options are disabled on some devices and have to be enabled first using a trick.) See also [[#Prepare_Android_Device|Prepare Android Device]].

== Android: Truncated Elements at Bottom ==
For Android devices that automatically show and hide the navigation bar/softkeys, the recorder may cut off elements in the lower area that would be hidden by the softkeys, even if they are not displayed at this time. In this case it is advisable to set the softkeys so that they are permanently displayed.

For newer Android versions there usually is no such option. Even if the controls are visible all the time, they don't have their own space, but are on top of the content of the app. Therefore, there is an area on the lower part of the screen, which cannot be automated, because it is not counted to the active area of the app. Appium will then truncate the elements there. This area can even be larger then the needed by the controls. This is a known issue for Samsung devices with Android 11. Since the information about the size of the app area is already provided on Android level, we cannot offer a solution for this, but can only hope that the problem will be fixed by the manufacturer. You may try to get better results by setting the control to gestures, but this bears the same issue.

== Android: Test Hangs While Finding an Element==
The block ''Find Element by XPath'' and all element blocks wait until an element is present for the given path. The timeout for this can be set either directly at the block or in the environment variables. However, if the element should already be present, but the test doesn't continue anyway, the reason could be in the UIAutomator/UIAutomator2. It waits for the app to go to the idle state before it even starts to search for the element. This may take longer, if the app e.g. runs an animation in the background or executes other kinds of actions. Fetching the page source, e.g. when updating in the GUI browser or in the recorder, can also take longer for this reason. There is a default timeout of 10 seconds after which it no longer waits for the idle state. This timeout can be set in Appium (waitForIdleTimeout). If you want to change the value of this timeout, you can do this since expecco 21.2 by executing the Smalltalk code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> before the test. The timeout is given in milliseconds, so the example sets it to 2 seconds.

==Android: Updating the Tree or Switching to Webview Context takes too long==
Especially with older devices it can happen that newer Chromedriver cannot be initialized. This makes it impossible to switch to the webview context. However, this is only detected over a timeout by Appium, which is 4 minutes by default. Since expecco also tries to switch to the webview context when building the tree in the GUI browser, this can lead to very long loading times. Since there is no way to decrease this timeout in Appium, we have added a corresponding capability to the version we provide in the MobileTestingSupplement. Starting with version 1.13.1.0 of the [[#Windows|MobileTestingSupplement]], ''chromedriverStartTimeout'' can be used to set the timeout in milliseconds. The switch still doesn't work then, but expecco doesn't take as long to update the tree and the context switch module fails faster. The connection dialog adds this capability automatically starting with expecco 22.1.

== No Action on Click ==
The block to click on an element is successful, but no action was performed on the device.
:This can happen if the element is hidden by another element and therefore clicking on the element is not possible. In this case, Appium does not throw an error, but simply nothing happens. If you would like to make a click at the position of the element anyways, even if it is hidden, use the block ''Tap'' instead and pass the location of the element to it (''Get Location''). If instead you want to check before a click whether the element is hidden at this moment, try whether the properties ''Is Displayed'' or ''Is Enabled'' might help you.

== No Update After Action ==
An action was triggered on the recorder and a block has been recorded, but the recorder still shows the old image.
:The recorder doesn't show a live image of the device, but only a snapshot. After an action has been executed, the recorder will update automatically. However, it can happen, that the image has already been updated before the effects of the action are fully completed on the device. In this case you should update the recorder by hand using the icon with the blue arrows. Since expecco 20.2 you can also enable automatic updates for this case. See also the description for the [[#Recorder|recorder]].

== Attribute "clickable" is wrong ==
An element has for the attribute/property "''clickable''" the value "''false''", but is actually clickable.
:The attribute "''clickable''" has to be set explicitly by the app developer and does not affect the behavior of the app. You should generally disregard this attribute in your tests. Unfortunately, many apps exist where the programmer was "lazy" about this.

==Connecting Fails==
If the connection to the Appium server fails, you will receive an error message in expecco similar to the one shown below.

[[File:MobileTestingVerbindungsfehler.png]]

Here you can see the type of error that has occurred. Click on "''Details''" to get more information. Possible errors are:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:The specified server is not running or is not reachable. Check the server address.
*''org.openqa.selenium.WebDriverException''
:Read the message after ''Original Error'' in the first line of the details:
:*''Unknown device or simulator UDID''
::Either the device is not connected properly or the udid is not correct.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::This error can have various causes. Either the WebDriverAgent could actually not be built because the signing settings are wrong or the appropriate provisioning profile is missing. Please read the section about [[#Signing|Signing]]. It is also possible that the WebDriverAgent cannot be started on the device, for example because an alert is in the foreground or you did not trust the developer.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::The specified app cannot be installed on the iOS device because it is not entered in the app's Provisioning Profile.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.''
::The path to the app is wrong. Make sure that the file is located in the specified path on your Mac.
:*''packageAndLaunchActivityFromManifest failed.''
::The specified ''apk'' file is probably broken.
:*''Could not find app apk at [...]''
::The path to the app is wrong. Make sure that the ''apk'' file is located in the specified path.

If the error is not due to one of the causes listed above, the automation applications on the device may no longer function properly. In this case it helps to uninstall them from the mobile device. They are then automatically reinstalled the next time a connection is established.

*For iOS devices, this is the WebDriverAgent, which you can simply uninstall from the home screen. This usually solves problems caused by changing the used Mac or the Xcode version.

*For Android devices, it is the UIAutomator2; here, a problem occurs sporadically on some devices, the cause is currently unknown to us. To uninstall, on the device, navigate to "''Settings''" > "''Applications''"* and search the list for the following entries:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Click on the respective application and then on "''Uninstall''".
*''The corresponding entry may have a slightly different name on some devices.''

If this doesn't help, check the output of the Appium server. For a server started by expecco, you can find the log in the list of [[#Running_Appium_Servers|Running Appium Servers]].

==I do not have a Mac==
Maybe this site will help you: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin

2025-02-17T09:39:52Z

Matilk: new supplement

'''Deutsche Version''' | [[Mobile_Testing_Plugin/en|English Version]]

= Einleitung =
Mit dem ''Mobile Testing Plugin'' können Anwendungen auf Android- und iOS-Geräten getestet werden. Dabei ist es egal, ob reale mobile Endgeräte oder emulierte Geräte verwendet werden. Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests unterstützt. Zudem ist damit das Aufzeichnen von Testabläufen möglich.

Zur Verbindung mit den Geräten wird [http://appium.io/ Appium] verwendet. Appium ist ein freies Open-Source-Framework zum Testen und Automatisieren von mobilen Anwendungen.

Zur Einarbeitung in das Mobile Plugin empfehlen wir das [[Mobile_Testing_Tutorial|Tutorial]] zu bearbeiten. Dieses führt anhand eines Beispiels Schritt für Schritt durch die Erstellung eines Testfalls und erklärt die nötigen Grundlagen.

= Installation und Aufbau =
Zur Verwendung des Mobile Testing Plugins müssen Sie expecco inkl. des Plugins Mobile Testing installiert haben und Sie benötigen die entsprechenden Lizenzen. expecco kommuniziert mit den Mobilgeräten über einen Appium-Server, der entweder auf demselben Rechner wie expecco läuft, oder auf einem zweiten Rechner. Dieser muss für expecco erreichbar sein.

==Installationsübersicht==

'''Rechner, auf dem expecco läuft:'''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem Android-Geräte angeschlossen sind:'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Android SDK'', dieses erhalten Sie ebenfalls mit dem Mobile Testing Supplement''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem iOS-Geräte angeschlossen sind2):'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement für Mac OS installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Xcode ''in einer Version, die die verwendete iOS-Version unterstützt, erhältlich über den Apple App Store''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
* Apple-Entwickler-Zertifikat mit zugehörigem privaten Schlüssel ''(zum Signieren des WebDriverAgents)''
* Provisioning Profile mit den verwendeten Mobilgeräten

Je nach Aufbau können die oben genannten Rechner auch das selbe Gerät sein. expecco kann sich sowohl über das Netzwerk mit einem entfernten Appium-Server und dort angeschlossenen Mobilgeräten verbinden, als auch lokal selbst einen Appium-Server starten und diesen mit lokalen Mobilgeräten verwenden. Einige Funktionen von expecco, die die Erstellung von Testfällen erleichtern, sind jedoch nur verfügbar, wenn die Mobilgeräte am selben Rechner angeschlossen sind, auf dem auch expecco läuft. Ein möglicher Aufbau kann daher wie in folgender Abbildung aussehen:

[[Datei:MobileTestingAufbau.png | 400px]]

Im Folgenden wird die Installation von Appium und anderer nötiger Programme für Windows und Mac OS erklärt.

1): Zum Zeitpunkt der Erstellung dieses Dokuments wurden Versionen bis 11 auf Funktion verifiziert. Neuere Versionen sollten - sofern nicht grundlegende Änderungen von Oracle vorgenommen wurden, ebenfalls funktionieren.

2): Beachten Sie, dass aufgrund der Voraussetzungen (keine Anbindung an nicht-Apple Geräte verfügbar) iOS-Geräte nur von einem Mac aus angesteuert werden können. Sie benötigen also einen Mac als "Vermittler" (siehe auch unten: [[#Ich habe keinen Mac | "Ich habe keinen Mac"]])

== Windows ==
Am einfachsten installieren Sie alles mit unserem Mobile Testing Supplement1. In neueren Versionen ist allerdings aufgrund geänderter Lizenzbedingungen seitens Oracle kein JDK mehr enthalten, sodass sie dieses zusätzlich installieren müssen. Sie können natürlich Appium auch direkt installieren, um die Version zu verwenden, die Sie möchten. Um dann einen Appium-Server mit expecco starten zu können, muss allerdings eine entsprechende Batchdatei vorhanden sein und in den [[Mobile_Testing_Plugin#Konfiguration_des_Plugins|Einstellungen]] angegeben werden. Verbindungen können aber auch zu anderen laufenden Appium-Servern aufgebaut werden.
*'''expecco 24.2''': [https://download.exept.de/transfer/h-expecco-24.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 2.0.1.1]
:Umstieg auf Appium 2. Der Appium-Server startet standardmäßig ohne den Path ''wd/hub/''.
:Appium 2.11.0
:Node 20.9.0
:adb 1.0.41 aus platform-tools 35.0.1
*expecco 24.1: [https://download.exept.de/transfer/h-expecco-24.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.3]
:Im Vergleich zum Vorgänger aktualisierte Chromedriver Versionen.
*expecco 23.2: [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Im Vergleich zum Vorgänger aktualisierte Chromedriver Versionen.
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Gleiche Versionen wie der Vorgänger, aber der Installer erlaubt nun, Appium zum Autostart hinzuzufügen.
*expecco 22.2 und 22.1: [https://download.exept.de/transfer/h-expecco-22.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 aus platform-tools 33.0.2
:''* Wir haben Appium um die Capability'' chromedriverStartTimeout ''erweitert, um schneller einen Timeout zu bekommen, wenn der Chromedriver nicht gestartet werden kann. (siehe [[#startChromedriverTimeout|Probleme und Lösungen]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Enthält die Appium-Version 1.22.0, Node ist weiterhin in der Version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Nur kleine Änderungen im Vergleich zur vorigen Version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und node 12 verwendet.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:Dieses installiert Appium in der Version 1.12.0 und enthält nun zusätzlich build-tools der Version 28.0.3 im android-sdk. Ansonsten ist es gleich wie die vorige Version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:Dieses installiert Appium in der Version 1.8.1. Außerdem bietet das Supplement auch an, ''Android Debug Bridge'' und ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) zu installieren. Damit sind Treiber für ein breites Spektrum an Android-Geräten abgedeckt, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen. Ein '''JDK ist (aufgrund geänderter Lizenzbedingungen seitens Oracle) nicht mehr enthalten''', dieses müssen Sie selbst herunterladen, z.B. von [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: wie expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.6.4. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.4.16. Während der Installation wird die grafische Oberfläche von Appium gestartet, dieses Fenster können Sie sofort wieder schließen. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.

Wenn expecco Mobilgeräte verwenden soll, die an einem anderen Rechner angeschlossen sind, müssen Sie dort einen Appium-Server starten. Dies können Sie mit der Datei <code>appium_standalone.cmd</code> tun. Der Server wird dann mit dem Standard-Port 4723 gestartet. Falls Sie eine andere Portnummer verwenden wollen, starten Sie den Server mit

appium_standalone.cmd -p <portnummer>

Der Server ist bereit, sobald die Zeile
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
angezeigt wird, wobei Sie am Ende die verwendete Portnummer ablesen können.

Beim ersten Starten von Appium – sowohl im Standalone als auch gestartet von expecco – kann es vorkommen, dass die Windows-Firewall den Node-Server blockiert. Lassen Sie den Zugriff zu, sonst kann Appium nicht gestartet werden.

1) Sie können natürlich auch die Command Line Tools (adb, sdkmanager, avdmanager etc.) einer vorhandenen Android Studio Version verwenden, sowie Appium separat installieren.
Da sich diese Tools regelmäßig ändern, und es in der Vergangenheit zu Inkompatibilitäten und Fehlern nach Releasewechseln kam, empfehlen wir zu Beginn, das mitgelieferte Paket zu verwenden. Dies ist möglicherweise nicht das aktuellste, wurde aber auf Lauffähigkeit getestet.

Falls das Android Mobilgerät an einem entfernen Rechner angeschlossen ist,
können Sie den aktuellen Bildschirminhalt z.B. mit dem [https://github.com/Genymobile/scrcpy scrcpy] tool live mitverfolgen.

== Mac OS (nicht erforderlich für Android-Tests)==
Hinweis: Wenn Sie nicht vorhaben, iOS-Geräte (iPhone, iPad, etc.) zu testen, können Sie das Folgende ignorieren. '''Der Apple-Rechner sowie das Mac-Setup werden für Android-Geräte nicht benötigt'''.

=== Xcode ===
Zur Automatisierung mit iOS-Geräten wird [https://developer.apple.com/xcode/ Xcode] benötigt. Sie erhalten dieses über den App Store. Dabei ist darauf zu achten, dass die Version zu den getesteten iOS-Versionen passt.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
Diese Tabelle gibt nur eine vereinfachte Übersicht, lesen Sie besser unter [https://xcodereleases.com/ Xcode Releases] oder [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode-Versionen] welche Version Sie brauchen. Für neue iOS Minor-Versionen gibt es in der Regel auch ein Update für Xcode, z.B. brauchen Sie für iOS 10.2 mindestens Xcode 8.2, für iOS 10.3 mindestens Xcode 8.3 usw.
Wenn Sie also auf eine neuere iOS-Version wechseln, benötigen Sie in der Regel auch eine neuere Xcode-Version. Neuere Versionen von Xcode laufen möglicherweise nicht auf älteren Betriebssystemen, was wiederum eine Aktualisierung des Betriebssystems erforderlich machen kann. Falls Sie auch ältere iOS-Versionen testen wollen kann es sinnvoll sein, die entsprechenden Xcode-Versionen parallel zu installieren.

=== Appium ===
Der Appium-Server kann entweder als Kommandozeilen-Anwendung installiert werden oder über [https://github.com/appium/appium-desktop Appium Desktop] verwendet werden, welcher den Server über ein GUI zur Verfügung stellt. Mittlerweile gibt es auch Appium 2.0, was wir aber bisher noch nicht mit expecco getestet haben und daher nicht empfehlen.

==== Appium Desktop ====
Laden Sie die neueste Version von [https://github.com/appium/appium-desktop/releases/ Appium Desktop] herunter. Für den Mac nehmen Sie am besten die dmg-Datei und installieren sie in den Anwendungen. Beim Starten der Anwendung ''Appium Server GUI'' erhalten Sie wahrscheinlich eine Fehlermeldung, dass es aus Sicherheitsgründen nicht möglich ist. Öffnen Sie dann das Kontextmenü auf der Anwendungsdatei (Rechtsklick bzw. Strg + Klick) und wählen Sie dort ''Öffnen'' aus. Bestätigen Sie dann, dass Sie die Anwendung wirklich öffnen wollen. Fortan können Sie die Anwendung normal öffnen.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Ab Xcode 14 gibt es Probleme beim Signieren des WebDriverAgents, den Appium zur Automatisierung auf das Gerät spielt. Dadurch ist mit der Version 1.22.3-4 von Appium Desktop kein Verbindungsaufbau möglich. Das Problem ist in neueren Versionen des WebDriverAgents behoben, es gibt aber aktuell noch keine Version von Appium Desktop, die eine solche Version enthält (Stand November 2022). Sie können aber manuell eine neue Version herunterladen (z.B. 4.10.2) und die Dateien in Appium ersetzen. Laden Sie dazu von der [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent Download-Seite] eine der beiden Archivdateien (zip oder tar.gz) mit dem Source Code herunter. Öffnen und entpacken Sie dann diese Datei. Den Inhalt des Ordners WebDriverAgent-4.10.2 müssen Sie nun nach

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

kopieren. Wenn Sie über den Finder dorthin navigieren, machen Sie auf die Anwendung ''Appium Server GUI'' einen Kontextklick (Rechtsklick bzw. Strg + Klick) und wählen Sie im Menü ''Paketinhalt anzeigen''. Ersetzen Sie alle Dateien, die bereits mit gleichem Namen enthalten sind.

==== Appium über npm installieren ====
Sie können Appium auch über npm (Node Package Manager) installieren. Dazu müsen Sie erst node/npm installieren. Das geht mit [https://github.com/nvm-sh/nvm nvm] (Node Version Manager) was Sie von Github bekommen. Falls die folgende Installationsanleitung bei Ihnen nicht funktionieren sollte, finden Sie dort ausführlichere Informationen im [https://github.com/nvm-sh/nvm#readme Readme].

Öffnen Sie ein Terminal-Fenster. Klonen Sie dann das Github-Repository von nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
und laden Sie es
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Führen Sie danach
command -v nvm
aus, um zu testen, ob es funktioniert hat. Es sollte ''nvm'' ausgegeben werden. Kommt keine Antwort, führen Sie
touch ~/.zshrc
aus, und versuchen Sie es erneut.

Nun können Sie node mit dem folgenden Befehl installieren.
nvm install 16.15.1
Da es mit der aktuellen Version von node Probleme beim Installieren von Appium gibt, empfehlen wir diese Version.

Nachdem node installiert ist, können Sie Appium darüber installieren:
npm install -g appium

Den Appium-Server können Sie nun einfach über den Befehl
appium
starten. Die Ausgabe erfolgt dann direkt im Terminal.

Auch bei dieser Version gibt es das Problem bei der Signierung des WebDriverAgents, wie bei [[#Appium_Desktop | Appium Desktop]] beschrieben. Laden Sie also auch in diesem Fall eine neuere Version des WebDriverAgents herunter und ersetzen Sie die alten Dateien. Diese finden Sie unter
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
Ältere Appium-Versionen stellen wir Ihnen über das Mobile Testing Supplement für Mac OS zur Verfügung, mit dem Sie es einfach installieren können:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.2)]
:Enthält Appium Version 1.18.3 und verwendet node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.0)]
:Nur wenige Änderungen im Vergleich zur vorigen Version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.98)]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und es wird node 12 verwendet.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.96)]
:Diese Version enthält Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.94)]
:Diese Version enthält Appium 1.8.0.

* expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.0.94)]
:Diese Version enthält Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement für Mac OS]
:Diese Version entält Appium 1.4.16.

Nachdem Herunterladen des Supplements, können Sie es in ein Verzeichnis Ihrer Wahl (z. B. Ihr Home-Verzeichnis) verschieben und dort entpacken. Ein geeigneter Befehl in einer Shell könnte wie folgt aussehen, passen Sie dabei die Versionsnummer entsprechend an:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

Wenn Sie Ihre Standard-Xcode-Installation verwenden wollen, können Sie Appium direkt über die Datei im ''bin''-Verzeichnis mit der entsprechenden Versionsnummer starten:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Falls Sie ein anderes Xcode als das als Standard konfigurierte verwenden wollen, müssen Sie Appium den entsprechenden Pfad über die Umgebungsvariable ''DEVELOPER_DIR'' angeben.
Wenn Sie Xcode z. B. in ''/Applications/Xcode-11.3.app'' installiert haben, müssten Sie Appium so starten:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Was als Standard-Xcode-Installation gesetzt ist, zeigt der Befehl:

xcode-select -p

Wenn Appium Ihre Xcode-Installation nicht findet, erscheint beim Verbinden eine Fehlermeldung in der Art:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
Starten Sie in diesem Fall Appium erneut, unter Angabe eines gültigen ''DEVELOPER_DIR''.

==== WebDriverAgent-Signierung ====
Zur Automatisierung lädt Appium eine App namens WebDriverAgent auf das Gerät und muss sie dafür signieren können. Dazu brauchen Sie einen Apple-Account und ein entsprechendes Zertifikat. Zur Evaluierung können Sie einen kostenlosen Account verwenden. Dieser hat den Nachteil, dass erstellte Profile nur eine Woche gültig sind und danach neu erstellt werden müssen. Seien Sie auch vorsichtig, wenn Sie sich den Account teilen, da es vorkommen kann, dass Zertifikate widerrufen werden oder durch automatische Generierung ungültig werden. Als Folge können bereits signierte Apps nicht mehr verwendet werden.

Wenn Sie bereits ein entsprechendes Zertifikat mit dem zugehörigen privaten Schlüssel in Ihrer [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac haben, können Sie den WebDriverAgent automatisch signieren lassen. Ansonsten empfiehlt es sich, die Signierung über Xcode einzustellen und zu verwalten.

Schließen Sie zuerst das Gerät, das Sie verwenden möchten, über USB an den Mac an. Stellen Sie sicher, dass sich der Mac und das Gerät im selben Netzwerk befinden, ansonsten kann es beim Verbindungsaufbau mit Appium zu Problemen kommen. Starten Sie Xcode und öffnen Sie ''Preferences''. Wechseln Sie zur Seite der Accounts und legen Sie einen Eintrag mit Ihrem Account an. Anschließend können Sie auf ''Manage Certificates...'' klicken, um die Zertifikate zu sehen, die zu diesem Account gehören. Zum Ausführen von Tests benötigen Sie ein iOS-Development-Zertifikat und den dazugehörigen privaten Schlüssel. Wenn Sie noch keines besitzen, erstellen Sie eines. Wenn Sie bereits eines haben, aber es nicht in Ihrem Schlüsselbund vorhanden ist (erkennbar an dem Hinweis "Not in Keychain"), können Sie es importieren. Das können Sie über die [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac machen, wenn Sie es zuvor aus dem Schlüsselbund exportiert haben, in dem es sich befindet. Das Zertifikat mit dem zugehörigen Schlüssel sollte sich im Schlüsselbund ''Anmeldung'' befinden. Dort kann es als PKCS#12-Datei (Endung typischerweise .p12) exportiert werden. Um ein Zertifikat in Ihren Schlüsselbund zu importieren, wählen Sie im Menü ''Ablage'' die Option ''Objekte importieren''. Falls Sie nicht wissen, wo das Zertifikat gespeichert ist, können Sie es in Xcode auch widerrufen und in Ihrem Schlüsselbund neu anlegen. Machen Sie das jedoch nur, wenn Sie wissen, dass das alte Zertifikat nicht mehr in Verwendung ist, da es danach nicht mehr benutzt werden kann. Nun sollte Ihr Schlüsselbund ein iOS-Development-Zertifikat enthalten.


Öffnen Sie nun das WebDriverAgent-Projekt in Xcode. Wenn Sie das Mobile Testing Supplement installiert haben, finden Sie es in dessen Verzeichnis unter
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
Wenn Sie Appium Desktop installier haben, finden Sie es unter
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''
Sie können einfach im Finder zu der Xcode-Project-Datei navigieren und Sie über einen Doppelklick öffnen. Beachten Sie dabei, dass Sie dabei auf die Anwendung Appium Server GUI einen Kontextklick (Rechtsklick bzw. Strg + Klick) machen und im Menü ''Paketinhalt anzeigen'' auswählen müssen, um in deren Unterverzeichnis zu gelangen.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Wählen Sie ''WebDriverAgentLib'' und die Seite ''Signing & Capabilities'' aus. Setzen Sie dort im Abschnitt ''Signing'' die Option ''Automatically manage signing'' und wählen Sie dann ein Team aus. Wechseln Sie nun zu ''WebDriverAgentRunner'' und tun Sie dort dasselbe.

Durch das Setzen des Teams sollten die Fehler für den WebDriverAgentRunner verschwinden. Sollte Xcode kein passendes Provisioning Profile für die Bundle ID ''com.facebook.WebDriverAgentRunner'' erstellen können, können Sie diese anpassen, dass sie zu Ihrem Zertifikat passt. Danach können Sie Xcode beenden oder auch, wie weiter unten beschrieben, direkt den Build über Xcode starten, damit das Projekt bereits gebaut ist, wenn Appium es verwenden möchte.

Wenn Sie sich nun von expecco eine Verbindung zu Ihrem Gerät aufbauen, wird der WebDriverAgent darauf installiert und gestartet, um anschließend zur zu testenden App zu wechseln. Eventuell muss auf dem Gerät muss der Ausführung des WebDriverAgents vertraut noch werden. Ein Anzeichnen dafür kann sein, dass die App WebDriverAgent zwar auf dem Gerät erscheint und zu starten versucht, danach aber wieder deinstalliert wird. Öffnen Sie dazu während des Verbindungsaufbaus auf dem Gerät in die Einstellungen und dort unter ''Allgemein'' den Eintrag ''Geräteverwaltung''. Dieser Eintrag ist nur sichtbar, wenn eine Entwickler-App auf dem Gerät installiert ist. Sie müssen daher möglicherweise warten, bis der WebDriverAgent installiert ist, bevor der Eintrag erscheint. Wählen Sie dort den Eintrag Ihres Apple-Accounts und vertrauen Sie ihm. Da der WebDriverAgent wieder deinstalliert wird, wenn der Start nicht funktioniert hat, müssen Sie dies während des Verbindungsaufbaus tun. Falls Ihnen das zu hektisch ist, können Sie auch folgenden Code ausführen:

<nowiki>xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test</nowiki>
bzw.
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

Damit wird der WebDriverAgent auf dem Gerät installiert ohne dass er wieder gelöscht wird.

Wenn es Probleme beim Installieren des WebDriverAgents gibt, können Sie auch versuchen, den Build über Xcode zu starten. Stellen Sie sicher, dass das richtige Target ''WebDriverAgent'' ausgewählt ist. Fehlermeldungen in Xcode zeigen vielleicht einfacher, wo das Problem liegt. Manchmal hilft es auch, es ein zweites Mal zu versuchen, weil es möglicherweise beim ersten Mal zu lange gedauert hat und abgebrochen wurde. Es kann sein, dass Sie während des Builds mehrmals aufgefordert werden, das Passwort für Ihren Schlüsselbund anzugeben.

[[Datei:WebDriverAgentCodesign.png]]

Lesen Sie auch die Dokumentation von Appium zum [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Aufsetzen von Tests mit iOS-Geräten]. In der [https://support.apple.com/en-us/HT204460 Dokumentation von Apple] finden Sie nähere Informationen zum Installieren und Vertrauen von Apps.

Ist der WebDriverAgent einmal auf dem Gerät installiert, wird er für spätere Verbindungen wieder verwendet und der Verbindungsaufbau sollte schneller funktionieren. Ebenso liegt dann die signierte Version bereits auf Ihrem Mac und muss nicht erneut gebaut werden, was die Verbindung zu weiteren Geräten ebenfalls beschleunigt. Wenn Sie wissen, dass bei Ihrem Verbindungsaufbau der WebDriverAgent erst noch signiert und gebaut werden muss, ist es ratsam, die Capability ''wdaLaunchTimeout'' zu setzen. Dieser Timeout, wie lange auf den Start der WebDriverAgents auf dem Gerät gewartet werden soll, liegt standardmäßig bei 60000$nbsp;ms. Der Build dauert aber häufig über eine Minute, sodass der Versuch zum Verbindungsaufbau dann abgebrochen wird. Ein Wert von 120000 hat sich hier als besser erwiesen.

== Konfiguration des Plugins ==
Bevor Sie loslegen, sollten Sie die Einstellungen des Mobile Testing Plugins überprüfen und ggf. anpassen.

Öffnen Sie im Menü den Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" den Eintrag "''Mobile Testing''" (s. Abb.). Standardmäßig werden diese Pfade automatisch gefunden (1). Um einen Pfad manuell anzupassen, deaktivieren Sie den entsprechenden Haken rechts davon. Sie erhalten in einer Drop-down-Liste einige Pfade zur Auswahl. Ist ein eingetragener Pfad falsch oder kann er nicht gefunden werden, wird das Feld rot markiert und es erscheint ein diesbezüglicher Hinweis. Stellen Sie sicher, dass alle Pfade richtig angegeben sind.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Konfiguration des Plugins]]

*'''appium''': Geben Sie hier den Pfad zur ausführbaren Datei an mit der Appium in der Kommandozeile gestartet werden kann. Unter Windows wird diese Datei in der Regel "<code>appium.cmd</code>" heißen. Dieser Pfad wird benutzt, wenn expecco einen Appium-Server startet.
*'''node''': Geben Sie hier den Pfad zur ausführbaren Datei an, die Node (auch "Node.js") startet. Dieser Pfad wird beim Starten eines Servers an Appium weitergegeben, damit Appium ihn unabhängig von der PATH-Variablen findet. Unter Windows heißt diese Datei in der Regel "<code>node.exe</code>".
*'''JAVA_HOME''': Geben Sie hier den Pfad zu einem JDK an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden. Um einzustellen, welches Java von expecco verwendet werden soll, setzen Sie diesen Pfad in den Einstellungen für die Java Bridge.
*'''ANDROID_HOME''': Geben Sie hier den Pfad zu einem SDK von Android an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden.
*'''adb''': Hier steht der Pfad zum adb-Befehl. Unter Windows heißt die Datei adb.exe. Diese wird von expecco beispielsweise verwendet, um die Liste der angeschlossenen Geräte zu erhalten. Diesen Pfad sollten Sie automatisch wählen lassen, da dann der Befehl im ANDROID_HOME-Verzeichnis verwendet wird. Dieser wird auch von Appium verwendet. Falls expecco und Appium jedoch verschiedene Versionen von adb verwenden kann es zu Konflikten kommen.
*'''android.bat''': Diese Datei wird nur benötigt, um damit den AVD und den SDK Manager zu starten. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.
*'''aapt''': Geben Sie hier den Pfad zum aapt-Befehl an. Unter Windows heißt diese Datei ''aapt.exe''. expecco verwendet aapt nur im Verbindungseditor, um das Paket und die Activities einer apk-Datei zu lesen. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | Konfiguration des JDKs]]

Ab expecco 2.11 gibt es das Feld ''Team-ID''. Wenn Sie iOS-Tests ausführen, tragen Sie hier die Team-ID Ihres Zertifikats ein. Diese wird für jede iOS-Verbindung verwendet, außer Sie setzen den Wert im Einzelfall in den Verbindungseinstellungen um. Wie Sie die Team-ID erhalten, lesen Sie im Abschnitt zur [[#Signierung|Signierung]] ber der Installation auf Mac OS. Mit expecco 2.10 können Sie die Team-ID nur für jede Verbindungseinstellung extra als Capability eintragen. Dazu müssen Sie jedoch die [[#Erweiterte_Ansicht|erweiterte Ansicht]] verwenden. Geben Sie hier die Capability ''xcodeOrgId'' an und setzen Sie als Wert die Team-ID des Zertifikats.

Die Einstellung zur Serveradresse unten auf der Seite bezieht sich auf das Verhalten des Verbindungseditors. Dieser prüft am Ende, ob die Serveradresse auf ''/wd/hub'' endet, da dies die übliche Form ist. Falls nicht, wird in einem Dialog gefragt, wie darauf reagiert werden soll. Das festgelegte Verhalten kann hier eingesehen und verändert werden.

Wechseln Sie ebenfalls zum Eintrag ''Java Bridge'' (s. Abb.). Hier muss der Pfad zu Ihrer Java-Installation angegeben werden, die von expecco benutzt wird. Tragen Sie hier ein JDK ein. Falls Sie unter Windows das aus dem Mobile Testing Supplement verwenden möchten, lautet der Pfad
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
Sie können auch die Systemeinstellungen verwenden.

== Android-Gerät vorbereiten ==
Wenn Sie ein Android-Gerät unter Windows anschließen benötigen Sie möglicherweise noch einen adb-Treiber für das Gerät. Einen passenden Treiber finden Sie üblicherweise auf der jeweiligen Webseite des Herstellers. Haben Sie den Universal-Treiber aus dem Mobile Testing Supplement installiert, sollte für die meisten Geräte bereits alles funktionieren. In einigen Fällen versucht auch Windows automatisch einen Treiber zu installieren, wenn Sie das Gerät zum ersten mal anschließen.
 
===USB-Debugging Einschalten===
'''Achtung:'''
Bevor Sie ein Mobilgerät mit dem Appium-Plugin ansteuern können, müssen Sie für dieses Debugging erlauben!

Für Android-Geräte finden Sie diese Option in den Einstellungen unter ''[https://www.droidwiki.org/wiki/Entwickleroptionen Entwickleroptionen]'' mit dem Namen ''[https://www.droidwiki.org/USB-Debugging USB-Debugging]''. Falls die Entwickleroptionen nicht angezeigt werden, können Sie diese freischalten, indem Sie unter "''Über das Telefon''" siebenmal auf "''Build-Nummer''" tippen.

===Wach bleiben Aktivieren===
Aktivieren Sie auch die Funktion ''Wach bleiben'', damit das Gerät nicht während der Testerstellung oder -ausführung den Bildschirm abschaltet.

Aus Sicherheitsgründen muss USB-Debugging für jeden Computer einzeln zugelassen werden. Beim Verbinden des Geräts mit dem PC über USB müssen Sie dabei am Gerät der Verbindung zustimmen. Falls Sie dies für Ihren Computer noch nicht getan haben, aber auf dem Gerät kein entsprechender Dialog erscheint, kann es helfen, das Gerät aus- und wieder einzustecken. Das kann insbesondere dann passieren, wenn Sie den ADB-Treiber installiert haben während das Gerät bereits über USB angeschlossen war. Falls auch das nicht hilft, öffnen Sie die Benachrichtigungen, indem Sie sie vom oberen Bildschirmrand herunter ziehen. Dort finden Sie die USB-Verbindung und Sie können die Optionen dazu öffnen. Wählen Sie einen anderen Verbindungstypen aus; in der Regel sollten MTP oder PTP funktionieren.

Sie können auch auf einem Emulator testen. Dieser muss nicht gesondert vorbereitet werden, da er bereits für USB-Debugging ausgelegt ist. Es ist sogar möglich, einen Emulator bei Testbeginn zu starten.

Um zu überprüfen, ob ein Gerät, das Sie an Ihren Rechner angeschlossen haben, verwendet werden kann, öffnen Sie den [[#Verbindungseditor|Verbindungseditor]]. Das Gerät sollte dort angezeigt werden.

=== Verbindung über WLAN ===
Es ist auch möglich, Android-Geräte über WLAN zu verbinden. Für Geräte mit Android 11 oder neuer ist dies direkt über WLAN möglich, im anderen Fall müssen Sie das Gerät zuerst über USB verbinden. Ab expecco 22.1 können Sie eine WLAN-Verbindung über den [[Mobile Testing Plugin#Verbindungseditor|Verbindungseditor]] aufbauen. Ansonsten ist es auch über die Eingabeaufforderung möglich.
==== Drahtlos verbinden über die Eingabeaufforderung mit expecco Versionen vor 22.1 (ab Android 11) ====
Mit expecco ab Version 22.1 funktioniert das einfacher über den Verbindungseditor.

Erlauben Sie in den Entwickleroptionen des Geräts Debugging über WLAN und öffnen Sie dessen Optionen. Sie müssen zuerst das Gerät mit dem Rechner koppeln. Wählen Sie dazu "''Gerät mit einem Kopplungscode koppeln''", um einen Kopplungscode und eine IP-Adresse mit Port zu erhalten. Öffnen Sie dann auf dem Rechner die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb pair <IP-Adresse des Geräts>:<Kopplungsport></nowiki>
wobei Sie <tt><IP-Adresse des Geräts>:<Kopplungsport></tt> durch die auf dem Gerät angezeigte IP-Adresse & Port ersetzen. Danach werden Sie aufgefordert, den Kopplungscode einzugeben. Wenn alles geklappt hat, sollte sich das Popup auf dem Gerät schließen und der Rechner als gekoppeltes Gerät angezeigt werden. Geben Sie dann in der Eingabeaufforderung ein:
<nowiki>adb connect <IP-Adresse des Geräts>:<Debug-Port></nowiki>
Die IP-Adresse ist hier noch die gleiche wie beim Koppeln, aber der Port ist ein anderer. Beides wird als IP-Adresse & Port auf dem Gerät angezeigt. Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie entweder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden. Häufig wird beim Neustart des Geräts auch die Erlaubnis für das Debugging über WLAN wieder zurückgesetzt und der verwendete Port ändert sich. Die Kopplung bleibt aber bestehen und muss beim nächsten Verbinden nicht noch einmal durchgeführt werden.

==== WLAN Verbindung über USB starten (Android 10 und früher) ====
Verbinden Sie zunächst das Gerät über USB mit dem Rechner. Öffnen Sie dann die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb tcpip 5555</nowiki>
Damit lauscht das Gerät auf eine TCP/IP-Verbindung an Port 5555. Sollten Sie mehrere Geräte angeschlossen oder Emulatoren laufen haben, müssen Sie genauer angeben, welches Gerät Sie meinen. Geben Sie in diesem Fall ein:
<nowiki>adb devices -l</nowiki>
Sie erhalten eine Liste aller Geräte, wobei die erste Spalte deren Kennung ist. Schreiben Sie dann stattdessen
<nowiki>adb -s <Gerätekennung> tcpip 5555</nowiki>
mit der Gerätekennung des gewünschten Geräts. Sie können die USB-Verbindung nun trennen. Jetzt müssen Sie die IP-Adresse Ihres Gerätes in Erfahrung bringen. Sie finden diese üblicherweise irgendwo in den Einstellungen des Geräts, beispielsweise beim Status oder in den WLAN-Einstellungen. Geben Sie dann ein:
<nowiki>adb connect <IP-Adresse des Geräts></nowiki>
Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie wieder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden.

=== Verbindung zu einem Emulator ===
Sie benötigen dazu den Emulator selbst, sowie mindestens ein AVD (Android Virtual Device). Hinweise zu Installation finden Sie in der [https://developer.android.com/studio/run/emulator Android Studio Dokumentation].

Wenn Sie Android Studio bereits mit den Defaulteinstellungen installiert haben 1), sollte der Emulator bereits mitinstalliert sein. Falls nicht, wählen Sie in Android Studio "''Configure''" - "''SDK Manager''" - "''Android SDK''" - "''SDK Tools''" - ''Android Emulator''", sowie dort die "''Platform Tools''".
Alternativ geht das auch über die Kommandzeile mit dem "sdkmanager" Kommando.

Als nächstes benötigen Sie mindestens ein AVD; auch dies geht am einfachsten über den Dialog in Android Studio:
wählen sie "''Configure''" - "''AVD Manager''" und folgen den Anweisungen (Deviceauswahl, Platform und Android Version).

Auch wenn Sie den Emulator automatisieren benötigen sie Appium; installieren Sie dieses entweder mit dem Mobile Testing Supplement, oder direkt von der Appium homepage (https://github.com/appium/appium-desktop/releases).

1)Android Studio selbst wird nicht von expecco benötigt; es bietet aber kompfortable Dialoge zum Installieren von Paketen und AVDs.

== iOS-Gerät und App vorbereiten ==
Das Ansteuern von iOS-Geräten ist nur über einen Mac möglich. Lesen Sie daher auch den Abschnitt zur [[#Mac_OS|Installation unter Mac OS]].

Bevor Sie ein Mobilgerät mit dem Mobile Testing Plugin ansteuern können, müssen Sie für iOS-Geräte ab iOS 8 Debugging erlauben. Aktivieren Sie dazu die Option ''Enable UI Automation'' unter dem Menüpunkt ''Entwickler'' in den Einstellungen des Geräts. Falls Sie den Eintrag ''Entwickler'' in den Einstellungen nicht finden, gehen Sie wie folgt vor: Schließen Sie das Gerät über USB an den Mac an. Dabei müssen Sie ggf. am Gerät noch der Verbindung zustimmen. Starten Sie Xcode und wählen Sie dann in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie dort Ihr Gerät aus. Danach sollte der Eintrag ''Entwickler'' in den Einstellungen auf dem Gerät auftauchen. Dazu müssen Sie möglicherweise die Einstellungen beenden und neu starten.

[[Datei:Alert.png | thumb | 270px | Beispiel für einen Alert unter iOS]]
Ein Verbindungsaufbau zu dem Gerät ist nicht möglich solange es bestimmte Alerts zeigt. Ein solcher Alert kann z. B. erscheinen wenn FaceTime aktiviert ist, indem ein Hinweis auf anfallende SMS-Gebühren angezeigt wird (siehe Screenshot). Achten Sie darauf, das Gerät so zu konfigurieren, dass es im Leerlauf keine solchen Alerts zeigt.

=== expecco 2.11 und später ===
Sie können beliebige Apps testen, die auf dem verwendeten Gerät lauffähig oder bereits installiert sind. Wenn die App als Development-Build vorliegt, muss die UDID des Geräts in der App hinterlegt sein. In jedem Fall muss der WebDriverAgent für das Gerät signiert werden. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]] unter Mac OS.

Falls Sie in einem Test den Home-Button verwenden wollen, müssen Sie auf dem Gerät AssistiveTouch aktivieren. Sie finden diese Option in den Einstellungen unter ''Allgemein'' > ''Bedienungshilfen'' > ''AssistiveTouch''. Platzieren Sie dann das Menü in der Mitte des oberen Bildschirmrands. Sie können das Drücken des Home-Buttons dann mit dem entsprechenden Menüeintrag im Recorder aufzeichnen oder direkt den Baustein ''Press Home Button'' benutzen.

=== expecco 2.10 ===
Die App, die Sie verwenden wollen, muss als Development-Build vorliegen. Außerdem muss die UDID des Geräts in der App hinterlegt sein.

=== Development-Build signieren ===
Ein Development-Build einer App ist nur für eine begrenzte Zahl von Geräten zugelassen und kann auf anderen Geräten nicht gestartet werden. Es ist aber möglich, das Zertifikat und die verwendbaren Geräte in einem Development-Build auszutauschen.

* Evaluierung mit Demo-App von eXept:
:Gerne stellen wir Ihnen eine Demo-App zur Verfügung, die als Development-Build vorliegt und die wir für Ihr Gerät signieren können. Senden Sie dazu bitte Ihrem eXept-Ansprechpartner die UDID Ihres Gerätes zu. Wie Sie die UDID Ihres Gerätes ermitteln können, ist im folgenden Abschnitt beschrieben.

* Eigene App für Ihr Testgerät verwenden:
:Wenn Sie von den App-Entwicklern einen Development-Build (IPA-Datei) erhalten, der für Ihr Testgerät zugelassen ist, können Sie diesen direkt verwenden. Dazu müssen Sie den Entwicklern die UDID Ihres Geräts mitteilen, damit sie diese eintragen können. '''Sie können die UDID eines Gerätes mithilfe von Xcode auslesen'''. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie Ihr Gerät aus und suchen Sie in Eigenschaften den Eintrag ''Identifier''. Die UDID ist eine 40-stellige Hexadezimalzahl.

* Extern entwickelte App für Ihr Testgerät umsignieren:
:Es können auch Apps umsigniert werden, damit Sie auf anderen Geräten lauffähig sind. Dieser Vorgang ist jedoch kompliziert und setzt insbesondere einen Zugang zu einem Apple-Developer-Account voraus. Eine Dokumentation zur Vorgehensweise ist derzeit in Vorbereitung.

:Für die Evaluierung unterstützen wir Sie gerne beim Umsignieren Ihrer App.


Weitere Informationen zur Verwendung von iOS-Geräten finden Sie auch in der [http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Dokumentation von Appium].

=== Native iOS-Apps ===
Sie können auch Apps verwenden, die bereits nativ auf dem Gerät vorhanden sind. Dazu müssen Sie deren Bundle-ID kennen und diese dann in die Verbindungseinstellungen eintragen. Hier eine kleine Auswahl gängiger Apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

Weitere Bundle-IDs finden Sie [https://github.com/joeblau/apple-bundle-identifiers hier].

= Beispiele =
Bei den Demo-Testsuiten für expecco finden Sie auch Beispiele für Tests mit dem Mobile Testing Plugin. Wählen Sie dazu auf dem Startbildschirm die Option "''Beispiel aus Datei''" und öffnen Sie den Ordner "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
Die Testsuite enthält zwei einfache Testpläne: "''Simple CalculatorTest''" und "''Complex Calculator and Messaging Test''". Beide Tests verwenden einen Android-Emulator, den Sie vor Beginn starten müssen. Die Apps, die im Test verwendet werden, gehören zur Grundausstattung des Emulators und müssen daher nicht mehr installiert werden. Da sich die Apps unter jeder Android-Version unterscheiden können, ist es wichtig, dass Ihr Emulator unter Android 6.0 läuft. Außerdem muss die Sprache auf Englisch gestellt sein.

; Simple CalculatorTest
: Dieser Test verbindet sich mit dem Taschenrechner und gibt die Formel ''2+3'' ein. Das Ergebnis des Rechners wird mit dem erwarteten Wert ''5'' verglichen.

; Complex Calculator and Messaging Test
: Dieser Test verbindet sich mit dem Taschenrechner und öffnet anschließend den Nachrichtendienst. Dort wartet er auf eine einkommende Nachricht von der Nummer ''15555215556'', in der eine zu berechnende Formel gesendet wird. Die Nachricht wird zuvor über einen Socket beim Emulator erzeugt. Nach dem Eintreffen der Nachricht wird diese vom Test geöffnet und deren Inhalt gelesen. Danach wird wieder der Taschenrechner geöffnet, die erhaltene Formel eingegeben und das Ergebnis gelesen. Anschließend wechselt der Test wieder zum Nachrichtendienst und sendet das Ergebnis als Antwort.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
Diese sind Bestandteil des Tutorials zum Mobile Testing Plugin. Der jeweils enthaltene Testfall ist unvollständig und wird im Zuge des Tutorials ergänzt. Lesen Sie dazu den Abschnitt [[#Tutorial|Tutorial]].

= Tutorial =
Es gibt ein Tutorial, das das grundsätzliche Vorgehen zur Erstellung von Tests mit dem Mobile Testing Plugin beschreibt. Grundlage dafür ist ein mitgeliefertes Beispiel, bestehend aus einer einfachen App und einer expecco-Testsuite.

Sie finden es auf der Seite [[Mobile_Testing_Tutorial|Mobile Testing Tutorial]] in zwei Versionen für Android und für iOS.
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_Android|Erste Schritte mit Android]]
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_iOS|Erste Schritte mit iOS]]

= Dialoge des Mobile Testing Plugins =
== Verbindungseditor ==
Mithilfe des Verbindungseditors können Sie schnell Verbindungen definieren, ändern oder aufbauen. Je nach Aufgabe weist der Dialog kleine Unterschiede auf und wird unterschiedlich geöffnet:
*Um eine Verbindung aufzubauen, klicken Sie im GUI-Browser auf "''Verbinden'"' klicken und wählen dann "''Mobile Testing''".
*Um eine bestehende Verbindung im GUI-Browser zu ändern oder zu kopieren, wählen Sie diese aus, machen einen Rechtsklick und wählen im Kontextmenü "''Verbindung bearbeiten''" oder "''Verbindung kopieren''" aus.
*Wollen Sie Verbindungseinstellungen nicht für den GUI-Browser sondern zur Verwendung in einem Test erstellen, wählen Sie im Menü des Mobile Testing Plugins den Punkt "''Verbindungseinstellungen erstellen...''". Darüber können nur die Einstellungen für eine Verbindung erstellt werden, ohne dass eine Verbindung tatsächlich angelegt wird.

Einige der Schaltflächen sind nur beim Erstellen von Verbindungseinstellungen sichtbar:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#"''Einstellungen löschen''": Setzt alle Einträge zurück. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Einstellungen aus Datei laden''": Erlaubt das Öffnen einer gespeicherten Einstellungsdatei (*.csf). Deren Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen aus Anhang laden''": Erlaubt das Öffnen eines Anhangs mit Verbindungseinstellungen aus einem geöffneten Projekt. Diese Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen in Datei speichern''" sowie
#"''Einstellungen in Anhang speichern''": Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern oder als Anhang in einem geöffneten Projekt anlegen. Beide Optionen besitzen ein verzögertes Menü, in dem Sie auswählen können, nur einen bestimmten Teil der Einstellungen zu speichern. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Erweiterte Ansicht''": Damit können Sie in die erweiterte Ansicht wechseln, um zusätzliche Einstellungen vorzunehmen. Lesen Sie dazu mehr am Ende des Kapitels. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Hilfe''": An der rechten Seite wird ein Hilfetext zum jeweiligen Schritt ein- oder ausgeblendet.

Der Dialog ist in drei Schritte unterteilt. Im ersten Schritt wählen Sie das Gerät, das Sie verwenden möchten, im zweiten Schritt wählen Sie aus, welche App verwendet werden soll und im letzten Schritt erfolgen die Einstellungen zum Appium-Server.

===Schritt 1: Gerät auswählen===
Im oberen Teil erhalten Sie eine Liste aller angeschlossenen Appium-Geräte, die erkannt werden. Mit der Checkbox darunter können Sie die Geräte ausblenden, die zwar erkannt werden, aber nicht bereit sind. Falls Sie ein Gerät eintragen wollen, das nicht angeschlossen ist, können Sie dies mit dem entsprechenden Knopf "''Android-Gerät eingeben''" bzw. "''iOS-Gerät eingeben''" anlegen. Dazu müssen Sie jedoch die benötigten Eigenschaften Ihres Geräts kennen. Das Gerät wird dann in einer zweiten Geräteliste angelegt und kann dort ausgewählt werden. Wenn keine Liste mit angeschlossenen Elementen angezeigt werden kann, werden stattdessen verschiedene Meldungen angezeigt:
*Keine Geräte gefunden
*:expecco konnte kein Android-Geräte finden.
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*Keine verfügbaren Geräte gefunden
*:expecco konnte keine verfügbaren Android-Geräte finden. Es wurden aber nicht verfügbare gefunden, z.B. mit dem Status "unauthorized".
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*:Um nicht verfügbare Geräte anzuzeigen, aktivieren Sie unten diese Option.
*Verbindung verloren
*:expecco hat die Verbindung zum adb-Server verloren. Versuchen Sie die Verbindung wieder herzustellen, indem Sie auf den Button klicken.
*Verbindung fehlgeschlagen
*:expecco konnte sich nicht mit dem adb-Server verbinden. Möglicherweise läuft er nicht oder der angegebene Pfad stimmt nicht.
*:Überprüfen Sie die adb-Konfiguration in den Einstellungen und versuchen Sie den adb-Server zu starten und eine Verbindung herzustellen indem Sie auf den Knopf klicken.
*Verbinden ...
*:expecco verbindet sich mit dem adb-Server. Dies kann einige Sekunden dauern.
*adb-Server starten ...
*:expecco startet den adb-Server. Dies kann einige Sekunden dauern.

Mit "''Weiter''" gelangen Sie zum nächsten Schritt. Wenn Sie Einstellungen für den GUI-Browser eingeben, ist das erst möglich, wenn ein Gerät ausgewählt wurde.

Anmerkung zum Freischalten: In jüngeren Android Versionen werden die Entwickleroptionen zunächst nicht mehr in den Einstellungen angeboten. Falls ihr Android Gerät in den Einstellungen keinen Eintrag zu "''Entwickleroptionen''" zeigt, wählen Sie zunächst den Eintrag "''Telefoninfo''", dann "''SoftwareVersionsInfo''" und klicken darin mehrfach auf den Eintrag "''BuildVersion''".

==== Chromedriver verwalten ====
Wenn die App, die Sie bedienen wollen, WebViews mit Chrome benutzt, benötigt Appium Zugriff auf einen passenden Chromedriver. Wenn Sie ein Gerät in der Liste auswählen, können Sie über "''Chromedriver verwalten''" sehen, welche Chrome-Versionen auf dem Gerät vorhanden sind und welche Chromedriver-Versionen durch expecco zur Verfügung stehen. Über diesen Dialog können Sie auch benötigte Chromedriver-Versionen herunterladen. Beachten Sie, dass auf dem Gerät verschiedene Chrome-Versionen vorhanden sein können, da die Apps in ihren WebViews nicht die gleiche Chrome-Version verwenden müssen, wie die als Browser installierte. Damit alles funktioniert, sollte der verwendete Chromedriver zur entsprechenden App passen. Sie können den Pfad zum Chromedriver auch am Ende des Verbindungsdialogs in den erstellten Capabilities ändern.

==== WLAN-Android-Geräte verbinden ====
Sie können sich auch über WLAN zu Android-Geräten verbinden. Dazu muss das Gerät zunächst mit adb verbunden werden, siehe [[Mobile_Testing_Plugin#Verbindung_.C3.BCber_WLAN|Verbindung über WLAN]]. Ab expecco 22.1 bietet der Verbindungseditor hierfür einen Dialog, der Ihnen dabei hilft und den Sie anstatt der Eingabeaufforderung verwenden können. Für Geräte mit Android 11 oder höher können Sie hier das Gerät mit dem Rechner zu koppeln, indem Sie die entsprechenden Parameter angeben und anschließend die Verbindung unter Angabe von IP-Adresse und Port aufbauen. Sie können damit auch für Geräte, die über USB verbunden sind, eine WLAN-Verbindung aufbauen. Wenn Sie das entsprechende Gerät in der Liste auswählen, werden die benötigten Angaben automatisch ausgelesen.

Beachten Sie, dass der Aufbau einer WLAN-Verbindung nicht Teil der Verbindungseinstellungen ist. Wenn Sie mit den erzeugten Einstellungen eine neue Verbindung aufbauen wollen, müssen Sie sicherstellen, dass das Gerät über mit der angegebenen IP-Adresse und dem Port mit adb verbunden ist, damit es gefunden wird. Die ADB-Verbindung geht verloren, wenn der ADB-Server oder das Gerät neu gestartet werden. Die Erlaubnis für das WLAN-Debugging wird beim Neustart des Geräts auch häufig zurückgesetzt und der Debug-Port kann dann wechseln. Daher muss eine WLAN-Verbindung immer manuell hergestellt werden.

===Schritt 2: App auswählen===
Hier können Sie Angaben zur App machen, die getestet werden soll. Dabei können Sie entscheiden, ob Sie eine App verwenden wollen, die bereits auf dem Gerät installiert ist, oder ob für den Test eine App installiert werden soll. Wählen Sie oben den entsprechenden Reiter aus. Je nachdem, ob Sie im vorigen Schritt ein Android- oder ein iOS-Gerät ausgewählt haben, ändert sich die erforderte Eingabe.

*'''Android'''
**''App auf dem Gerät''
**:Wenn Sie im ersten Schritt ein angeschlossenes Gerät ausgewählt haben, werden die Pakete aller installierten Apps automatisch abgerufen und Sie können die Auswahl aus den Drop-down-Listen treffen. Die installierten Apps sind in Fremdpakete und Systempakete unterteilt; wählen Sie die entsprechende Paketliste aus. Diese Auswahl gehört nicht zu den Einstellungen, sondern stellt nur die entsprechende Paketliste zur Verfügung. Sie können den Filter benutzen, um die Liste weiter einzuschränken und dann das gewünschte Paket auswählen. Die Activities des ausgwählten Pakets werden ebenfalls automatisch abgerufen und als Drop-down-Liste zur Verfügung gestellt. Wählen Sie die Activity aus, die gestartet werden soll. In der Regel wird automatisch eine Activity aus der Liste eingetragen. Falls Sie kein verbundenes Gerät verwenden, müssen Sie die Eingabe des Pakets und der Activity von Hand vornehmen.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Benutzen Sie einen lokalen Appium-Server, können Sie den rechten Butten benutzen, um zu der Installationsdatei der App zu navigieren und diesen Pfad einzutragen. Wenn möglich werden dabei auch das entsprechende Paket und die Activity in den Feldern darunter eingetragen. Diese Angabe ist aber nicht notwendig.

*'''iOS'''
**''App auf dem Gerät''
**:Geben Sie die Bundle-ID einer installierten App an. Sie können die IDs der installierten Apps bspw. mithilfe von Xcode erfahren. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü "''Window''" den Eintrag "''Devices''". Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wenn Sie Ihr Gerät auswählen, sehen Sie in der Übersicht eine Auflistung der von Ihnen installierten Apps.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Zu den Vorraussetzungen an Apps für reale Geräte lesen Sie bitte den Abschnitt [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Geräte und App vorbereiten]].

Im unteren Teil können Sie festlegen, ob die App beim Verbindungsabbau zurückgesetzt bzw. deinstalliert werden soll, und ob sie initial zurückgesetzt werden soll. Auch hier wird die entsprechende Capability gar nicht gesetzt, wenn Sie "''(Default)''" auswählen. Mit "''Weiter''" gelangen Sie zum nächsten Schritt.

===Schritt 3: Servereinstellungen===
Im letzten Schritt befindet sich zunächst im oberen Teil eine Liste aller Capabilities, die sich aus Ihren Angaben der vorigen Schritte ergeben. Wenn Sie sich mit Appium auskennen und noch zusätzliche Capabilities setzen möchten, die der Verbindungseditor nicht abdeckt, können Sie durch Klicken auf "''Bearbeiten''" in die erweiterte Ansicht gelangen. Lesen Sie dazu den Abschnitt weiter unten.

Wenn Sie Einstellungen für den GUI-Browser eingeben, können Sie den ''Verbindungsnamen'' eintragen, mit dem die Verbindung angezeigt wird. Dies ist auch der Name unter dem Bausteine diese Verbindung verwenden können, wenn sie aufgebaut ist. Wenn Sie das Feld frei lassen, wird ein Name generiert. Wenn der Haken für "''Von expecco gesteuert''" gesetzt ist, wird expecco einen lokalen Appium-Server an einem freien Port starten, oder einen bereits gestarteten freien Server verwenden. Um einen eigenen Server zu verwenden, schalten Sie diese Funktion ab und geben Sie die entsprechende Adresse ein. Sie erhalten die lokale Standard-Adresse und bereits verwendete Adressen zur Auswahl.

In älteren expecco-Versionen ist der Haken mit "''Bei Bedarf starten''" beschriftet. In diesem Fall müssen Sie auch eine Adresse angeben, wenn expecco den Server starten soll. expecco versucht dann beim Verbinden einen Appium-Server an der angegebenen Adresse zu starten, wenn dort noch keiner läuft. Dieser Server wird dann beim Beenden der Verbindung ebenfalls heruntergefahren. Dies funktioniert nur für lokale Adressen. Achten Sie darauf, nur Portnummern zu verwenden, die auch frei sind. Verwenden Sie am besten nur ungerade Portnummern ab dem Standardport 4723. Beim Verbindungsaufbau wird ebenfalls die folgende Portnummer verwendet, wodurch es sonst zu Konflikten kommen könnte.

Je nachdem, wie Sie den Dialog geöffnet haben, gibt es nun verschiedene Schaltflächen um ihn abzuschließen. In jedem Fall haben Sie die Option zu speichern. Dabei öffnet sich ein Dialog, indem Sie entweder ein geöffnet Projekt auswählen können, um die Einstellungen dort als Anhang zu speichern, oder auswählen es in einer Datei zu speichern, die Sie anschließend angeben können. Durch das Speichern wird der Dialog nicht beendet, wodurch Sie anschließend noch eine andere Option auswählen könnten.

Wenn Sie den Editor zum Verbindungsaufbau geöffnet haben, können Sie abschließend auf "''Verbinden''" oder "''Server starten und verbinden''" klicken, je nachdem, ob der Haken für den Serverstart gesetzt ist. Für das Ändern oder Kopieren einer Verbindung im GUI-Brower heißt diese Option "''Übernehmen''", da in diesem Fall nur der Verbindungseintrag geändert bzw. neu angelegt wird, der Verbindungsaufbau aber nicht gestartet wird. Das können Sie bei Bedarf anschließend über das Kontextmenü tun. Falls Sie Capabilities einer bestehenden Verbindung geändert haben, fordert Sie anschließend ein Dialog auf zu entscheiden, ob diese Änderungen direkt übernommen werden sollen, indem die Verbindung abgebaut und mit den neuen Verbindungen aufgebaut wird, oder nicht. In diesem Fall werden die Änderungen erst wirksam, nachdem Sie die Verbindung neu aufbauen.

Zur Verwendung des Verbindungseditors lesen Sie auch den entsprechenden Abschnitt im jeweiligen Tutorial in Schritt 1 (Android: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren|Demo ausführen]], iOS: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren_.28iOS.29|Demo ausführen (iOS)]]).

===Erweiterte Ansicht===
Die erweiterte Ansicht des Verbindungseditors erhalten Sie entweder durch Klicken auf "''Bearbeiten''" im dritten Schritt oder jederzeit über den entsprechenden Menüeintrag, wenn Sie den Editor über das Plugin-Menü gestartet haben. In dieser Ansicht erhalten Sie eine Liste aller eingestellten Appium-Capabilities. Zu dieser können Sie weitere hinzufügen, Einträge ändern oder entfernen. Um eine Capability hinzuzufügen, wählen Sie diese aus der Drop-down-Liste des Eingabefelds aus. In dieser befinden sich alle bekannten Capabilities sortiert in die Kategorien ''Common'', ''Android'' und ''iOS''. Haben Sie eine Capability ausgewählt, wird ein kurzer Informationstext dazu angezeigt. Sie können in das Feld auch von Hand eine Capability eingeben. Klicken Sie dann auf "''Hinzufügen''", um die Capabilitiy in die Liste einzutragen. Dort können Sie in der rechten Spalte den Wert setzen. Um einen Entrag zu löschen, wählen Sie diesen aus und klicken Sie auf "''Entfernen''". Mit "''Zurück''" verlassen Sie die erweiterte Ansicht.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Laufende Appium-Server ==
Im Menü des Mobile Testing Plugins finden Sie den Eintrag "''Appium-Server...''". Mit diesem öffnen Sie ein Fenster mit einer Übersicht aller Appium-Server, die von expecco gestartet wurden und auf welchem Port diese laufen. Durch Klicken auf das Icon in der Spalte "''Log anzeigen''" können Sie das Logfile des entsprechenden Servers anschauen. Dieses wird beim Beenden des Servers wieder gelöscht. Mit den Icons in der Spalte "''Beenden''" kann der entsprechenden Server beendet werden. Allerdings wird dies verhindert, wenn expecco über diesen Server noch eine offene Verbindung hat. Für welche Verbindung ein Server verwendet wird, sehen Sie in der rechten Spalte. Steht dort ''<idle>'' wird er zur Zeit nicht von expecco verwendet.

[[Datei:MobileTestingAppiumServer.png]]

Beim Öffnen des Editors um eine Appium-Verbindung aufzubauen, wird direkt ein Appium-Server gestartet, um den folgenden Verbindungsaufbau zu beschleunigen. Zu diesem Zweck hält sich expecco auch immer einen freien Appium-Server offen. Weitere laufende Server, die nicht mehr verwendet werden, werden jedoch nach einiger Zeit automatisch beendet.

Im Menü des Mobile Testing Plugins finden Sie auch den Eintrag "''Alle Verbindungen und Server beenden''". Dies ist für den Fall gedacht, dass Verbindungen oder Server auf andere Weise nicht beendet werden können. Beenden Sie Verbindungen wenn möglich immer im GUI-Browser oder durch Ausführen eines entsprechenden Bausteins. Server, die Sie in der Server-Übersicht gestartet haben, beenden Sie dort; Server, die mit einer Verbindung gestartet wurden, werden automatisch mit dieser beendet.

Beachten Sie, dass in der Übersicht nur Server aufgelistet sind, die von expecco gestartet und verwaltet werden. Mögliche andere Appium-Server, die auf andere Art gestartet wurden, werden nicht erkannt.

== Recorder ==
Besteht im GUI-Browser eine Verbindung zu einem Gerät, kann der integrierte Recorder verwendet werden, um mit diesem Gerät einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

[[Datei:MobileTestingRecorder.png|caption|]]

====Komponenten des Recorderfensters====
#'''Aufnahme fortsetzen/pausieren''': Über das rechte Symbol können Sie die Aufnahme pausieren. Sie sehen dann ein großes Pause-Symbol in der Anzeige. Alle Aktionen, die Sie währenddessen im Recorder machen werden zwar ausgeführt, es werden aber keine Bausteine aufgezeichnet. Über das linke Symbol können Sie dann wieder in den normalen Aufnahmemodus wechseln.
#'''Aufnahme stoppen''': Stoppt die Aufnahme und schließt das Recorderfenster.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Gerät. Dies wird nötig, wenn das Gerät zur Ausführung einer Aktion länger braucht oder sich etwas ohne das Anstoßen durch den Recorder ändert. Seit expecco 21.2 gibt es hier zusätzlich ein Untermenü, mit dem automatisches Aktualisieren angeschaltet werden kann, indem im Hintergrund auf Änderungen geprüft wird (siehe auch ''Automatisches Aktualisieren'' weiter unten).
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Elemente einzeichnen''': Die Rahmen aller Elemente der Ansicht werden angezeigt.
#'''Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst. Dabei stehen folgende Aktionen zur Verfügung:
#*Aktionen auf Elemente:
#**Klicken: Kurzer Klick auf das Element, über dem der Cursor steht. Zur genaueren Bestimmung, welches Element verwendet wird, benutzen Sie die Funktion Follow-Mouse oder Element-Highlighting.
#**Antippen mit Dauer (Element): Ähnlich zum Klicken, nur dass zusätzlich die Dauer des Klicks aufgezeichnet wird. Dadurch sind auch längere Klicks möglich.
#**Antippen mit Position (Element): Ähnlich zum Klicken, aber zusätzlich wird die Position innerhalb des Elements aufgenommen. Die Position kann relativ zur Größe des Elements aufgenommen werden oder, wenn Sie dabei Strg gedrückt halten, absolut zur linken oberen Ecke des Elements.
#**Text setzen: Ermöglicht das Setzen eines Textes in Eingabefelder.
#**Text löschen: Löscht den Text eines Eingabefelds.
#*Aktionen auf das Gerät:
#**Antippen (Bildschirm): Löst einen Klick auf die Bildschirmposition aus.
#**Antippen mit Dauer (Bildschirm): Löst einen Klick auf die Bildschirmposition aus, bei dem auch die Dauer berücksichtigt wird.
#**Wischen: Wischen in einer geraden Linie vom Punkt des Drückens des Mausknopfes bis zum Loslassen. Die Dauer wird ebenfalls aufgezeichnet.
#:Beachten Sie bei diesen Aktionen, dass das Ergebnis sich auf verschiedenen Geräten unterscheiden kann, bspw. bei verschiedenen Bildschirmauflösungen.
#*Erstellen von Testablauf-Bausteinen
#**Attribut prüfen: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Das Ergebnis triggert den entsprechenden Ausgang.
#**Attribut zusichern: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Bei Ungleichheit schlägt der Test fehl.
#**Attribut holen: Liest den aktuellen Wert eines Attributs aus.
#*Automatisch
#:Ist das Auto-Werkzeug ausgewählt, können alle Aktionen durch spezifische Eingabeweise benutzt werden: ''Klicken'', ''Element antippen'' und ''Wischen'' funktionieren weiterhin durch Klicken, wobei sie anhand der Dauer und der Bewegung des Cursors unterschieden werden. Um ein ''Antippen'' auszulösen, halten Sie beim Klicken Strg gedrückt. Die übrigen Aktionen erhalten Sie durch einen Rechtsklick auf das Element in einem Kontextmenü.
#'''Kontext-Aktionen''': Hier können Sie Aktionen aufzeichnen, die Kontexte betreffen:
#*Zu Kontext wechseln: Bietet eine Liste der aktuell verfügbaren Kontexte und Sie können auswählen, zu welchem gewechselt werden soll.
#*Aktuellen Kontext holen: Holt den Handle des aktuellen Kontexts.
#*Kontext-Handles holen: Holt eine Liste aller aktuell verfügbaren Kontext-Handles.
#'''Softkeys''': Nur unter Android. Simuliert das Drücken der Knöpfe Zurück, Home, Fensterliste und Power.
#'''Home-Button''': Nur unter iOS ab expecco 2.11. Ermöglicht das Drücken des Home-Buttons. Vor expecco 19.2 funktioniert es nur, wenn AssistiveTouch aktiviert ist und sich das Menü in der Mitte des oberen Bildschirmrands befindet. Ab expecco 19.2 verwendet die Funktion kein AssistiveTouch mehr.
#'''Hilfe''': Öffnet diese Online-Dokumentation auf der allgemeinen Seite zu [[GuiBrowser_Recorder|GUI-Browser Recordern]].
#'''Anzeige''': Zeigt einen Screenshot des Geräts. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Ansicht anpassen''': Öffnet einen Dialog um die Ansicht anzupassen, falls expecco das Bild nicht richtig darstellt. Sie können die Skalierung anpassen oder das Bild um 90° drehen.
#'''Ausrichtung anpassen''': Korrigiert das Bild, falls dieses auf dem Kopf stehen sollte. Über den Pfeil rechts daneben kann das Bild auch um 90° gedreht werden, falls dies einmal nötig sein sollte. Ab expecco 19.1 finden Sie diese Funktion in ''Ansicht anpassen''. Die Ausrichtung des Bildes ist für die Funktion des Recorders unerheblich, dieser arbeitet ausschließlich auf den erhaltenen Elementen.
#'''Skalierung''': Ändert die Skalierung des Screenshots.
#'''Meldungen''': Zeigt den Pfad des ausgewählten Elements oder andere Meldungen an. Es gibt ein Kontextmenü, um eine Liste der vorigen Meldungen zu sehen.

====Verwendung====
Mit jedem Klick im Fenster wird eine Aktion ausgelöst und im Arbeitsbereich des GUI-Browsers aufgezeichnet. Dort können Sie das Aufgenommene abspielen, editieren oder daraus einen neuen Baustein erstellen.
Aktionen zum Auslösen von Sofkeys finden Sie direkt in der Menüleiste (s.o.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Werkzeugs in der Menüleiste (s.o.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion.
Zur Verwendung des Recorders lesen Sie auch Schritt 2 im Tutorial ([[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen|Android]] bzw. [[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen_.28iOS.29|iOS]]).

====Elemente verbergen====
Ab expecco 21.2 gibt es im Kontextmenü außerdem die Möglichkeit, das ausgewählte Element im Recorder zu verbergen. Das bedeutet, dass dieses Element fortan nicht mehr ausgewählt werden kann. Diese Funktion eignet sich dazu, Elemente zu ignorieren, die im Vordergrund liegen, um auf Elemente darunter zugreifen zu können. Um diesen Zustand wieder rückgängig zu machen, müssen Sie das entsprechende Element im Baum des GUI-Browsers finden, dort gibt es im Kontextmenü ebenfalls einen solchen Eintrag.

====Automatisches Aktualisieren====
Der Recorder zeigt kein Livebild des Geräts sondern nur eine Momentaufnahme. Um mit der Anzeige auf dem Gerät übereinzustimmen muss daher nach Änderungen aktualisiert werden. Der Recorder aktualisiert sich automatisch, nachdem er eine Aktion ausgeführt hat. Ab expecco 20.2 sind zudem weitere automatische Updates möglich. Sie können Sie im Menü ''Fenster'' aktivieren.

Zum einen kann kurze Zeit nach dem Ausführen einer Aktion überprüft werden, ob es noch Änderungen nach der ersten Aktualisierung gegeben hat, damit in diesem Fall eine zweite Aktualisierung stattfinden kann. Dies soll das Problem beheben, dass der Recorder nach einer Aktion nicht aktuell ist, weil die Aktualisierung zu früh stattgefunden hat.

Zum anderen kann eine periodische Aktualisierung eingeschaltet werden. Nach einem einstellbaren Interval wird der Recorder automatisch aktualisiert, sollte es Änderungen geben. Dadurch ist die Anzeige im Recorder immer weitgehend aktuell, allerdings entsteht dadurch auch ein Mehraufwand was die Kommunikation mit dem Gerät betrifft.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid-Apps und WebViews =

'''!!! WICHTIGER HINWEIS - Wenn Sie Probleme haben, auf den Webview zu wechseln, geben Sie bitte unter den Android Einstellungen - Apps -Standard Apps "Chrome" als "Browser-App" an !!!
'''

Hybrid-Apps enthalten neben den Plattform-nativen Elementen weitere Elemente, die in einen WebView eingebunden sind. Diese Elemente können ebenfalls bedient werden, allerdings muss zuvor in den entsprechenden Kontext gewechselt werden. Mit dem Baustein "''Get Current Context''" erhalten Sie den aktuellen Kontext. Zu Beginn ist dies "''NATIVE_APP''", also der Kontext der nativen Elemente. Mit dem Baustein "''Get Context Handles''" bekommen Sie eine Collection aller vorhandenen Kontexte. Gibt es einen WebView-Kontext, so heißt dieser "''WEBVIEW_1''" oder "''WEBVIEW_<package>''" mit dem Paket des WebViews. Es kann auch mehrere WebView-Kontexte geben. Zu jedem WebView-Kontext gibt es im nativen Kontext ein entsprechendes WebView-Element. Mit dem Baustein "''Switch to Context''" können Sie in einen solchen Kontext wechseln und haben fortan nur Zugriff auf die Elemente in diesem Kontext.

Im GUI-Browser werden zum einen oben im Baum die vorhandenen Kontexte angezeigt, zum anderen wird der Baum eines Kontexts unterhalb des entsprechenden WebView-Elements eingefügt.

= XPath anpassen mithilfe des GUI-Browsers =
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen "''GTIN-13 (EAN-13)''" und "''Verify''", das Eingabefeld der Zahl "''4006381333986''" und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des "''GTIN-13''"-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch "''Pfad überprüfen''" (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit "''Verify Path: OK''" (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit "*" zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert "''GTIN-13 (EAN-13)''" besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer "''hierarchy''" (für iOS wäre es "''AppiumAUT''"), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix "''android.widget.''", das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend "''XCUIElementType''" am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. "''FrameLayout''" ist ein Kindelement von "''hierarchy''", "''LinearLayout''" ist ein Kind von "''FrameLayout''" usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element "''hierarchy''" beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben "''TextView''"-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ "''Button''" gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut "''resource-id''". Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut "''name''" verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem "@" eingeleitet und der Wert mit einem "=" in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter "''Test''" eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf "''Lauf''". Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu "''Eigenschaften''", wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

== Weitere Locator-Strategien ==
Appium bietet neben XPath noch weitere Strategien zur Adressierung von Elementen an. Einige davon stehen Ihnen '''ab Version 20.1''' ebenfalls mit expecco zur Verfügung. Diese sind nicht ganz so mächtig wie XPath, dafür aber häufig schneller bei der Auflösung auf dem Gerät. Insbesondere bei der Verwendung mit iPhones, wo die Hierarchie bei jeder XPath-Auflösung erst aufgebaut werden muss, bieten alternative Strategien einen Vorteil für die Laufzeit.

XPath ist weiterhin der Standard, das heißt alle Locator ohne besondere Angabe werden als XPath interpretiert. Um eine der anderen Strategien zu verwenden, schreiben Sie diese mit einem Gleichzeichen vor den gewünschten Locator. Diese Technik können Sie sowohl an den Blöcken verwenden, als auch im GUI-Browser testen.

{|
|-
| style="vertical-align:top" | AccessibilityId || style="padding-bottom:0.5em" | Verwendet den Wert des Elements, der dazu dient, die App barrierefrei zu machen. Für iOS ist das das Attribut '''Accessibility-id''', für Android das Attribut '''content-descr'''. ''Beispiel: accessibilityId=Löschen''
|-
| style="vertical-align:top" | className || style="padding-bottom:0.5em" | Verwendet den Namen der Klasse des Elements. ''Beispiel: className=android.widget.FrameLayout''
|-
| style="vertical-align:top" | id || style="padding-bottom:0.5em" | Verwendet die Kennung des Elements. Für iOS ist das das Attribut '''name''', für Android das Attribut '''resource-id'''. ''Beispiel: id=android:id/text1''
|-
| style="vertical-align:top" | iOSClassChain1 || style="padding-bottom:0.5em" | Verwendet die Hierarchie der Elemente ähnlich wie bei XPath. Eine Erklärung zum Aufbau finden Sie [https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules hier]. ''Beispiel: iOSClassChain=XCUIElementTypeWindow/XCUIElementTypeButton[`label == "Ok"`]''
|-
| style="vertical-align:top; padding-right:1em" | iOSNsPredicateString1 || style="padding-bottom:0.5em" | Verwendet einfache Kriterien, wie Attribute, die auch kombiniert werden können. ''Beispiel: iOSNsPredicateString=type == 'XCUIElementTypeButton' AND name == 'Weiter'''
|-
| style="vertical-align:top" | name1 || style="padding-bottom:0.5em" | Verwendet den Namen des Elements. ''Beispiel: name=Bestätigen''
|-
|}

:1 ''nur für iOS''

Um eine direkte Beschleunigung mit iOS zu erzielen, ohne dass Sie Ihre bisherigen Pfade anpassen müssen, wandelt expecco zudem Pfade, die nur aus einem Element mit Klasse und name-Attribut bestehen, zur Laufzeit automatisch in einen entsprechenden Locator der Strategie iOSNsPredicateString um. Wenn Sie einen Pfad explizit als XPath markieren, wird diese Anpassung nicht vorgenommen.

=Probleme und Lösungen=
== Locator sind versionsabhängig oder variabel ==
Dann sollten Sie die Locator (xPath) entweder in einer Variablen halten oder ein Locator-Mapping in einem Screenplay Anhang definieren. Es ist auch möglich, lediglich Teile des Locators (z.B. Locator-Pfad eines Elternelements oder Attributwert) in einer Variable zu halten und im Freezevalue des Locator-Pins mit "''$(varName)''" einzufügen.

==Unsichtbare UI-Elemente==
Beachten Sie, dass im [[#Recorder|Recorder]] auch Elemente berücksichtigt werden, die Sie auf dem Bildschirm nicht sehen. Schalten Sie daher das Element-Highlighting an oder nutzen Sie die Follow-Mouse-Funktion und den Elementbaum im GUI-Browser, um festzustellen, ob das richtige Element verwendet wird. Es kann vorkommen, dass unsichtbare Elemente vor anderen Elementen liegen und diese verdecken, so dass die gewünschten Elemente im Recorder nicht ausgewählt werden können. Lesen Sie dazu den Abschnitt [[#Elemente_verbergen|Elemente verbergen]].

==''org.openqa.selenium.StaleElementReferenceException''==
Der Fehler <code>org.openqa.selenium.StaleElementReferenceException</code> tritt immer dann auf, wenn ein Element verwendet wird, das nicht mehr da ist. Wenn das in Ihrem Test passiert und das Element eigentlich da sein sollte, verwenden Sie an der Stelle stattdessen den Locator (XPath), um das Element neu zu holen.

In manchen Fällen kann dieser Fehler auch dann auftreten, wenn Sie am Baustein bereits Locator angegeben haben. Das liegt daran, dass immer zuerst der Locator aufgelöst und das entsprechende Element geholt wird und dann die Aktionen mit dem Element ausgeführt wird. Wenn die App das Element genau zwischen dem Zeitpunkt des Auflösens und Holens und der Ausführung der Aktion aktualisiert und dabei ein neues Element erzeugt, kommt es zu diesem Fehler. Passiert das an einer bestimmten Stelle in Ihrem Test, bleibt nichts anderes als den Fehler abzufangen und es erneut zu versuchen.

==iOS: Kabel nicht zertifiziert==
In manchen Fällen erscheint beim Verbinden eines iOS-Geräts über USB der Hinweis, das verwendete Kabel sei nicht zertifiziert. In diesem Fall hilft es nur, das entsprechende Kabel auszutauschen.
==iOS: Alerts beim Verbindungsaufbau==
Stellen Sie sicher, dass beim Verbindungsaufbau mit einem iOS-Gerät keine Alerts geöffnet sind. Der Aufbau schlägt sonst fehl, da die App nicht in den Vordergrund kommen kann. Siehe auch [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Gerät und App vorbereiten]].

==iOS: .ipa installieren nicht möglich==
Beachten Sie, dass auf iOS-Simulatoren keine ''.ipa''-Dateien sondern nur ''.app''-Dateien installiert werden können.

==iOS: Erster Verbindungsaufbau funktioniert nicht==
Wenn auf Ihrem Mac noch kein signierter Build des WebDriverAgents liegt, muss dieser beim ersten Verbindungsaufbau erst erzeugt werden. Das kann in der Regel etwas länger als eine Minute dauern. Standardmäßig verwendet Appium aber einen Timeout von 60000 ms um zu warten bis der WebDriverAgent auf dem Gerät startet, so dass der Aufbau in diesen Fällen abgebrochen wird. Sie können den Timeout mit der Capability ''wdaLaunchTimeout'' setzen, z.B. auf ''120000''.

Außerdem müssen die Einstellungen für die Signierung passen. Am zuverlässigsten funktioniert das nach unserer Erfahrung, wenn man im Xcode-Projekt des WebDriverAgents auf automatische Signierung stellt und das Team setzt. Siehe dazu die Erklärung im Abschnitt [[#WebDriverAgent-Signierung|WebDriverAgent-Signierung]]. In diesem Fall sollten Sie die Capabilities ''xcodeConfigFile'' bzw. ''xcodeOrgId'' und ''xcodeSigningId'' '''nicht''' verwenden, da es sonst zu Konflikten kommen kann. Achtung: Wenn Sie eine Team-ID in den Mobile-Testing-Einstellungen gesetzt haben, setzt expecco diese automatisch als ''xcodeOrgId''!

Achten Sie beim ersten Verbindungsaufbau außerdem auf Ihr Gerät, da Sie dort möglicherweise der Installation per Passwort zustimmen müssen. Auf dem Mac kann die Eingabe des Passworts zur Freigabe des Schlüsselbunds für die Signierung nötig werden, häufig auch mehrmals.

==Android: Gerät nicht im Verbindungsdialog==
Wenn ein über USB angeschlossenes Android-Gerät nicht im Verbindungsdialog auftaucht, versuchen Sie, den USB-Verbindungstyp zu ändern. In der Regel sollten MTP oder PTP funktionieren. Prüfen Sie nochmal, ob "USB Debugging" in den Entwicklereinstellungen des Geräts aktiviert ist (diese Einstellungen sind bei manchen Geräten zunächst unsichtbar, und müssen durch einen Trick zugänglich gemacht werden). Siehe auch [[#Android-Ger.C3.A4t_vorbereiten|Android-Gerät vorbereiten]].

==Android: Abgeschnittene Elemente unten==
Bei Android-Geräten, die die Steuerungsleiste bzw. Softkeys automatisch ein- und ausblenden, kann es vorkommen, dass der Recorder im unteren Bereich Elemente abschneidet, die durch die Softkeys verdeckt würden, auch wenn sie zu diesem Zeitpunkt gar nicht angezeigt werden. In diesem Fall hift es, die Softkeys so einzustellen, dass sie in einer permanenten Leiste angezeigt werden.

Bei neueren Android-Versionen gibt es eine solche Einstellung in der Regel nicht. Auch wenn die Steuerelemente permanent eingeblendet sind, liegen sie auf keiner extra Leiste, sondern vor dem Inhalt der App. Es gibt dann im unteren Teil einen Bereich, der nicht bedient werden kann, weil er nicht zum aktiven Bereich der App gezählt wird, weshalb die Elemente von Appium abgeschnitten werden. Dieser Bereich kann auch größer sein als von den Steuerungselementen beansprucht. Bekannt ist dies für Samsung-Geräte mit Android 11. Da die Information über die Größe des App-Bereichs bereits auf Android-Ebene so geliefert wird, können wir hierfür keine Lösung anbieten, sondern können nur hoffen, dass das Problem vom Hersteller behoben wird. Sie können versuchen, ob Sie mit der Einstellung von Gestensteuerung bessere Ergebnisse bekommen, allerdings gibt es hier das gleiche Problem.

== Android: Test hängt beim Suchen eines Elements==
Der Baustein ''Find Element by XPath'' und alle Element-Bausteine warten bis ein Element zum angegebenen Pfad auftaucht. Den Timeout dafür kann man entweder am Baustein direkt oder in den Umgebungsvariablen ändern. Wenn das Element aber bereits da sein sollte und es dennoch sehr lange dauert, bis der Test weitergeht, kann das am UIAutomator/UIAutomator2 liegen. Dieser wartet, bis die App in den Idle-Zustand geht, bevor er überhaupt nach Elementen sucht. Dies kann länger dauern, wenn die App z.B. im Hintergrund noch Animationen abspielt oder andere Aktionen ausführt. Auch das Holen des Page-Sources z.B. beim Aktualisieren im GUI-Browser oder im Recorder kann dadurch länger dauern. Standardmäßig gibt es hierfür einen Timeout von 10 Sekunden, nach dem nicht weiter auf den Idle-Zustand gewartet wird. Dieser Timeout lässt sich durch eine Einstellung in Appium anpassen (waitForIdleTimeout). Falls Sie einen anderen Wert für diesen Timeout setzen möchten, ist dies ab expecco 21.2 möglich, indem Sie vor dem Test den Smalltalk-Code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> ausführen. Der Timeout wird in Millisekunden angegeben, das Beispiel setzt ihn also auf 2 Sekunden.

==Android: Aktualisieren des Trees oder Wechseln zum Webview-Kontext braucht zu lange==
Speziell mit älteren Geräten kann es vorkommen, dass neuere Chromedriver nicht initialisiert werden können. Das führt dann dazu, dass nicht in den Webview-Kontext gewechselt werden kann. Dies wird von Appium allerdings nur über einen Timeout festgestellt, der standardmäßig bei 4 Minuten liegt. Da expecco auch beim Aufbauen des Trees im GUI-Browser versucht in den Webview-Kontext zu wechseln, kann das zu sehr langen Ladezeiten führen. Da es in Appium keine Möglichkeit gibt, diesen Timeout herunter zu setzen, haben wir die Version, die wir im MobileTestingSupplement bereitstellen, um eine entsprechende Capability erweitert. Ab der Version 1.13.1.0 des [[#Windows|MobileTestingSupplements]] kann mit ''chromedriverStartTimeout'' der Timeout in Millisekunden gesetzt werden. Der Wechsel funktioniert dadurch zwar trotzdem nicht, aber expecco braucht dann nicht mehr so lange beim Aktualisieren des Trees und der Baustein zum Wechseln des Kontextes schlägt schneller fehl. Der Verbindungsdialog fügt diese Capability ab expecco 22.1 automatisch hinzu.

==Keine Aktion bei Klick==
Der Baustein zum Klicken auf ein Element ist erfolgreich, aber auf dem Gerät wurde keine Aktion ausgeführt.
:Dies kann vorkommen, wenn das Element von einem anderen Element verdeckt ist und ein Klick auf das Element deshalb nicht möglich ist. In diesem Fall wird von Appium kein Fehler geworfen, sondern es passiert einfach nichts. Wenn Sie dennoch einen Klick an der Position des Elements machen möchten, auch wenn es verdeckt ist, benutzen Sie stattdessen den Baustein ''Tap'' und übergeben Sie diesem die Position des Elements (''Get Location''). Wenn Sie stattdessen vor einem Klick prüfen möchten, ob das Element zu diesem Zeitpunkt verdeckt ist, versuchen Sie, ob Ihnen die Eigenschaften ''Is Displayed'' oder ''Is Enabled'' weiterhelfen.

==Kein Update nach Aktion==
Über den Recorder wurde eine Aktion ausgeführt, für die auch ein Baustein aufgezeichnet wurde, der Recorder zeigt aber immer noch das alte Bild.
:Der Recorder zeigt kein Livebild des Geräts, sondern immer nur eine Momentaufnahme. Nachdem eine Aktion ausgeführt wurde, aktualisiert sich der Recorder automatisch. Es kann aber vorkommen, dass das Bild schon aktualisiert wurde, bevor die Auswirkungen der Aktion auf dem Gerät vollständig abgeschlossen sind. In diesem Fall sollten Sie den Recorder von Hand aktualisieren über das Symbol mit den blauen Pfeilen. Ab expecco 20.2 können Sie für diesen Fall auch automatisches Aktualisieren einstellen. Siehe auch Beschreibung zum [[#Recorder|Recorder]].

=="clickable" Attribut falsch==
Ein Element hat im "''clickable''" Attribut/Property den Wert "''false''", ist aber dennoch anklickbar.
:Das "''clickable''" Attribute muss explizit vom App-Programmierer gesetzt werden, und hat tatsächlich keine Relevanz für das tatsächliche Verhalten der App. Sie sollten dieses Attribut i.A. in Ihren Tests nicht beachten. Leider existieren viele Apps, bei denen der Programmierer hier "lazy" war.

==Verbindungsaufbau schlägt fehl==
Schlägt der Verbindungsaufbau mit dem Appium-Server fehl, erhalten Sie in expecco eine Fehlermeldung ähnlicher der unten abgebildeten.

[[Datei:MobileTestingVerbindungsfehler.png]]

Hier sehen Sie die Art des aufgetretenen Fehlers. Klicken Sie auf "''Details''" um nähere Informationen zu erhalten. Mögliche Fehler sind:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:Der angegebene Server läuft nicht oder ist nicht erreichbar. Überprüfen Sie die Serveradresse.
*''org.openqa.selenium.WebDriverException''
:Lesen Sie in den Details in der ersten Zeile die Meldung hinter ''Original Error'':
:*''Unknown device or simulator UDID''
::Entweder ist das Gerät nicht richtig angeschlossen oder die udid stimmt nicht.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::Dieser Fehler kann verschiedene Ursachen haben. Entweder konnte tatsächlich der WebDriverAgent nicht gebaut werden, weil die Signierungseinstellungen falsch sind oder das passende Provisioning Profile fehlt. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]]. Es kann auch sein, dass der WebDriverAgent auf dem Gerät nicht gestartet werden kann, weil sich beispielsweise ein Alert im Vordergrund befindet oder Sie dem Entwickler nicht vertraut haben.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::Die angegebene App kann nicht auf dem iOS-Gerät installiert werden, weil es nicht im Provisioning Profile der App eingetragen ist.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.'''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die Datei unter dem angegebenen Pfad auf dem Mac befindet.
:*''packageAndLaunchActivityFromManifest failed.''
::Die angegebene ''apk''-Datei ist vermutlich kaputt.
:*''Could not find app apk at [...]''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die ''apk''-Datei am angegebenen Pfad befindet.

Falls der Fehler nicht durch eine der oben gelisteten Ursachen bedingt ist, kann es sein, dass die auf dem Gerät befindlichen Automation-Anwendungen nicht mehr richtig funktionieren. Hier hilft es, diese vom Mobilgerät zu deinstallieren. Beim nächsten Verbindungsaufbau werden sie dann automatisch neu installiert.

*Für iOS-Geräte ist das der WebDriverAgent, den Sie einfach vom Home-Screen deinstallieren können. Dies behebt in der Regel Probleme durch den Wechsel des verwendeten Macs oder der Xcode-Version.

*Für Android-Geräte ist es der UIAutomator2; hier tritt auf einigen Geräten sporadisch ein Problem auf, die Ursache dafür ist uns z.Z. noch nicht bekannt. Zur Deinstallation navigieren Sie auf dem Gerät zu "''Einstellungen''" > "''Anwendungen''"* und suchen in der Liste nach folgenden Einträgen:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Klicken Sie auf die jeweilige Anwendung und dann auf "''Deinstallieren''".
*''Der entsprechende Eintrag heißt auf manchen Geräten möglicherweise etwas anders.''

Falls dies nicht hilft, kann eventuell die Ausgabe des Appium-Servers weiterhelfen. Für einen von expecco gestarteten Server finden Sie das Log in der Liste der [[#Laufende_Appium-Server|laufenden Appium-Server]].

==Ich habe keinen Mac==
Vielleicht hilft Ihnen diese Webseite weiter: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Release Notes 24.x

2024-12-19T16:31:01Z

Matilk: /* Future Release 24.2 (4Q 2024) */

See also: [[Release Notes 23.x]]
 

== Future Release 24.2 (January 2025) ==
*Feature: WindowsAutomation: "Mouse Wheel Simulation" support
*Feature: Any and template typed parameters in testcase (of testplan)
*Feature: Negated [[Testplan_Editor/en#Condition_Variables|condition variable]] check
*Fix: Project Difference Viewer showed wrong tab for steps inside the test/demo diagram
*Fix: Exchange connection function of diagram editor left an invisible connection at the pin. Lead to wrong output value forwarding during the current session, but cured itself when saving and reloading.
*Improving the function and operation of variable pins ([[Scheme_Editor/en#Variable_Number_of_Pins|Scheme_Editor/Variable_Number_of_Pins]])
*Fix/Feature: Severity level limit is passed on in sub-test plans with the option of tightening the severity level per test plan level
*Improvement: Change modification date of the project when shrink wrapping an imported library

== Release 24.1 (2Q 2024) ==
*Feature: [[Expecco_API/en#Global_and_Static_Variables|Static Variables for Python]]
*Feature: Qt-Testing: Logging with log levels <code>DEBUG</code>, <code>INFO</code> and <code>WARN</code> ([[Qt_Inject_Windows/en#Logging|Qt-Logging]])
*Feature: Qt-Testing: Qt-Connections now use the ConnectionManager like the other Gui test technologies
*Feature: WindowsAutomation: Native Touch, Tap, Drag & Drop support now in the base WindowsAutomation Library
*Feature: Show Log and [[Timeline/en|Timeline view]] for testplans
*Feature: Search and Goto Line menu functions in the activity log view
*Feature: [[Embedded Systems C Bridge API|C-Bridge]] now supports SSL connections (encryption and authentication using certificates)
*Feature: [[Testsuite_Editor-ExecutionSettings_Editor/en|Settings for execution]] (thread pool and log activities/pins/info) can now be saved in the test suite settings
*Feature: CSV test report, values for start time, end time and duration added
*Feature: Improved refactoring for compound blocks: "Extract (& Replace) New Compound Action"
*Feature: Enhanced expecco reflection library
*Feature: Logprocessors can be executed for embedded testplans
*Feature: Logging of background actions can be individually enabled and disabled for testplans and nested testplans
*Feature: Support for script actions written in the [[Installing_additional_Frameworks/en#Julia_Installation|Julia]] programming language
*Feature: Powershell actions: support functions for writing to pins, logging, opening dialogs, etc.
*Fix: Current temporary testplan settings (like selected testcases, do-not-execute of pre/post action, etc.) don't get lost anymore when reimporting a library
*Fix: WindowsAutomation: Fix blocking of applications after <Mouse Button Down>
*Fix: asynchronous write to an output pin with no wait() in bridged actions are now detected and reported as error (see Example3 in the [[Expecco_API/en#Asynchronous_and_Callback_Functions|NodeJS API Documentation]])
*Fix: Bridges: Detect (and ignore) invalid requests from forked background bridge threads
*Fix: Acitivity logs of asynchronous events in background actions are now displayed correctly in the background activity log.
*Fix: Qt: Drag and drop improved by revising the "Move mouse event" (Windows)
*Fix: Disabling logs of sub-activities (if successful, if not successful, etc.)

Selenium WebDriver Plugin/en

2024-08-22T15:16:05Z

Matilk: /* FAQ */ Firefox after Update

[[Selenium_WebDriver_Plugin|Deutsche Version]] | '''English Version'''

=Introduction=
Use the ''Selenium WebDriver Plugin'' to test or automate interactions of applications running in a web-browser (*). The plugin can be (and usually is) used with the [[Expecco_GUI_Tests_Extension_Reference|GUI Browser]], which helps in the creation of tests. Moreover, the GUI Browser can record UI sessions, which can later be customised or refactored as required.

The ''Selenium WebDriver Plugin'' replaces the previous [[Selenium_Web_Test_Plugin|Selenium Web Test Plugin]], which was based on the now outdated Selenium RC framework. 
The new web driver uses the [https://www.seleniumhq.org/projects/webdriver/ Selenium WebDriver] for automation, and replaces the previous interface.
(see https://www.guru99.com/introduction-webdriver-comparison-selenium-rc.html for background information and a description of the differences.)
Read [[#Transferring_Old_Selenium_Tests|this section]] for information how to transfer testsuites using the old plugin.

(*) actually, there exists WebDriver interfaces to control Windows or OS X desktop applications. Thus, this plugin can be used in a number of additional scenarios.

=Settings=
This plugin uses the Java bridge and therefore needs a Java installation. You can specify it in the settings under ''Plugins'' -> ''Java Bridge''. The important field is ''Java Installation Path'', where you can set a JDK or JRE. If nothing is set, expecco tries to find java in the PATH.

[[Datei:JDKPfadEinstellungen.png|600px]]

There are settings for the Selenium WebDriver Plugin itself as well. You find them under ''Plugins'' -> ''Webtest (Selenium WebDriver)''. There you can for example set the address of a remote running Selenium server or another Jar file for Selenium. The settings for the different browser types are divided into the two subpages ''Most Popular Browsers'' and ''Other Browsers''. There you can set the path to the browser executable or to the webdriver to use. You can leave all these fields empty and expecco will search for them automatically

=Browser Support=
This plugin supports (among others) the Chrome/Chromium, Edge, Firefox, Internet Explorer and Opera browsers.
 Safari under OSX must be at least version 10, and OSX must be at least El Capitan.
The plugin uses the WebDriver interface for communication; therefore, browsers running both on the local or on a remote machine can be tested and/or controlled.
In addition, many other browsers, UIs and devices support the WebDriver protocol, and can thus be automated/tested with expecco.

==Update WebDriver==
Each browser has a driver ("''WebDriver''") for opening and controlling a browser window.
Usually, the driver is a separate program which translates WebDriver requests into browser-specific interface calls. However, there are also browsers and programs which have the WebDriver protocol already built in (eg. Safari).

The expecco installation package includes current driver versions for common browsers. However, as the browsers are updated continuously, sometimes even automatically, you sooner or later may have to download a new driver version. In that case put it in the folder inside your expecco installation directory where the other versions are stored as well, at:
<code>packages/exept/expecco/plugin/seleniumWebDriver/lib/XXX</code>
(of course, with "\”s instead of "/"s on Microsoft Windows operating systems), where "XXX" denotes the operating system (Windows, Linux, OSX etc.).


In the connection dialog, expecco may show a warning, that the driver version is incompatible with the browser version. In some cases this may only be due to the fact, that this version was not known at the time of delivery. Some combinations may work despite the warning, but we cannot guarantee that for each individual case.

Therefore you can always check the "''Do not show this warning again''" toggle, if such a warning is shown, to have expecco remember that combination as "compatible" in your settings, and not warn again. You should only do that, if you are sure that your tests will still be executed correctly. As we sometimes get compatibility problems ourselves and cannot always immediately find the reason, we advice you, to update the driver.

For Chrome and Microsoft Edge, where each new browser version comes with a new driver version, you find a button in the connection dialog, to download matching driver versions by expecco.

You find new driver versions at the following addresses:
{|
|Chrome/Chromium
|[https://sites.google.com/chromium.org/driver/ ChromeDriver]
|-
|Edge
|[https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft WebDriver]
|-
|Firefox
|[https://github.com/mozilla/geckodriver/releases GeckoDriver]
|-
|Internet Explorer
|[https://selenium-release.storage.googleapis.com/index.html IEDriverServer]
|-
|Opera
|[https://github.com/operasoftware/operachromiumdriver/releases Opera driver]
|-
|Safari
|[https://webkit.org/blog/6900/webdriver-support-in-safari-10 Safari Support]
|}

Download a suitable version and place it at an appropriate location in the above mentioned directory. expecco will then find and use it.  Alternatively, you can set the path to a driver either in the [[#Advanced_Settings | connection editor]] or in the [[#Plugin_Settings | plugin settings]].

[[Datei:bulb.png|20px]]Please verify that the driver's version is compatible with the browser version. If in doubt, consult the version history (e.g. for Chrome: https://chromedriver.storage.googleapis.com/2.25/notes.txt).

[[Datei:bulb.png|20px]]Notice: For Internet Explorer, "<code>Protected Mode</code>" settings must be set to the same value for all zones, to be able to start a connection. (in the Internet Explorer, open "Settings" - "Internet Options" - "Security", and set the value of "protected mode" to the same in all 4 zones; otherwise, you'll get error- and warning dialogs when connecting). See also the [https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver#required-configuration required configuration] to use InternetExplorerDriver.

[[Datei:bulb.png|20px]]Also notice: the plugin uses JavaScript for some advanced functions, and those functions require that JavaScript is enabled in the browser. This is especially needed to use the GUI browser and the recorder. Test execution may be possible without JavaScript, as long as no actions are used which rely on JavaScript.
If you get an error like <code>"org.openqa.selenium.JavascriptException: Error executing JavaScript"</code>,
make sure that JavaScript is enabled in the browser and that the versions of the browser and the associated driver are compatible.

=Additional Uses=
{|
|[https://github.com/appium/appium-for-mac AppiumForMac]
|WebDriver to control OS X apps (i.e. also non-Browsers)
|-
|[https://github.com/microsoft/WinAppDriver WinAppDriver]
|WebDriver to control Windows Desktops
|}

Notice, that these interfaces usually provide a subset of the functionality provided by special plugins, such as Java-GUI or WindowsAutomation plugins. Usually, they are ok to manipulate the top level window or to confirm simple dialogs, but less usable for more complex UI tests.

= Quick Start =
== Open Browser / Connecting ==
* Start expecco
* Click on "''New Testsuite''"
* Click on the GUI-Browser symbol ([[Datei:GUIBrowser.png|24px]])
* A new Tab appears, containing the GUI-Browser
* Click on "''Connect''" and choose "''Selenium Testing''". The [[#Connection Editor | Connection Dialog]] appears (see details below)
* Choose the type of browser (eg. "<code>firefox</code>" and enter the URL of the tested web site (eg. "<code><nowiki>http://www.myHost.com</nowiki></code>") and )
* Click on "Connect"
* A browser is started automatically, and the page is shown
* As soon as the connection is established, the page's elements are shown in the GUIBrowser's left tree view

== Start a Recording ==
* After a connection has been established, click on the record icon ([[Datei:Recording.png|16px]]) in the GUIBrowser.

== Inspecting Elements ==
* Select an element in the browser's element-tree, or move the mouse over it in "follow-mouse mode". If your browser does not support this "follow-mouse" mode, try opening a recorder, and move the mouse there.
The element's attributes are shown in the lower-center attribute/property list.
== Manually adding Actions and Checks ==
* In addition to recording, actions and checks can also be selected from the upper-centre action list. Select one there and either try it immediately or add it to the recording sequence via the add-action button at the top far right.

=Connecting=
==Connection Editor==
The connection editor defines, changes or starts a connection. Open the GUI browser, click on "''Connect''" and select "''Selenium Testing (WebDriver)''". You can also create attachments or files containing connection parameters ("''connection settings''") without actually connecting to/opening a new browser connection via the "''Save Connection Settings''" menu item.

When opened, the connection editor presents a number of fields and load/save buttons in its toolbar menu:

[[Datei:SeleniumWebDriverConnectDialog.png]]

#''Load settings from attachment'': Open an attachment containing connection settings from an open project. This settings will be added to the editor. Already entered inputs that are not conflicting will remain unchanged.
#''Load settings from file'': Open a saved settings file (*.csf). Its settings will be added to the editor. Already entered inputs that are not conflicting will remain unchanged.
#''Save settings as attachment'': Save all entered settings as attachment in an open project.
#''Save settings as JSON attachment'': Save all entered settings in JSON format as attachment in an open project.
#''Save settings to file'': Save all entered settings to a file (*.csf).
#''Version info'': Opens a window showing the used versions of the Selenium server, the selected browser and its driver.
#''Online documentation'': Open this online documentation page.
#''Connection name'': Enter the name of the connection used to show it in the GUI browser. (Optional)
#''Browser type'': Choose the type of browser to use. Ensure it is installed and the version of the used driver is compatible with the browser version.
#''URL'': Enter the URL to open at startup. To open an empty browser window, leave this field empty. To open a local file use the "<code>file://</code>" scheme, e.g. "<code>file:///C:/Users/admin/Desktop/index.html</code>".
#''Advanced view'': Toggle the view to enter [[#Advanced Settings|advanced settings]].
#''Information on the selected browser'': Here, the selected browser type is shortly characterized.
#''Information on the settings'': It shows which Selenium, browser and driver version will be used regarding the current settings. If you have set [[#Advanced Settings|advanced settings]], they will also be displayed here.

===Advanced Settings===
Besides the used browser and the start URL, more settings and possibly "''capabilities''" may be required. To see click on the "Advanced" toggle. Depending on the selected browser type you get different entry fields.

*''Remote Server'': To open a browser on a remote host, start a Selenium server there and set this field to its address. You can also enter a local address if you do not want the Selenium server to start automatically or if it is already running. See the next section [[#Remote Connections|Remote Connections]] on how to start a Selenium server.

*''Headless'': to open the browser in "headless" mode, i.e. without a window. Not all browsers/drivers support this mode.

*''Binary'': Enter the path to the binary of the selected browser. Use this if the browser cannot be found automatically by Selenium, or if you have another browser version installed or to be tested against.

*''Driver'': For each browser, a particular driver is needed for automation. New browser versions often also need a new driver version. If you don't want or cannot use the driver provided by expecco, set its path here.

*''Command Line Options'': arguments passed to the browser-command. For example the chrome browser supports a "--disable-extensions" command line argument, firefox supports "--safe-mode" and "--profile". These options are browser- and possibly browser-version specific. Most browsers allow for a "--help" argument, which you may try in a shell window to find out.

*''Firefox Profile'': For Firefox, it is possible to set a ''Firefox Profile'', containing specific settings. If no profile is set, each connection will use a new empty one.

*''Capabilities'': Selenium connections can use several capabilities to define the connection's behavior. To add specific capabilities, set them in this field. Write "''<capability name>: <value>''" or "''<capability name> = <value>''", one entry per line.The set of capabilities needed or supported are browser- and driver specific. Please refer to the concrete driver's documentation as found via the driver links above. Common capabilities are: "app" or "application", "url", etc. For drivers which communicate with mobile devices, the capabilities also select which device to use and/or wether an emulator should be started.You can also set properties for the Firefox browser - for this, use the same syntax as for capabilities, but add a leading ''$'' to the property name.Properties used by expecco internally (such as browser type, url or remote host) are prefixed by a "#"-character.

==Remote Connections==
To start a browser on a remote computer, copy the Selenium server and the required driver to that computer. You find the files in your expecco installation at "<code>packages\exept\expecco\plugin\seleniumWebDriver\lib</code>". Start the Selenium server (on the remote host) with:
java -jar selenium-server-standalone-3.6.0.jar
By default, the server will listen on port 4444. To use another port, set it with the "<code>-port <nr></code>" command line argument. To connect to that server, set the "''remote server''" parameter of the connection to "''<Server-Address>:4444/wd/hub''".

Check and possibly configure your firewall to allow transmission through the port.

== Headless Browsing ==
"''Headless Browsing''" means: "''without a window''", and is useful to test web-pages for reachability, performance and structure. You can either use the HTMLUnit browser type, which simulates a browser, or run against one of the real browsers in headless mode. Notice, that not all browsers support this headless mode - we recommend using "firefox" or "chrome" for this.

Also notice, that in order to verify that a web page's interaction with a browser works correctly, you should test against real browsers.
For an introduction on what "headless browsing" means, see for example [https://www.guru99.com/selenium-with-htmlunit-driver-phantomjs.html https://www.guru99.com/selenium-with-htmlunit-driver-phantomjs.html].

Notice: the HTMLUnit driver has been removed from the latest selenium distribution and is also no longer supplied with expecco (it was not a good test tool anyway, as it behaved differently from real browsers).
 If required, download from [https://github.com/SeleniumHQ/htmlunit-driver https://github.com/SeleniumHQ/htmlunit-driver].

==Connection Blocks==
SeleniumWebDriverLibrary offers a number of blocks to start a Selenium connection within a testrun. The ''connection name'' identifies the connection during the run, if the test uses multiple connections and switches between them (eg. if multiple browser windows are open simultaneously). To start a connection with predefined settings, save them in the connection dialog (as attachment), and use the "[''Connect From File'']" action block.

=Plugin Settings=
To use certain browser installations or drivers as default, for every connection, set them in the settings dialog of the plugin ("''Extras''" → "''Settings''" → "''Plugins''" → "''Selenium WebDriver Extension''"). Settings for specific browsers can be found under "''Most Popular Browsers''" or "''Other Browsers''". The settings there are used as default, unless overwritten by an individual connection configuration.

===Execution Delay for Chrome===
In some cases it can happen when using the Chrome browser that blocks with element actions, for example a click, run successfully in the test, but the actual action was not executed at all. This is a known bug [https://github.com/MPDL/imeji-gui-testing/issues/37], [https://github.com/SeleniumHQ/selenium/issues/4075] that needs to be fixed by Selenium or Chromedriver. The error can be prevented by either calling the click via JavaScript – to do this, set ''invokeDirectly'' to ''true'' at the click block – or wait briefly before the action. Execution via JavaScript has the disadvantage that it is less close to the click of a real user and, for example, clicks on elements work even if they are hidden by other elements. In general, blocks with element actions automatically wait until the corresponding element is available. In the cases described here, however, this is not sufficient. Therefore you will find the setting ''execution delay'' in the plugin settings for Chrome. During execution, the system waits accordingly long between each action. If you experience the described error, you can increase its value. Of course, a higher value has an effect on the test run executio times.

=Recorder=
The following description applies to all GUI technologies which support remote recording in the integrated expecco recorder: the behaviour of the recorder is (apart from small differences due to technology-specific limitations) the same across different connections.

Use of this recorder has some advantages over direct recording in the browser:
* it can be used with remote machines/connections/mobil devices especially for mobile devices, which may be all located in a separate (server-) room
* it provides precise control over which event is to be recorded. For example, for clicks, there are alternative ways to record: as "press-release", as "click", as "move-then-click", as "move-then-press-delay-release". Depending on the page's underlying event handling (typically done in JavaScript), either one may be required.

Once connected to a browser, the integrated recorder can be used to record a test case. Start the recorder by selecting the appropriate connection in the GUI browser's left tree and click the ''record'' button. The recorder opens a new window. Each click in the window records an action. More actions are available in the menu. Recorded actions are added to the ''workspace'' of the GUI browser to form a sequence of interactions. This sequence can be edited, parametrized or replayed immediately. When finished, it should be saved into the suite as a new "Test Action".

General actions can be found either directly in the menu bar or there in the Browser Tools menu (see below). To record actions on elements, either change the selection of the element tool in the menu bar (see below) and click on the element or select the corresponding action from the context menu by right-clicking on the element. For text input, you can also place the cursor over the element and enter the text. The input dialog for this action opens. It is also possible to record the imputs ''backspace'', ''return'' and ''tab'' that way.

[[Datei:SeleniumWebDriverRecorder.png]]

'''Components of the recorder window'''
#'''Pause recording''': If the control lamp is red, the recorder is in "''recording''"-mode. Pause the recording by clicking on this lamp. The lamp will turn to grey. In this state you can execute actions with the recorder, but they are not recorded. Click again to resume the recording.
#'''Update''': Update the screenshot on the element tree. Necessary if the recorder view does not fit the browser content.
#'''Follow-Mouse''': The element under the cursor is selected in the GUI browser.
#'''Element Highlighting''': The element under the cursor gets a red frame.
#'''Element Tools''': Select which tool to use for recording. You can choose between all actions that use a certain element. The selected action is triggered by each click in the view and the element is determined by the click position. Not selected actions are available by right click.
#'''Browser Tools''': Actions not refering to ocertain elements, like scrolling or actions on the current URL or the title, can be triggered here.
#'''Page navigation''': Actions for page navigation: ''Back'', ''Forward'' and ''Refresh Page''
#'''Alert Handling''': Click this button if the browser shows an alert, to be able to select the actions for alert handling.
#'''Online Documentation''': Open this online documentation.
#'''View''': Shows a screenshot of the browsers. Actions can be triggered by mouse depending on the selected tool. If a new action can be entered, the frame of the window is green, red otherwise. Scrolling is forwarded to the browser, but not recorded.
#'''Resize Window to Screen Size''': Change the size of the window to show the whole screenshot.
#'''Set Screen Scale to Fit Window''': Scale the screenshot to fully fit in the window
#'''Scale''': Changes the scale of the screenshot. Can also be adjusted by scrolling with pressed <kbd>CTRL</kbd> key.
#'''Notifications''': Shows notifications, e.g. if an action cannot be recorded. The last notification is displayed until it is closed by the button on its right side. '''Window Tabs''': As of expecco 23.1, tabs are displayed above the display for each open window as soon as a connection has more than one browser window. Whether the browser displays this as a tab or in its own window does not matter. You can use the tabs in the recorder to switch the current window and also record this switch. '''Frame context''': As of expecco 23.1, you can see below the display in which frame context you are currently in (see the section [[#Embedded_Content|Embedded Content]]). You can click on the entries to switch to a higher context and record this switch. If you have compound paths enabled, the display will update when you select an embedded item.

=Embedded Content=
In HTML it is possible to include content from another page within one page. The most common element to do this is an iframe (inline frame). The content of an iframe can also be accessed with Selenium, but first you have to switch to this context. In the SeleniumWebDriverLibrary there are corresponding blocks to switch to the context of an iframe, to switch to the parent context and to switch back to the default content, i.e. the top context. All element blocks always resolve the applied paths within the current context. In the GUI browser, you will see an additional element for embedded content, which you can expand to see its elements.

==Compound Paths==
Since expecco 23.1 there is the possibility to also use compound paths at the blocks to access the content of an iframe directly from the standard content. For this purpose, simply the path to the iframe and the path within the iframe content are combined into one. It is important here that no elements may be omitted at the transition, i.e. the front part must end with the iframe element and the back part must begin with ''/body''. In between the paths may be shortened and it is of course also possible to access elements nested to any depth in this way. Both techniques can be used on the blocks as desired, the only important thing is that the paths are always resolved in the context in which Selenium is currently located.

If you want to record the combined paths or use them in the GUI Browser, check the box ''Record Compound Paths'' in the ''GUI Browser'' menu under ''Recording''. This will create and display a compound path for embedded elements relative to the current context, instead of only within its own context as before. You can also address these elements directly in the recorder or find them via Follow-Mouse.

=Shadow Elements=
Shadow DOMs allow you to encapsulate parts of a page from the remaining document. They provide a way to attach hidden shadow elements to an element. You can find a more detailed explanation for example here: [https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM Using shadow DOM - Web APIs | MDN].

The SeleniumWebDirverLibrary has the block ''[Web] Get Shadow DOM'', which gives you the topmost elements, which then can be used like other WebElements.

As the elements are hidden, they are not directly displayed in the GUI browser. However, since expecco 23.1 you can check in the context menu of the elements in the GUI browser the option to find shadow elements. They then will be displayed when updating the children of an element, if there are any, but not when updating the whole tree. If the option is checked, the elements are also available in the recorder.

==Compound Paths==
Similar to elements inside a frame, shadow elements can be accessed by compound paths. These paths can be used directly at the library blocks and the block ''[Web] Get Shadow DOM'' is not required. The paths are of the form
<host path>/shadowRoot/<shadow path>
where ''<host path>'' denotes the path to the element that has the shadow DOM attached, and ''<shadow path>'' denotes the path inside the shadow DOM to the desired element. '/shadowRoot' serves as marker where the switch to the shadow DOM is needed.

=Authentication Alerts=
If a Web page uses HTTP authentication with Basic Authentication, an alert window for entering the user name and password opens when the page is loaded. This window cannot be accessed directly with Selenium. In the GUI browser, it is displayed as an alert. An exception to this is Chrome, where the driver does not respond to any request as long as the dialog is open. At this point, the plugin cannot even determine whether an authentication dialog is open or whether the driver is not responding for other reasons.

For local connections under Windows, authentication can be performed using Windows Access. In the SeleniumWebDriverLibrary there are specific authentication blocks for individual browser types as well as the block ''Authenticate at Alert'', which executes the corresponding block depending on the connection. There are different restrictions for the different browser types:

:'''Chrome:''' The credentials are sent to a chrome window, so it only works if not more than one are open. In this case, the single block has the option to specify the title of the window.
:'''Edge''': With Microsoft Edge a login is not supported.
:'''Firefox''': Sends the credentials to a Firefox dialog box and therefore only works if there are not multiple ones.
:'''Internet Explorer''': With Internet Explorer a login is not supported.

As an additional option, you can also log in using the URL. Instead of the page <nowiki>https://www.example.com</nowiki> call the URL <nowiki>https://user:password@www.example.com</nowiki>. It is important that '':'' and ''@'' do not appear in the user name or password. This method may not be supported by every browser.

With the [[WindowsAutomation_Reference_2.0/en|WindowsAutomation2]]-Plugin it is also possible to execute such a login with all browser types.

=Transferring Old Selenium Tests=
This Plugin replaces the previous [[Selenium_Web_Test_Plugin|Selenium Web Test Plugin]], which is based on [https://www.seleniumhq.org/projects/remote-control/ Selenium RC]. Selenium RC is no longer supported by their authors and it will also no longer be maintained by exept. The successor is [https://www.seleniumhq.org/projects/webdriver/ Selenium WebDriver], also referred to as Selenium 2.

Recording of test actions using [https://www.seleniumhq.org/projects/ide/ Selenim IDE] is also outdated, as the plugin is not supported by newer browsers. The ''Selenium WebDriver Plugin'' uses its own [[#Recorder|Recorder]] instead.

Tests which were created with the old ''Selenium WebTest Plugin'' using SeleniumLibrary can be executed with the new Selenium WebDriver.
For this, go to the plugin settings of "''Webtest Legacy (Selenium)''" and check "''Use WebDriver for execution''". Please verify that your tests are still running after this change, as there is no 100% backward compatibility (which is outside the scope of expecco). However, most of the old test actions should run without problems.

=FAQ=
*'''Scrollbars cannot be handled in the recorder'''
:The scrollbar of the browser which is diplayed if a page is larger than the browser window is no controllable web element. Mostly it is useless to scroll by a certain amount in a test where the size of the browser window is not defined. Instead, use the block <code>[Web] Scroll Element into View</code> to scroll a relevant element to the visible region. The default click block used by the recorder already includes this action (<code>[WebElement] Click (Scroll Element into View)</code>). If you scroll on the recorder window, the action will also be applied to the browser, but is not recorded. If you actually want to scroll by a certain amount, there is an appropriate entry in the browser actions, and more blocks in the SeleniumWebDriverLibrary.

*'''Block fails if element becomes visible too late'''
:All blocks that use an element path have built in that they wait until a corresponding element appears. However, there are cases where an element is already there, but not yet visible. If you click on the element you will get an error. Possible errors in this context are <code>org.openqa.selenium.ElementNotInteractableException: element not interactable</code> and <code>org.openqa.selenium.JavascriptException: javascript error: Cannot read property 'left' of undefined</code>. In this case, use the <code>[Web] Wait for Visibility of Element</code> block or <code>[Web] Wait for Element to Be Clickable</code> before interacting with the element.

*'''Error message <code>Cannot read property 'left' of undefined</code>'''
:The error <code>org.openqa.selenium.JavascriptException: javascript error: Cannot read property 'left' of undefined</code> can occur with the Chrome browser. This means that the used element is not visible. See the point above on that. The error is also known in combination with elements in a dropdown list, i.e. when clicking or moving the mouse over a <nowiki><option></nowiki> element within a <nowiki><select></nowiki> element. Such elements are generally not clickable. Instead, use a suitable <code>[Web] Select</code> block with the <nowiki><select></nowiki> element.

*'''Error message: <code>Stale Element Reference Exception</code>'''
:The error <code>org.openqa.selenium.StaleElementReferenceException</code> occurs whenever a WebElement is used that is no longer there. If that happens during your test and the element should have been there, try using the locator instead to fetch the element again. Maybe the error occurs because the test is currently in a different frame context as the element. If you are using [[#Compound_Paths|compound paths]], the element should switch by itself to the correct context when it is used.
:In rare cases this error can also occur in expecco itself, if at somewhere in the GUI browser or the recorder such a WebElement is used. You should then be able to abort and try again. Should the error persist, switch to the default content and refresh the tree in the GUI browser.

*'''Block runs successfully, but without effect'''
:This case can occur with Chrome. The element is available, the action does not throw an error, but nothing is executed. Usually it helps to wait briefly before the execution, see [[#Execution_Delay_for_Chrome | Execution Delay for Chrome]].

*'''Executions using Chrome are slower'''
:To fix a problem when executing with Chrome, a delay is defined in the plugin settings for Chrome. Check if this value is possibly too high; see [[#Execution_Delay_for_Chrome | Execution Delay for Chrome]].

*'''Errors like: "org.openqa.selenium.InvalidArgumentException: Expected "handle" to be a string..."'''
:This occurs if the driver does not match the browser (any more). Please read the above chapter "[[#Update WebDriver|Update WebDriver]]".

*'''Key Chords with Shortcuts are not working'''
:Pressing keys simultaneously can be simulated using Key Chords. They can also be used to send shortcuts. However, not all inputs will work, as they are only sent to the page content, not to the browser itself. Combinations like ''Ctrl + t'' to open a new browser tab probably wont't work, ''Ctrl + a'' and ''Ctrl c'' on the other hand should be effective.

*'''Additional Window Handles for Opera'''
:The Opera browser returns more window handles as there are opened tabs or windows. They represent Opera internal features like ''Speed Dial'' or ''Better Address Bar Experience'' (BABE), which are embedded in the browser window, but not displayed like regular tabs. You can switch to these tabs using an appropriate action block, however not all actions are possible then, which can be used with the normal tabs. For example you cannot close them and they don't provide a screenshot. Therefore it is better to not even switch to their contexts. So be careful when switching to a tab by index, as the Opera tabs are among the others and the index might be a different one than for the other browser types.

*'''Chrome: Choose your search engine'''
:Newer versions of Chrome show an [https://www.google.com/chrome/choicescreen/ overlay] at startup, where you have to choose a search engine. Usually, this choice is saved in the user profile. However, if you don't explicitly set a Chrome profile for the connection, each connect will use an empty profile and this question will always show up.

:In most cases, the test can run in the back despite the overlay. However, the overlay counts as tap or window, meaning the block ''[Web] Get Window Handles'' for an example returns a window handle for it and you can switch to it. But you have options to get rid of it:
:* ''--disable-search-engine-choice-screen'': In the [[#Advanced_Settings|advanced settings]] you can add the option <code>--disable-search-engine-choice-screen</code> and the overlay won't show up.
:* ''Choose'': You can extend your test, so it actually chooses a search engine and closes the overlay. There are two things you need to bear in mind. First, you have to switch there using a ''Switch to Window'' block (e.g. by index ''2'' or with an empty title) and back to your original tab afterwards as well. Secondly, the interesting elements in the overlay are [[#Shadow_Elements|shadow elements]] and as such not directly displayed in the GUI-Browser.

*'''Firefox: <code>Process unexpectedly closed with status 0</code>'''
:Error pattern: The connection to the Firefox browser fails with the error message <code>org.openqa.selenium.WebDriverException: Process unexpectedly closed with status 0</code>. However, the browser eventually opens without there being a connection in expecco.
:A known cause of this issue is that the browser is started for the first time after an update, which the browser cannot handle properly in the automated state. The second attempt should then be successful. To prevent this error, make sure that you always start the browser normally the first time after an update.

Selenium WebDriver Plugin

2024-08-22T15:02:28Z

Matilk: /* FAQ */ Firefox nach Update

'''Deutsche Version''' | [[Selenium_WebDriver_Plugin/en|English Version]]
=Achtung=
Das Webtest Selenium WebDriver Plugin ersetzt das bisherige [[Selenium_Web_Test_Plugin|Selenium Web Test Plugin]]. Zur Automatisierung wird [https://www.seleniumhq.org/projects/webdriver/ Selenium WebDriver] verwendet (Driver für gängige Browser werden von uns mitgeliefert), der das bisher verwendete Selenium RC ersetzt. Dies wurde einerseits notwendig, da die SeleniumRC Schnittstelle von neuen Browsern nicht mehr unterstützt wird, andererseits, sinnvoll, da auch andere UI Technologien mit diesem Protokoll angesprochen werden können.

Sie können dieses Protokoll nur noch mit älteren Browsern verwenden, und wir empfehlen dringend, auf die neue Version umzusteigen. Hinweise zur Migration älterer Testsuiten finden Sie [[#Portierung_alter_Selenium-Tests | unten]].

=Einleitung=
Mit dem Selenium WebDriver Plugin können Sie Tests von Webapplikationen erstellen oder auch diese automatisieren (*). Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests oder automatisierten Browseraktionen unterstützt. Zudem ist damit das Aufzeichnen von Abläufen möglich.

(*) tatsächlich gibt es auch WebDriver-Schnittstellen um z.B. Windows-Apps oder OPS-Fenster zu manipulieren. Insofern gibt es für dieses Plugin weitere Einsatzbereiche.

=Einstellungen=
Das Plugin verwendet die Java-Bridge und benötigt daher eine Java-Installation. Sie können diese in den Einstellungen unter ''Erweiterungen'' -> ''Java Bridge'' angeben. Wichtig ist hier das Feld ''Pfad zur Java-Installation'', wo Sie ein JDK oder JRE angeben können. Ist nichts angegeben, versucht expecco java im PATH zu finden.

[[Datei:JDKPfadEinstellungen.png|600px]]

Für das Selenium WebDriver Plugin selbst gibt es ebenfalls Einstellungsmöglichkeiten, die Sie unter ''Erweiterungen'' -> ''Webtest (Selenium WebDriver)'' finden. Hier können Sie zum Beispiel die Adresse zu einem remote laufenden Selenium-Server angeben oder eine andere Jar-Datei für Selenium angeben. Einstellungen zu den verschiedenen Browser-Typen teilen sich auf die Unterseiten ''Beliebte Browser'' und ''Andere Browser'' auf. Dort können Sie den Pfad zur Browser-Ausführungsdatei oder zum Webdriver angeben, der verwendet werden soll. Diese Felder können Sie alle leer lassen, expecco wird dann automatisch danach suchen.

=Browser-Unterstützung=
Das Plugin unterstützt die Browser Chrome/Chromium, Edge, Firefox, Internet Explorer und Opera.
 Safari unter OSX muss zumindest in der Version 10 vorliegen und OSX muss mindestens die El Capitan Version sein.
Zur Kommunikation wird die WebDriver Schnittstelle verwendet; somit kann der getestete Browser sowohl lokal als auch auf einem entfernten Rechner laufen.

Da inzwischen eine Vielzahl von weiteren Browsen, Geräten und graphischen Oberflächen eine WebDriver Schnittstelle anbieten, können auch diese - z.T. mit eingeschränktem Funktionsumfang - über diese automatisiert werden. So gibt es z.B. auch Schnittstellen für Windows Mobilgeräte oder Desktopanwendungen.

== WebDriver aktualisieren==
Für jeden Browsertyp gibt es einen Driver, über den das Starten und Ansteuern der Browserfenster funktioniert. Für die wichtigsten Browser finden sich im Lieferumfang aktuelle Driverversionen. Da die Browser fortlaufend aktualisiert werden, teilweise sogar automatisch, müssen Sie früher oder später neue Driverversionen herunterladen. Legen Sie diese dann in Ihrem expecco-Installationsverzeichnis bei den anderen Versionen ab, und zwar unter:
<code>packages/exept/expecco/plugin/seleniumWebDriver/lib/XXX</code>
(unter Microsoft Windows Betriebssystemen mit "\” anstatt "/"), wobei "XXX" für das Betriebssystem steht (Windows, Linux, OSX etc.).

Im Verbindungsdialog warnt expecco, wenn eine Driverversion nicht zur Browserversion passt. In manchen Fällen kann das aber auch nur daran liegen, dass diese Version zum Zeitpunkt der Auslieferung noch nicht bekannt war. Manche Kombinationen können trotz der Warnung funktioniert, aber das können wir im Einzelfall nicht garantieren.

Daher können Sie bei einer solchen Warnung immer die Option "''Diese Warnung nicht mehr anzeigen''" anwählen, damit diese Driver-Browser-Versionskombination in ihren Settings als "kompatibel" vermerkt wird, und in Zukunft nicht mehr gemeldet wird. Dies sollten Sie aber nur machen, wenn Sie sicher sind, dass Ihre Tests nach wie vor korrekt ausgeführt werden. Da wir hier selbst bisweilen auf Kompatibilitätsprobleme stoßen, und nicht immer gleich klar ist, woran es liegt, empfehlen wir aber den Driver zu aktualisieren.

Für Chrome und Microsoft Edge, bei denen es für jede neue Browserversion auch eine neue Driverversion gibt, finden Sie im Verbindungsdialog einen Button, um mit expecco die passende Version herunterzuladen.

Neuere Versionen der Driver bekommen Sie an folgenden Adressen:
{|
|Chrome/Chromium
|[https://sites.google.com/chromium.org/driver/ ChromeDriver]
|-
|Edge
|[https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft WebDriver]
|-
|Firefox
|[https://github.com/mozilla/geckodriver/releases GeckoDriver]
|-
|Internet Explorer
|[https://selenium-release.storage.googleapis.com/index.html IEDriverServer]
|-
|Opera
|[https://github.com/operasoftware/operachromiumdriver/releases OperaDriver]
|-
|Safari
|[https://webkit.org/blog/6900/webdriver-support-in-safari-10 Safari Support]
|}

Laden Sie sich eine passende Version herunter und legen Sie sie im oben genannten Verzeichnis an der entsprechenden Stelle ab. Expecco wird sie dann finden und verwenden.  Alternativ können Sie auch in expecco den Pfad zu einem Driver angeben, entweder im [[#Erweiterte_Einstellungen | Verbindungseditor]] oder in den [[#Plugin-Einstellungen | Plugin-Einstellungen]].

[[Datei:bulb.png|20px]]Bitte verifizieren Sie, daß die Version des Drivers kompatibel ist mit der des Browsers. Im Zweifel suchen Sie nach der Versionshistorie (z.B. für Chrome: https://chromedriver.storage.googleapis.com/2.25/notes.txt).

[[Datei:bulb.png|20px]]Für den Internet Explorer ist zu beachten, dass der geschützte Modus für alle Zonen gleich eingestellt sein muss, damit eine Verbindung möglich ist. (im Internet Explorer: "''Einstellungen''" - "''Internetoptionen''" - "''Sicherheit''" öffnen, und bei allen 4 Zonen "geschützter" Bereich gleich einstellen; ansonsten kommen beim Verbindungsaufbau Fehler- und Warndialoge). Siehe außerdem die [https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver#required-configuration erforderliche Konfiguration] zur Verwendung des InternetExplorerDrivers.

[[Datei:bulb.png|20px]]Das Plugin verwendet für einige Funktionen JavaScript. Stellen Sie daher sicher, dass die Ausführung von JavaScript im verwendeten Browser erlaubt ist, insbesondere wenn Sie den GUI-Browser oder den Recorder verwenden wollen. Das Ausführen von Tests ist auch ohne JavaScript möglich, solange keine Aktionen verwendet werden, welche JavaScript benötigen oder explizit ausführen. Sollten Sie einen Fehler der Art "<code>org.openqa.selenium.JavascriptException: Error executing JavaScript</code>" bekommen, stellen Sie sicher, dass die Ausführung von JavaScript im verwendeten Browser erlaubt ist und Browser- und zugehörige WebDriver-Version kompatibel sind.

= Headless Browser =
Mit "''Headless''" bezeichnet man eine Anwendung, welche ohne Bedienoberfläche abläuft. Einige der Browser unterstützen einen "headless" Modus, bei dem kein Browserfenster angezeigt wird. Der Browser operiert dabei in einem "unsichtbaren Fenster" führt aber alle Operationen aus, und liefert auch die selbe Elementhierarchie.
Bei einigen Browsern sind allerdings die Screenshot (Bild vom Fenster bzw. von Elementen) eingeschränkt bzw. gar nicht verfügbar. Den "headless" Modus können Sie beim Verbindungsaufbau in den "''Advanced Settings''" angeben.

= HTML Unit Browser =
Bei diesem "''Pseudobrowser''" handelt es sich um eine weitere "''headless''" Variante, welche ganz ohne Renderengine operiert, und lediglich die Elementhierarchie sowie Javascript unterstützt. Sein Verhalten kann stark von dem "echter" Browser abweichen.

Diesen Browsertyp können Sie verwenden, wenn ihr Test das Verhalten des Webservices (also der Servierseite) betrifft, und nicht das Verhalten der Anwendung im Browser (End-User-Experience) im Fokus hat. Zum Beispiel kann der "HTML Unit Browser" zum Generieren von Last oder gleichzeitigen Aktionen gegenüber dem Server dienen.
Da sich dieser Browser im Verhalten z.T. stark von dem echter Browser unterscheidet sollte er nur (wenn überhaupt) in besonderen Fällen verwendet werden.

= Schneller Einstieg =
== Browser öffnen / verbinden ==
* Starten Sie expecco
* Klicken Sie auf "''Neue Testsuite''"
* Klicken Sie auf das GUI-Browser Symbol ([[Datei:GUIBrowser.png|24px]])
* Es erscheint der GUI-Browser in einem neuen Reiter
* Klicken Sie auf "''Verbinden''" und wählen Sie "''Webtest (Selenium WebDriver)''" aus. Dann erscheint der [[#Verbindungseditor | Verbindungsdialog]] (Details siehe unten)
* Im Verbindungsdialog geben Sie die zu testende Webseite ein (z.B. "<code><nowiki>http://www.myHost.com</nowiki></code>") und wählen den Browsertyp (z.B. "<code>chrome</code>" oder "<code>firefox</code>") aus
* Klicken Sie auf "''Verbinden''"
* Ein Browser wird nun automatisch gestartet, und die Seite angezeigt.
* Sobald die Verbindung steht, wird im GUIBrowser die Seitenstruktur als Baum angezeigt, und im rechten Diagramm-Fenster erscheint ein passender Verbindungsbaustein. Dieser wird nicht automatisch aufgezeichnet, da man diesen normalerweise nicht in jeder aufgezeichneten Sequenz haben will (mehr dazu unten).

== Recording aufnehmen ==
* Klicken Sie auf das Recording Symbol im GUI-Browser.
[[Datei:Recording_Start.png | 200px]]
* Ein Recorderfenster erscheint (eine Beschreibung der Bedienelemente finden Sie unten)
* Sie zeichnen nun direkt im Rekorder auf. 
* Klicks werden je nach Einstellung als Klick, Mausbewegung, Drag&Drop etc. aufgezeichnet. Während der Aufzeichnung können Sie zwischen diesen Werkzeugen wechseln: 
[[Datei:Recorder_Werkzeuge.png | 300px]]
* die aufgezeichneten Aktionen werden im Tab "''Aufgezeichnete Sequenz''" dargestellt. Sie können dort noch bearbeitet werden.
* Zum Beenden der Aufzeichnung klicken Sie entweder auf den "''Stop Recording''" Knopf im GUI Browser, oder schließen das Rekorderzenster. Es ist auch möglich, das Aufzeichnen temporär zu Pausieren, indem sie im Rekorder auf den "''Aufnahme''"-Knopf oben links drücken.
* Nach dem Aufzeichnen können sie die Sequenz un ihre Testsuite als Testfall oder Teilsequenz übernehmen.

== Aufgezeichnete Aktion wiedergeben ==

* Im Reiter "''Aufgezeichnete Sequenz''" kann die aktuelle Aufzeichnung sofort wiedergegeben werden ("''Play''"-Knopf drücken) Beachten Sie, daß ihre Webseite üblicherweise im gleichen Zustand sein sollte - gegebenenfalls sollten Sie also den "''Back''"-Knopf oder eine andere Navigation anwenden, um dies sicher zu stellen.
* Die Sequenz kann bearbeitet werden. Dazu können entweder weitere Aktionen aufgenommen werden, oder zusätzliche Aktionen entweder via Drag&Drop oder über das Kontextmenü (bzw. <kbd><CTRL-N</kbd>) angelegt werden. Häufig werden zusätzliche Delay- oder Verifikations-Bausteine benötigt, die sie hiermit an geeigneter Stelle einfügen können.

=Verbindungsaufbau=
==Verbindungseditor==
Mit dem Verbindungseditor werden Verbindungen definiert, geändert und aufgebaut. Sie erreichen ihn, indem Sie den GUI-Browser öffnen und dort auf "''Verbinden''" klicken und dann "''Selenium Testing (WebDriver)''" auswählen.

[[Datei:SeleniumWebDriverConnectDialog.png]]

#''Einstellungen aus Anhang laden'': Öffnet einen Anhang im expecco Projekt mit Verbindungseinstellunge. Diese Einstellungen werden in den Editor übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#''Einstellungen aus Datei'': Öffnet eine gespeicherte Einstellungsdatei (*.csf). Diese Einstellungen werden in den Editor übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#''Einstellungen in Anhang speichern'': Hier können Sie die eingetragenen Einstellungen als Anhang im expecco-Projekt anlegen.
#''Einstellungen in JSON-Anhang speichern'': Hier können Sie die eingetragenen Einstellungen im JSON-Format als Anhang im expecco-Projekt anlegen.
#''Einstellungen in Datei speichern'': Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern.
#''Versionsinfo'': Zeigt ein Fenster mit den verwendeten Versionen des Selenium-Servers, des ausgewählten Browser und dessen Driver an.
#''Online-Dokumentation'': Öffnet diese Online-Dokumentation.
#''Verbindungsname'': Tragen Sie hier den Namen ein, unter dem die Verbindung im GUI-Browser angezeigt werden soll. (Optional)
#''Browsertyp'': Wählen Sie hier aus, welchen Browser Sie verwenden möchten. Stellen Sie sicher, dass dieser installiert ist und die Version des verwendeten Drivers zur Browserversion passt.
#''URL'': Tragen Sie hier die URL ein, die zu Beginn aufgerufen werden soll. Sie können das Feld auch frei lassen, dann wird ein leeres Browser-Fenster geöffnet. Um eine lokale Datei zu öffnen, verwenden Sie das Schema "<code>file://</code>", z.B. "<code>file:///C:/Users/admin/Desktop/index.html</code>".
#''Erweiterte Ansicht'': Wechselt zur Ansicht für die Eingabe von [[#Erweiterte Einstellungen|erweiterten Einstellungen]].
#''Informationen zum gewählten Browser'': Hier wird der ausgewählte Browsertyp kurz vorgestellt.
#''Informationen zu den Einstellungen'': Hier wird angezeigt, welche Selenium-, Browser- und Driver-Version mit den aktuellen Einstellungen verwendet wird. Falls Sie [[#Erweiterte Einstellungen|erweiterten Einstellungen]] gesetzt haben, werden diese hier ebenfalls aufgelistet.

===Warnung über mögliche Inkompatibilität ===
Manche Browser benötigen einen versionsspezifischen Webdriver, da die verwendeten Kommunikationsprotokolle unterschiedlich sein können.

Da regelmässig neue Browserversionen erscheinen, und damit einhergehend auch neue Versionen des zug. Webdrivers benötigt werden, kann. es sein, dass die mit expecco mitgelieferten Webdriver nicht mehr zur aktuellen Browserversion passen. Dies trat in der Vergangenheit insbes. beim Chromebrowser mehrfach auf.

Um auf eventuelle Probleme hinzuweisen hält expecco intern eine Liste von Paaren der von exept bereits getesteten Browser- zu Webdriverversion. Falls ihr Browser aktueller ist, und nicht in der Liste enthalten ist, erscheint eine Warnung im Infobereich.

Diese erscheint nur zu Ihrer Information - in den meisten Fällen funktioniert die Interaktion mit dem Browser auch dann. Allerdings ist es in jedem Fall sinnvoll, den Driver zu aktualisieren, um solche Probleme auszuschliessen.
Wenn die Kombination ohne Probleme läuft, ist es möglich, die aktuelle Kombination in die Liste einzutragen (drücken Sie dazu auf "Diese Kombination ist in Ordnung"). Dann erschient der Warndialog nicht mehr.

===Erweiterte Einstellungen===
Neben dem zu verwendenden Browser und der Start-URL kann man noch weitere Einstellungen für eine Verbindung vornehmen. Wechseln Sie dazu im Verbindungsmenü die Ansicht über den entsprechenden Menü-Eintrag. Je nachdem, welchen Browsertypen Sie ausgewählt haben, bekommen Sie andere Eingabefelder.

*''Remote Server'': Falls der Browser auf einem entfernten Rechner gestartet werden soll, starten Sie dort einen Selenium-Server und geben Sie dessen Adresse in diesem Feld an. Natürlich können Sie auch eine lokale Adresse angeben, wenn nicht automatisch ein Selenium-Server gestartet werden soll. Lesen Sie hierzu auch den nächsten Abschnitt [[#Remote-Verbindungen|Remote-Verbindungen]].
*''Binary'': Geben Sie den Pfad zum Binary des ausgewählten Browsers an, wenn dieser nicht automatisch von Selenium gefunden wird oder Sie eine weitere Version installiert haben.
*''Driver'': Zu jedem Browser wird ein spezieller Driver zur Automatisierung benötigt. Für neue Versionen des Browsers braucht man häufig auch eine neue Version des entsprechenden Drivers. Wenn Sie nicht den von expecco installierten Driver verwenden wollen, geben Sie hier einen entsprechenden Pfad an.
*''Firefox Profile'': Für Firefox gibt es zusätzlich die Möglichkeit, ein Profil bzw. Template anzugeben, das spezifische Einstellungen enthält. Wenn keines angegeben wird, wird für jede Verbindung ein neues, leeres Profil angelegt.
*''Capabilities'': Für Selenium-Verbindungen sind einige Capabilities definiert, mit denen sich Verbindungs-Eigenschaften oder auch das Browserverhalten festlegen lassen.
Solche Capabilities können Sie sie in diesem Feld angeben. Schreiben Sie dazu ''<capability name>: <value>'' oder ''<capability name> = <value>''; jeweils ein Eintrag pro Zeile. Außerdem können Sie hier auch Eigenschaften für den Firefox-Browser setzen. Die Eingabe hierfür erfolgt wie für die Capabilities, nur dass sie dem Namen der Eigenschaft ein ''$'' voranstellen müssen.

:Angegebene Capabilities werden durch die Methode ''setCapability()'' gesetzt. Insbesondere bei der Verwendung von Chrome gibt es einige Einstellungsoptionen, die sich nicht mit dieser Methode setzen lassen, sondern beispielsweise über ''setExperimentalOption()'' angegeben werden müssen. Zu diesem Zweck haben Sie außerdem die Möglichkeit, in diesem Feld einen Methodenaufruf mit Werten anzugeben. Diese Methode wird dann auf das entsprechende Options- bzw. Capabilities-Objekt angewandt. Um die Struktur der Eingabe von normalen Capabilities beizubehalten, müssen Sie am Ende noch '':'' oder ''='' setzen, aber keinen Wert danach. Beispiel: ''setExperimentalOption(“useAutomationExtension”, false)=''

==Lokale-Verbindungen==
Um einen Browser auf ihrer lokalen Maschine zu starten, werden lediglich die Felder "''URL''" sowie "''Browsertyp''" benötigt. Als Voreinstellung für den Browser wird "<code>chrome</code>" erscheinen.

==Remote-Verbindungen==
Um einen Browser auf einem entfernten Rechner zu starten, müssen Sie zunächst den Selenium-Server und die benötigten Driver auf diesen Rechner kopieren. Auf dem Zielrechner muss Java installiert sein. Sie finden die Dateien in Ihrer expecco-Installation unter "<code>packages/exept/expecco/plugin/seleniumWebDriver/lib</code>". Sie können sich auch von [https://www.selenium.dev/downloads/ Selenium] eine aktuelle Version herunterladen.
 Starten Sie dann den Selenium-Sever (auf dem entfernten Rechner) mit:
java -jar selenium-server-standalone-3.141.59.jar
(die Versionsnummer wird in Ihren Fall eine andere sein)

Standardmäßig wird der Server dann auf dem Port 4444 Verbindungen annehmen. Um einen anderen Port zu verwenden,
geben Sie diesen auf der Kommandozeile mit "<code>-port <nr></code>" an.
 Um von expecco eine Verbindung über diesen Server herzustellen, geben Sie beim Verbindungsaufbau als Remote-Server
<Server-Adresse>:4444/wd/hub
an.

Das Starten des Selenium-Servers bzw. die Verbindung muss eventuell von der Firewall zugelassen werden.

Falls der Server beim Verbinden die jeweiligen Driver nicht finden, legen Sie diese ins selbe Verzeichnis, in dem Sie den Server starten, oder fügen Sie das Verzeichnis in dem der Driver liegt zum Pfad hinzu. Beachten Sie dabei, dass expecco verschiedene Versionen eines Driver-Typs mitliefert und diese durch einen Namenszusatz unterscheidet. Aufgrund dieser Zusätze erkennt der Server die Dateien aber häufig nicht.

Für neue Versionen von '''Microsoft Edge''', die Chromium basieren, starten Sie anstatt eines Selenium-Servers direkt den MSEdgeDriver ("msedgedriver.exe") in der Version, die zur Edge-Version auf diesem Rechner passt.
msedgedriver.exe [--port=9515]
Wenn Sie keine Portnummer angeben, wird der Service auf dem Port 9515 gestartet. Geben Sie dann beim Verbindungsaufbau in expecco als Remote-Server die Adresse
<Server-Adresse>:9515
an. Die Erweiterung "/wd/hub" ist hier nicht erforderlich.

==Verbindungsbausteine==
Der Verbindungsaufbau, welcher im GUI Browser interaktiv erfolgt, muss natürlich bei einem automatisierten Ablauf über einen Aktionsbaustein erfolgen.
Dazu gibt es in der SeleniumWebDriverLibrary im Ordner "''Connection''" verschiedene Bausteine, welche die Verbindungsparameter von verschiedenen Quellen erhalten:
* Connect Dieser Baustein erhält die Verbindungsparameter über Eingangspins
* Connect from File Hier werden die Einstellungen aus einer Datei (Anhang) gelesen (typischerweise im JSON Format)
* Connect from Spec Die Verbindungsparameter werden in einem Dictionaryobjekt geliefert
* Reuse or Start Connection Im Gegensatz zu obigen Bausteinen, welche immer eine neue Browserverbindung aufbauen (i.e. ein neues Browserfenster öffnen), wird dieser Baustein zunächst prüfen, ob bereits eine Verbindung besteht, und diese gegebenenfalls wiederverwenden. Dieser Baustein kann daher mehrfach (i.e. zu Beginn von Teilsequenzen) platziert werden, und damit die Teilsequenzen sowohl innerhalb eines komplexeren Gesamttests als auch "stand-alone", d.h. einzeln ausgeführt werden.

Alle "Connect" Bausteine benötigen die Angabe eines "''Verbindungsnamens''".
Dieser hat die Aufgabe, die Verbindung im weiteren Testverlauf zu identifizieren, wenn zwischen mehreren Verbindungen gewechselt wird, und zum Abbauen der Verbindung.

Wenn Sie im GUI Browser im Elementbaum auf eine Verbindung klicken, erscheint in der rechten "Test" Kachel ein Connect Baustein mit entsprechend vorgelegten Parametern. Diesen können Sie bei Bedarf gleich in die Rekordersequenz übertragen, oder (besser) als separate Aktion speichern (es ist sinnvoll, den Verbindungsaufbau von den aufgezeichneten Teilsequenzen zu trennen; damit haben Sie es später leichter, andere Browser zu verwenden, die Parameter der Verbindung zu ändern und auch neue Teilsequenzen aufzuzeichnen oder zu modifizieren.

Verbindungen mit komplexen Einstellungen werden typischerweise im Verbindungsdialog angelegt, und die Einstellungen von dort über die Menüfunktion "''Sichern in Anhang/Datei''" in einer Datei gesichert. So können Sie verschiedene Konfigurationen in einzelnen Dateianhängen in ihrer Testsuite oder auch außerhalb aufbewahren. Zum Verbinden verwenden Sie dann den Aktionsbaustein "[''Connect From File'']".

=Plugin-Einstellungen=
Wenn Sie eine bestimmte Browser-Installationen oder Driver standardmäßig als Voreinstellung verwenden möchten, können Sie diese in den Einstellungen des Plugins eintragen. Sie finden sie über das Menü unter dem Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" → "''Webtest (Selenium WebDriver)''". Einstellungen für spezifische Browser finden Sie unter den Unterpunkten "''Beliebteste Browser''" bzw. "''Andere Browser''".
Die dortigen Einstellungen gelten als Voreinstellung für jede Verbindung, es sei denn in einer konkreten Verbindungseinstellungen ist etwas anderes angegeben.

===Ausführungsverzögerung für Chrome===
In manchen Fällen kann es bei Verwendung des Chrome-Browsers vorkommen, dass Bausteine mit Element-Aktionen, beispielsweise ein Klick, im Test erfolgreich durchlaufen, die eigentliche Aktion aber gar nicht ausgeführt wurde. Dies ist ein bekannter Fehler [https://github.com/MPDL/imeji-gui-testing/issues/37], [https://github.com/SeleniumHQ/selenium/issues/4075], der von Selenium bzw. chromedriver behoben werden muss.

Der Fehler lässt sich verhindern, indem entweder der Klick über JavaScript aufgerufen wird (setzen Sie dazu im Klick-Baustein ''invokeDirectly'' auf ''true'' ) oder vor der Aktion kurz gewartet wird. Die Ausführung über JavaScript hat den Nachteil, dass sie weniger nah am Klick eines echten Benutzers ist; beispielsweise funktionieren Klicks auf Elemente auch dann, wenn sie von anderen Elementen verdeckt werden (was bei einem "normalen"Klick nicht geht).

Generell warten die Bausteine mit Element-Aktionen automatisch, bis das entsprechende Element verfügbar ist (existiert). In den hier beschriebenen Fällen reicht das aber nicht aus. Deshalb finden Sie in den Plugin-Einstellungen für Chrome die Einstellung "''Ausführungsverzögerung''". Bei der Ausführung wird dann zwischen den Aktionen entsprechend lange gewartet. Falls bei Ihnen der beschriebene Fehler eintritt, können Sie diesen Wert erhöhen. Ein größerer Wert hat natürlich Auswirkung auf die Gesamtlaufzeit.

=Recorder=

Die folgende Beschreibung des Recorders gilt prinzipiell für alle von expecco unterstützten GUI Technologien. Verhalten und Bedienung sind bis auf kleine technologiebedingte Unterschiede für alle gleich.

Besteht im GUI-Browser eine Verbindung mit einem Browserfenster, kann der integrierte Recorder verwendet werden, um einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Für jeden Klick im Fenster wird eine Aktion aufgezeichnet. Weitere Aktionen stehen über das Menü zur Verfügung. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

Allgemeine Aktionen finden Sie entweder direkt in der Menüleiste oder dort im Browser-Werkzeuge-Menü (s.u.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Element-Werkzeugs in der Menüleiste (s.u.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion. Auf diese Weise ist es ebenfalls möglich, die Eingaben ''Backspace'', ''Return'' und ''Tab'' aufzuzeichnen.

[[Datei:SeleniumWebDriverRecorder.png]]

'''Komponenten des Recorderfensters'''
#'''Aufnahme Pausieren''': Wenn die Kontrollleuchte rot ist, nimmt der Recorder auf. Durch Klicken können Sie die Aufnahme anhalten. Die Kontrolleuchte leuchtet dann grau. In diesem Zustand können Sie weiter Aktionen über das Recorder-Fenster ausführen, sie werden aber nicht aufgezeichnet. Klicken Sie erneut, um die Aufnahme weiterzuführen.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Browser. Dies wird nötig, wenn die Anzeige des Recorders nicht mit dem tatsächlichen Browserinhalt übereinstimmt.
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Element-Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Es stehen alle Aktionen zur Verfügung, die auf ein bestimmtes Element ausgeführt werden. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst und das Element aus der Position bestimmt. Die nicht ausgewählten Aktionen sind jederzeit über einen Rechtsklick erreichbar.
#'''Browser-Werkzeuge''': Aktionen die sich nicht auf bestimmte Elemente beziehen, wie Scrollen oder Aktionen auf die aktuelle URL oder den Titel, können hier ausgelöst werden.
#'''Seitennavigation''': Aktionen zur Seitennavigation: ''eine Seite zurück'', ''eine Seite vor'' und ''aktuelle Seite neu laden''
#'''Alert-Behandlung''': Wenn der Browser einen Alert anzeigt, klicken Sie auf diesen Button, um die Aktionen zur Alert-Behandlung auswählen zu können.
#'''Online Dokumentation''': Öffnet diese Online-Dokumentation.
#'''Anzeige''': Zeigt einen Screenshot des Browsers. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot. Scrollen wird den Browser weitergeleitet, aber nicht aufgenommen.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Skalierung''': Ändert die Skalierung des Screenshots. Diese kann auch über Scrollen in der Anzeige bei gedrückt gehaltener Strg-Taste angepasst werden.
#'''Meldungen''': Hier werden Meldungen angezeigt, bspw. wenn eine Aktion nicht aufgenommen werden konnte. Die letzte Meldung wird solange angezeigt, bis sie über den Button rechts daneben geschlossen wird. '''Fenster-Tabs''': Ab expecco 23.1 werden oberhalb der Anzeige Tabs für jedes offene Fenster angezeigt, sobald eine Verbindung mehr als ein Browserfenster besitzt. Ob der Browser dieses als Tab oder in einem eigenen Fenster anzeigt, ist dabei egal. Über die Tabs im Recorder können Sie das aktuelle Fenster wechseln und diesen Wechsel auch aufzeichnen. '''Frame-Kontext''': Ab expecco 23.1 sehen Sie unterhalb der Anzeige, in welchem Frame-Kontext Sie sich gerade befinden (siehe dazu den Abschnitt [[#Eingebettete_Inhalte|Eingebettete Inhalte]]). Sie können auf die Einträge klicken, um in einen höheren Kontext zu wechseln und diesen Wechsel aufzuzeichnen. Falls Sie zusammengesetzte Pfade eingestellt haben, wird die Anzeige aktualisiert, wenn Sie ein eingebettetes Element ausgewählt haben.

=Eingebettete Inhalte=
In HTML ist es möglich, auf einer Seite Inhalte einer anderen einzubinden. Das gängigste Elemente dafür ist ein Iframe (Inlineframe). Auf den Inhalt eines Iframes kann ebenfalls mit Selenium zugegriffen werden, allerdings muss dazu zuerst in diesen Kontext gewechselt werden. In der SeleniumWebDriverLibrary gibt es entsprechenden Bausteine, um in den Kontext eines Iframes zu wechseln, um in den Elternkontext zu wechseln und um zurück zum Standardinhalt, also dem obersten Kontext zu wechseln. Alle Element-Bausteine lösen die angelegten Pfade immer innerhalb des aktuellen Kontexts auf. Im GUI-Browser sehen Sie für eingebettete Inhalte ein zusätzliches Element, welches sie aufklappen können um dessen Elemente zu sehen.

==Zusammengesetzte Pfade==
Seit expecco 23.1 gibt es die Möglichkeit, auch zusammengesetzte Pfade an den Bausteinen zu verwenden, um direkt vom Standardinhalt auf den Inhalt eines Iframes zugreifen zu können. Dazu werden einfach der Pfad zum Iframe und der Pfad innerhalb des Iframe-Inhalts zu einem zusammengesetzt. Wichtig ist hierbei, dass beim Übergang keine Elemente ausgelassen werden dürfen, d.h. der vordere Teil muss mit dem Iframe-Element enden und der hintere Teil mit ''/body'' beginnen. Dazwischen dürfen die Pfade gekürzt werden und es ist natürlich auch möglich auf diese Art beliebig tief geschachtelte Elemente zu erreichen. An den Bausteinen können beide Techniken nach belieben verwendet werden, wichtig ist nur, dass die Pfade immer in dem Kontext aufgelöst werden, in dem sich Selenium gerade befindet.

Wenn Sie die kombinierten Pfade aufzeichnen, bzw. im GUI-Browser verwenden wollen, setzen Sie im Menü ''GUI Browser'' unter ''Aufzeichnung'' den Haken bei ''Zusammengesetzte Pfade aufzeichnen''. Damit wird für eingebettete Elemente ein zusammengesetzter Pfad relativ zum aktuellen Kontext erzeugt und angezeigt, anstatt wie bisher nur innerhalb seines eigenen Kontexts. Außerdem können Sie diese Elemente auch direkt im Recorder ansprechen oder über Follow-Mouse finden.

=Shadow-Elemente=
Shadow-DOMs sind eine Möglichkeit, um Teile einer Seite vom übrigen Dokument abzukapseln. Dabei werden an ein Element versteckte Shadow-Elemente angehängt. Eine ausführlichere Erklärung finden Sie zum Beispiel hier: [https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM Using shadow DOM - Web APIs | MDN].

In der SeleniumWebDirverLibrary gibt es den Baustein ''[Web] Get Shadow DOM'', der die obersten Elemente liefert, die dann wie andere WebElemente verwendet werden können.

Da die Elemente versteckt sind, werden sie vom GUI-Browser nicht direkt angezeigt. Ab expecco 23.1 kann man allerdings im Kontextmenü der Elemente im GUI-Browser einen Haken setzen, dass Shadow-Elemente gesucht werden sollen. Beim Aktualisieren der Kinder eines Elements werden sie dann angezeigt, falls vorhanden, allerdings nicht, wenn der gesamte Baum aktualisiert wird. Wenn der Haken gesetzt ist, sind die Elemente auch im Recorder verfügbar.

==Zusammengesetzte Pfade==
Ähnlich wie die Elemente innerhalb eines Frames kann auch auf die Shadow-Elemente direkt über zusammengesetzte Pfade zugegriffen werden. Diese Pfade können dann direkt an den Bausteinen verwendet werden, sodass der Baustein ''[Web] Get Shadow DOM'' nicht benötigt wird. Die Pfade haben die Form
<host path>/shadowRoot/<shadow path>
wobei ''<host path>'' den Pfad zum Element angibt, an das der Shadow-DOM angehängt wurde, und ''<shadow path>'' der Pfad innerhalb des Shadow-DOMs zum gewünschten Element ist. '/shadowRoot' dient als Marker, dass an dieser Stelle der Wechsel in den Shadow-DOM erfolgt.

=Authentifizierungs-Alerts=
Falls eine Webseite HTTP-Authentifizierung mit Basic Authentication verwendet, öffnet sich beim Laden der Seite ein Alert-Fenster zur Eingabe von Benutzernamen und Passwort. Dieses Fenster ist nicht direkt mit Selenium bedienbar. Im GUI-Browser wird es wie ein Alert angezeigt. Eine Ausnahme hierzu bildet Chrome, bei dem der Driver auf keine Anfrage antwortet solange der Dialog geöffnet ist. Das Plugin kann zu diesem Zeitpunkt insbesondere nicht feststellen, ob ein Authentifizierungs-Dialog geöffnet ist oder ob der Driver aus anderen Gründen nicht antwortet.

Bei lokalen Verbindungen unter Windows kann eine Authentifizierung mittels Windows Access ausgeführt werden. Es gibt in der SeleniumWebDriverLibrary für einzelne Browsertypen spezifische Authentifizierungs-Bausteine sowie den Baustein ''Authenticate at Alert'', der je nach Verbindung den entsprechenden Baustein ausführt. Für die verschiedenen Browser-Typen gibt es dabei unterschiedliche Einschränkungen:

:'''Chrome:''' Die Anmeldedaten werden an ein Chromefenster geschickt, daher funktioniert es nur, wenn nicht mehrere geöffnet sind. Der Einzelbaustein hat für diesen Fall die Option, den Titel des Fensters anzugeben.
:'''Edge''': Mit Microsoft Edge wird eine Anmeldung nicht unterstützt.
:'''Firefox''': Schickt die Anmeldedaten an ein Firefox-Dialogfenster und funktioniert daher nur, wenn es nicht mehrere gibt.
:'''Internet Explorer''': Mit dem Internet Explorer wird eine Anmeldung nicht unterstützt.

Als zusätzliche Option steht Ihnen auch eine Anmeldung über die URL zur Verfügung. Rufen Sie anstatt der Seite <nowiki>https://www.example.com</nowiki> die URL <nowiki>https://user:password@www.example.com</nowiki> auf. Wichtig ist hierbei, dass '':'' und ''@'' nicht im Benutzernamen oder im Passwort auftauchen. Möglicherweise wird diese Methode nicht von jedem Browser unterstützt.

Mithilfe des [[WindowsAutomation_Reference_2.0|WindowsAutomation2]]-Plugins ist es ebenfalls möglich, solch eine Anmeldung mit allen Browsertypen auszuführen.

=Portierung alter Selenium-Tests=
Dieses Plugin ersetzt das bisherige [[Selenium_Web_Test_Plugin|Selenium Web Test Plugin]]. Dieses basierte auf [https://www.seleniumhq.org/projects/remote-control/ Selenium RC], welches in Zukunft von den Browsern nicht mehr unterstützt wird. Der Nachfolger von Selenium RC ist [https://www.seleniumhq.org/projects/webdriver/ Selenium WebDriver], auch ''Selenium 2'' genannt. Ebenso ist auch das Aufzeichnen von Tests mit [https://www.seleniumhq.org/projects/ide/ Selenim IDE] veraltet, da das Plugin von neueren Browsern nicht mehr unterstützt wird. Das Selenium WebDriver Plugin verwendet stattdessen einen eigenen [[#Recorder|Recorder]].

Tests, die mit dem alten Selenium Web Test Plugin erstellt wurden und die alte SeleniumLibrary verwenden, können über Selenium WebDriver ausgeführt werden. Setzen Sie dazu in den Plugin-Einstellungen von "''Webtest Legacy (Selenium)''" den Haken bei "''WebDriver für die Ausführung verwenden''". Für die wichtigsten Funktionen wurde Wrapper bzw. umsetzende Funktionen erstellt, um die Migration möglichst problemlos zu gestalten.
Testen Sie dann, ob die Tests wie bisher ablaufen. Für den überwiegenden Teil der Bausteine sollte es dabei keine Probleme geben. Einige wenige Aktionen werden in der WebDriver Version nicht mehr unterstützt oder verhalten sich unterschiedlich. Es ist auch nicht garantiert, daß die Emulation der alten Schnittstelle auf Dauer von Selenium unterstützt werden. Wenn möglich sollten Sie daher über kurz oder lang die Testfälle umschreiben.

=FAQ=
*'''Scrollbalken lassen sich im Recorder nicht bedienen'''
:Der Scrollbalken des Browsers, der automatisch angezeigt wird, wenn eine Seite größer als das Browserfenster ist, ist kein bedienbares Webelement. Scrollen um einen bestimmten Betrag ist in einem Test selten sinnvoll, wenn die Größe des Browserfensters nicht festgelegt ist. Verwenden Sie stattdessen den Baustein <code>[Web] Scroll Element into View</code>, um ein entsprechendes Element in den sichtbaren Bereich zu scrollen. Der Klick-Baustein, den der Recorder standardmäßig verwendet, führt diese Aktion bereits automatisch mit aus (<code>[WebElement] Click (Scroll Element into View)</code>). Wenn Sie im Recorder-Fenster scrollen, wird dies automatisch auf den Browser übertragen, aber nicht aufgezeichnet. Falls Sie tatsächlich um einen bestimmten Betrag scrollen möchten, gibt es bei den Browser-Aktionen einen Eintrag dafür und weitere Bausteine in der SeleniumWebDriverLibrary.

*'''Baustein schlägt fehl, wenn Element zu spät sichtbar wird'''
:Alle Bausteine, die einen Elementpfad verwenden, haben automatisch eingebaut, dass sie warten, bis ein entsprechendens Element auftaucht. Es gibt aber Fälle, in denen ein Element zwar bereits da, aber noch nicht sichtbar ist. Bei einem Klick auf das Element bekommen Sie dann einen Fehler. Mögliche Fehler in diesem Zusammenhang sind <code>org.openqa.selenium.ElementNotInteractableException: element not interactable</code> und <code>org.openqa.selenium.JavascriptException: javascript error: Cannot read property 'left' of undefined</code>. Verwenden Sie dann vor einer Interaktion mit dem Element den Baustein <code>[Web] Wait for Visibility of Element</code> oder <code>[Web] Wait for Element to Be Clickable</code>.

*'''Fehlermeldung: <code>Cannot read property 'left' of undefined</code>'''
:Der Fehler <code>org.openqa.selenium.JavascriptException: javascript error: Cannot read property 'left' of undefined</code> kann mit dem Chrome-Browser auftreten. In diesem Fall ist das verwendete Element nicht sichtbar. Lesen Sie dazu den Punkt oben. Der Fehler ist auch im Zusammenhang mit Elementen in einer Dropdown-Liste bekannt, d.h. bei einem Klick oder dem Bewegen der Maus auf ein <nowiki><option></nowiki>-Element innerhalb eines <nowiki><select></nowiki>-Elements. Diese Elemente sind prinzipiell nicht klickbar. Verwenden Sie stattdessen einen passenden <code>[Web] Select</code>-Baustein mit dem <nowiki><select></nowiki>-Element.

*'''Fehlermeldung: <code>Stale Element Reference Exception</code>'''
:Der Fehler <code>org.openqa.selenium.StaleElementReferenceException</code> tritt immer dann auf, wenn ein WebElement verwendet wird, das nicht mehr da ist. Wenn das in Ihrem Test passiert und das Element eigentlich da sein sollte, verwenden Sie an der Stelle stattdessen den Locator, um das Element neu zu holen. Eventuell liegt es auch daran, dass sich der Test momentan in einem anderen Frame-Kontext befindet als das Element. Wenn Sie [[#Zusammengesetzte_Pfade|zusammengesetzte Pfade]] verwenden, sollte das Element selbst in den richtigen Kontext wechseln, bevor Aktionen darauf ausgeführt werden.
:In seltenen Fällen kann der Fehler auch in expecco selbst auftreten, wenn an irgendeiner Stelle im GUI-Browser oder Recorder ein entsprechendes WebElement verwendet wird. Sie sollten dann abbrechen können und es nochmal versuchen. Sollte der Fehler bestehen bleiben, wechseln Sie in den Default Content und laden Sie den Baum im GUI-Browser neu.

*'''Baustein läuft erfolgreich, aber ohne Auswirkungen'''
:Dieser Fall kann mit Chrome auftreten. Das Element ist verfügbar, die Aktion wirft keinen Fehler, aber es wird nichts ausgeführt. In der Regel hilft es, vor der Ausführung kurz zu warten, siehe [[#Ausf.C3.BChrungsverz.C3.B6gerung_f.C3.BCr_Chrome | Ausführungsverzögerung für Chrome]].

*'''Ausführungen mit Chrome sind langsamer'''
:Um ein Problem bei der Ausführung mit Chrome zu beheben, ist in den Plugin-Einstellungen für Chrome eine Verzögerung definiert. Überprüfen Sie, ob dieser Wert eventuell zu hoch eingestellt ist; siehe [[#Ausf.C3.BChrungsverz.C3.B6gerung_f.C3.BCr_Chrome | Ausführungsverzögerung für Chrome]].

*'''Fehlermeldungen wie: "org.openqa.selenium.InvalidArgumentException: Expected "handle" to be a string..."'''
:Dies passiert wenn der Driver nicht (mehr) zum Browser passt. Lesen Sie dazu obiges Kapitel "[[#WebDriver aktualisieren|WebDriver aktualisieren]]".

*'''Key Chords mit Shortcuts funktionieren nicht'''
:Das Drücken mehrerer Tasten gleichzeitig lässt sich als Key Chord simulieren. Dadurch können auch Shortcuts eingegeben werden. Allerdings funktionieren hier nicht alle Eingaben, da diese nur an den Seiteninhalt und nicht an den Browser selbst gehen. Kombinationen wie ''Strg + t'' um einen neuen Browsertab zu öffnen, funktionieren daher vermutlich nicht, ''Strg + a'' oder ''Strg + c'' sollten hingegen möglich sein.

*'''Zusätzliche Window Handles mit Opera'''
:Der Opera-Browser liefert mehr Window Handles als Tabs bzw. Fenster geöffnet sind. Diese kommen von Opera-internen Funktionen wie dem Schnellstart (''Speed Dial'') oder der ''Better Address Bar Experience'' (BABE), die zwar im Browserfenster eingebunden, aber nicht als Tab angezeigt werden. Zu diesen Tabs kann zwar mit den entsprechenden Bausteinen gewechselt werden, es sind dann aber nicht alle Aktionen möglich, die für die normalen Tabs zur Verfügung stehen. Sie können zum Beispiel nicht geschlossen werden und man bekommt von ihnen kein Bild. Am besten wechselt man daher gar nicht erst in diese Kontexte. Seien Sie also vorsichtig, wenn Sie anhand des Index zu einem Tab wechseln wollen, da sich die Opera-Tabs zwischen den anderen befinden und der Index ein anderer als für die anderen Browser sein kann.

*'''Chrome: Wähle deine Suchmaschine'''
:Neuere Chromeversionen zeigen nach dem Starten ein [https://www.google.com/chrome/choicescreen/ Overlay], bei dem man die verwendete Suchmaschine auswählen soll. Die Entscheidung wird normalerweise im Benutzerprofil gespeichert. Wenn für die Verbindung aber nicht explizit ein Chrome-Profil angegeben wird, hat man bei jedem Verbindungsaufbau ein leeres Profil und es wird immer nachgefragt.

:In vielen Fällen kann der Test auch trotz des Overlays im Hintergrund ablaufen. Das Overlay gilt aber wie ein Tab bzw. Fenster; so liefert beispielsweise vom Baustein ''[Web] Get Window Handles'' einen Handle dafür und es kann auch dorthin gewechselt werden. Es gibt aber auch Möglichkeiten es loszuwerden:
:* ''--disable-search-engine-choice-screen'': In den [[#Erweiterte_Einstellungen|erweiterten Einstellungen]] kann man bei den Optionen <code>--disable-search-engine-choice-screen</code> angeben, dann kommt das Overlay nicht.
:* ''Auswählen'': Sie können Ihren Test auch so erweitern, dass zu Beginn eine Suchmaschine ausgewählt und damit das Overlay geschlossen wird. Dabei müssen Sie zwei Dinge beachten. Zum einen müssen Sie zuerst mit einem ''Switch to Window''-Baustein dorthin wechseln (z.B. mit Index ''2'' oder leerem Titel) und am Ende auch wieder zurück zu Ihrem ursprünglichen Tab. Zum anderen sind interessanten Elemente des Overlays [[#Shadow-Elemente|Shadow-Elemente]] und werden daher im GUI-Browser nicht direkt angezeigt.

*'''Firefox: <code>Process unexpectedly closed with status 0</code>'''
:Fehlerbild: Die Verbindung zum Firefox-Browser kommt nicht zustande mit der Fehlermeldung <code>org.openqa.selenium.WebDriverException: Process unexpectedly closed with status 0</code>. Der Browser öffnet sich dann aber doch ohne dass es eine Verbindung in expecco gibt.
:Eine bekannte Ursache dafür ist, dass der Browser dabei zum ersten Mal nach einem Update gestartet wird, womit der Browser im automatisierten Zustand nicht zurecht kommt. Beim zweiten Versuch sollte der Fehler dann nicht mehr auftreten. Um den Fehler zu verhindern, achten Sie darauf, den Browser nach einem Update immer zuerst normal zu starten.

Selenium WebDriver Plugin

2024-08-05T13:34:15Z

Matilk: /* FAQ */ Chrome: Wähle deine Suchmaschine

Selenium WebDriver Plugin/en

2024-08-05T13:33:24Z

Matilk: /* FAQ */ Chrome: Choose your search engine

[[Selenium_WebDriver_Plugin|Deutsche Version]] | '''English Version'''

=Introduction=
Use the ''Selenium WebDriver Plugin'' to test or automate interactions of applications running in a web-browser (*). The plugin can be (and usually is) used with the [[Expecco_GUI_Tests_Extension_Reference|GUI Browser]], which helps in the creation of tests. Moreover, the GUI Browser can record UI sessions, which can later be customised or refactored as required.

The ''Selenium WebDriver Plugin'' replaces the previous [[Selenium_Web_Test_Plugin|Selenium Web Test Plugin]], which was based on the now outdated Selenium RC framework. 
The new web driver uses the [https://www.seleniumhq.org/projects/webdriver/ Selenium WebDriver] for automation, and replaces the previous interface.
(see https://www.guru99.com/introduction-webdriver-comparison-selenium-rc.html for background information and a description of the differences.)
Read [[#Transferring_Old_Selenium_Tests|this section]] for information how to transfer testsuites using the old plugin.

(*) actually, there exists WebDriver interfaces to control Windows or OS X desktop applications. Thus, this plugin can be used in a number of additional scenarios.

=Settings=
This plugin uses the Java bridge and therefore needs a Java installation. You can specify it in the settings under ''Plugins'' -> ''Java Bridge''. The important field is ''Java Installation Path'', where you can set a JDK or JRE. If nothing is set, expecco tries to find java in the PATH.

[[Datei:JDKPfadEinstellungen.png|600px]]

There are settings for the Selenium WebDriver Plugin itself as well. You find them under ''Plugins'' -> ''Webtest (Selenium WebDriver)''. There you can for example set the address of a remote running Selenium server or another Jar file for Selenium. The settings for the different browser types are divided into the two subpages ''Most Popular Browsers'' and ''Other Browsers''. There you can set the path to the browser executable or to the webdriver to use. You can leave all these fields empty and expecco will search for them automatically

=Browser Support=
This plugin supports (among others) the Chrome/Chromium, Edge, Firefox, Internet Explorer and Opera browsers.
 Safari under OSX must be at least version 10, and OSX must be at least El Capitan.
The plugin uses the WebDriver interface for communication; therefore, browsers running both on the local or on a remote machine can be tested and/or controlled.
In addition, many other browsers, UIs and devices support the WebDriver protocol, and can thus be automated/tested with expecco.

==Update WebDriver==
Each browser has a driver ("''WebDriver''") for opening and controlling a browser window.
Usually, the driver is a separate program which translates WebDriver requests into browser-specific interface calls. However, there are also browsers and programs which have the WebDriver protocol already built in (eg. Safari).

The expecco installation package includes current driver versions for common browsers. However, as the browsers are updated continuously, sometimes even automatically, you sooner or later may have to download a new driver version. In that case put it in the folder inside your expecco installation directory where the other versions are stored as well, at:
<code>packages/exept/expecco/plugin/seleniumWebDriver/lib/XXX</code>
(of course, with "\”s instead of "/"s on Microsoft Windows operating systems), where "XXX" denotes the operating system (Windows, Linux, OSX etc.).


In the connection dialog, expecco may show a warning, that the driver version is incompatible with the browser version. In some cases this may only be due to the fact, that this version was not known at the time of delivery. Some combinations may work despite the warning, but we cannot guarantee that for each individual case.

Therefore you can always check the "''Do not show this warning again''" toggle, if such a warning is shown, to have expecco remember that combination as "compatible" in your settings, and not warn again. You should only do that, if you are sure that your tests will still be executed correctly. As we sometimes get compatibility problems ourselves and cannot always immediately find the reason, we advice you, to update the driver.

For Chrome and Microsoft Edge, where each new browser version comes with a new driver version, you find a button in the connection dialog, to download matching driver versions by expecco.

You find new driver versions at the following addresses:
{|
|Chrome/Chromium
|[https://sites.google.com/chromium.org/driver/ ChromeDriver]
|-
|Edge
|[https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft WebDriver]
|-
|Firefox
|[https://github.com/mozilla/geckodriver/releases GeckoDriver]
|-
|Internet Explorer
|[https://selenium-release.storage.googleapis.com/index.html IEDriverServer]
|-
|Opera
|[https://github.com/operasoftware/operachromiumdriver/releases Opera driver]
|-
|Safari
|[https://webkit.org/blog/6900/webdriver-support-in-safari-10 Safari Support]
|}

Download a suitable version and place it at an appropriate location in the above mentioned directory. expecco will then find and use it.  Alternatively, you can set the path to a driver either in the [[#Advanced_Settings | connection editor]] or in the [[#Plugin_Settings | plugin settings]].

[[Datei:bulb.png|20px]]Please verify that the driver's version is compatible with the browser version. If in doubt, consult the version history (e.g. for Chrome: https://chromedriver.storage.googleapis.com/2.25/notes.txt).

[[Datei:bulb.png|20px]]Notice: For Internet Explorer, "<code>Protected Mode</code>" settings must be set to the same value for all zones, to be able to start a connection. (in the Internet Explorer, open "Settings" - "Internet Options" - "Security", and set the value of "protected mode" to the same in all 4 zones; otherwise, you'll get error- and warning dialogs when connecting). See also the [https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver#required-configuration required configuration] to use InternetExplorerDriver.

[[Datei:bulb.png|20px]]Also notice: the plugin uses JavaScript for some advanced functions, and those functions require that JavaScript is enabled in the browser. This is especially needed to use the GUI browser and the recorder. Test execution may be possible without JavaScript, as long as no actions are used which rely on JavaScript.
If you get an error like <code>"org.openqa.selenium.JavascriptException: Error executing JavaScript"</code>,
make sure that JavaScript is enabled in the browser and that the versions of the browser and the associated driver are compatible.

=Additional Uses=
{|
|[https://github.com/appium/appium-for-mac AppiumForMac]
|WebDriver to control OS X apps (i.e. also non-Browsers)
|-
|[https://github.com/microsoft/WinAppDriver WinAppDriver]
|WebDriver to control Windows Desktops
|}

Notice, that these interfaces usually provide a subset of the functionality provided by special plugins, such as Java-GUI or WindowsAutomation plugins. Usually, they are ok to manipulate the top level window or to confirm simple dialogs, but less usable for more complex UI tests.

= Quick Start =
== Open Browser / Connecting ==
* Start expecco
* Click on "''New Testsuite''"
* Click on the GUI-Browser symbol ([[Datei:GUIBrowser.png|24px]])
* A new Tab appears, containing the GUI-Browser
* Click on "''Connect''" and choose "''Selenium Testing''". The [[#Connection Editor | Connection Dialog]] appears (see details below)
* Choose the type of browser (eg. "<code>firefox</code>" and enter the URL of the tested web site (eg. "<code><nowiki>http://www.myHost.com</nowiki></code>") and )
* Click on "Connect"
* A browser is started automatically, and the page is shown
* As soon as the connection is established, the page's elements are shown in the GUIBrowser's left tree view

== Start a Recording ==
* After a connection has been established, click on the record icon ([[Datei:Recording.png|16px]]) in the GUIBrowser.

== Inspecting Elements ==
* Select an element in the browser's element-tree, or move the mouse over it in "follow-mouse mode". If your browser does not support this "follow-mouse" mode, try opening a recorder, and move the mouse there.
The element's attributes are shown in the lower-center attribute/property list.
== Manually adding Actions and Checks ==
* In addition to recording, actions and checks can also be selected from the upper-centre action list. Select one there and either try it immediately or add it to the recording sequence via the add-action button at the top far right.

=Connecting=
==Connection Editor==
The connection editor defines, changes or starts a connection. Open the GUI browser, click on "''Connect''" and select "''Selenium Testing (WebDriver)''". You can also create attachments or files containing connection parameters ("''connection settings''") without actually connecting to/opening a new browser connection via the "''Save Connection Settings''" menu item.

When opened, the connection editor presents a number of fields and load/save buttons in its toolbar menu:

[[Datei:SeleniumWebDriverConnectDialog.png]]

#''Load settings from attachment'': Open an attachment containing connection settings from an open project. This settings will be added to the editor. Already entered inputs that are not conflicting will remain unchanged.
#''Load settings from file'': Open a saved settings file (*.csf). Its settings will be added to the editor. Already entered inputs that are not conflicting will remain unchanged.
#''Save settings as attachment'': Save all entered settings as attachment in an open project.
#''Save settings as JSON attachment'': Save all entered settings in JSON format as attachment in an open project.
#''Save settings to file'': Save all entered settings to a file (*.csf).
#''Version info'': Opens a window showing the used versions of the Selenium server, the selected browser and its driver.
#''Online documentation'': Open this online documentation page.
#''Connection name'': Enter the name of the connection used to show it in the GUI browser. (Optional)
#''Browser type'': Choose the type of browser to use. Ensure it is installed and the version of the used driver is compatible with the browser version.
#''URL'': Enter the URL to open at startup. To open an empty browser window, leave this field empty. To open a local file use the "<code>file://</code>" scheme, e.g. "<code>file:///C:/Users/admin/Desktop/index.html</code>".
#''Advanced view'': Toggle the view to enter [[#Advanced Settings|advanced settings]].
#''Information on the selected browser'': Here, the selected browser type is shortly characterized.
#''Information on the settings'': It shows which Selenium, browser and driver version will be used regarding the current settings. If you have set [[#Advanced Settings|advanced settings]], they will also be displayed here.

===Advanced Settings===
Besides the used browser and the start URL, more settings and possibly "''capabilities''" may be required. To see click on the "Advanced" toggle. Depending on the selected browser type you get different entry fields.

*''Remote Server'': To open a browser on a remote host, start a Selenium server there and set this field to its address. You can also enter a local address if you do not want the Selenium server to start automatically or if it is already running. See the next section [[#Remote Connections|Remote Connections]] on how to start a Selenium server.

*''Headless'': to open the browser in "headless" mode, i.e. without a window. Not all browsers/drivers support this mode.

*''Binary'': Enter the path to the binary of the selected browser. Use this if the browser cannot be found automatically by Selenium, or if you have another browser version installed or to be tested against.

*''Driver'': For each browser, a particular driver is needed for automation. New browser versions often also need a new driver version. If you don't want or cannot use the driver provided by expecco, set its path here.

*''Command Line Options'': arguments passed to the browser-command. For example the chrome browser supports a "--disable-extensions" command line argument, firefox supports "--safe-mode" and "--profile". These options are browser- and possibly browser-version specific. Most browsers allow for a "--help" argument, which you may try in a shell window to find out.

*''Firefox Profile'': For Firefox, it is possible to set a ''Firefox Profile'', containing specific settings. If no profile is set, each connection will use a new empty one.

*''Capabilities'': Selenium connections can use several capabilities to define the connection's behavior. To add specific capabilities, set them in this field. Write "''<capability name>: <value>''" or "''<capability name> = <value>''", one entry per line.The set of capabilities needed or supported are browser- and driver specific. Please refer to the concrete driver's documentation as found via the driver links above. Common capabilities are: "app" or "application", "url", etc. For drivers which communicate with mobile devices, the capabilities also select which device to use and/or wether an emulator should be started.You can also set properties for the Firefox browser - for this, use the same syntax as for capabilities, but add a leading ''$'' to the property name.Properties used by expecco internally (such as browser type, url or remote host) are prefixed by a "#"-character.

==Remote Connections==
To start a browser on a remote computer, copy the Selenium server and the required driver to that computer. You find the files in your expecco installation at "<code>packages\exept\expecco\plugin\seleniumWebDriver\lib</code>". Start the Selenium server (on the remote host) with:
java -jar selenium-server-standalone-3.6.0.jar
By default, the server will listen on port 4444. To use another port, set it with the "<code>-port <nr></code>" command line argument. To connect to that server, set the "''remote server''" parameter of the connection to "''<Server-Address>:4444/wd/hub''".

Check and possibly configure your firewall to allow transmission through the port.

== Headless Browsing ==
"''Headless Browsing''" means: "''without a window''", and is useful to test web-pages for reachability, performance and structure. You can either use the HTMLUnit browser type, which simulates a browser, or run against one of the real browsers in headless mode. Notice, that not all browsers support this headless mode - we recommend using "firefox" or "chrome" for this.

Also notice, that in order to verify that a web page's interaction with a browser works correctly, you should test against real browsers.
For an introduction on what "headless browsing" means, see for example [https://www.guru99.com/selenium-with-htmlunit-driver-phantomjs.html https://www.guru99.com/selenium-with-htmlunit-driver-phantomjs.html].

Notice: the HTMLUnit driver has been removed from the latest selenium distribution and is also no longer supplied with expecco (it was not a good test tool anyway, as it behaved differently from real browsers).
 If required, download from [https://github.com/SeleniumHQ/htmlunit-driver https://github.com/SeleniumHQ/htmlunit-driver].

==Connection Blocks==
SeleniumWebDriverLibrary offers a number of blocks to start a Selenium connection within a testrun. The ''connection name'' identifies the connection during the run, if the test uses multiple connections and switches between them (eg. if multiple browser windows are open simultaneously). To start a connection with predefined settings, save them in the connection dialog (as attachment), and use the "[''Connect From File'']" action block.

=Plugin Settings=
To use certain browser installations or drivers as default, for every connection, set them in the settings dialog of the plugin ("''Extras''" → "''Settings''" → "''Plugins''" → "''Selenium WebDriver Extension''"). Settings for specific browsers can be found under "''Most Popular Browsers''" or "''Other Browsers''". The settings there are used as default, unless overwritten by an individual connection configuration.

===Execution Delay for Chrome===
In some cases it can happen when using the Chrome browser that blocks with element actions, for example a click, run successfully in the test, but the actual action was not executed at all. This is a known bug [https://github.com/MPDL/imeji-gui-testing/issues/37], [https://github.com/SeleniumHQ/selenium/issues/4075] that needs to be fixed by Selenium or Chromedriver. The error can be prevented by either calling the click via JavaScript – to do this, set ''invokeDirectly'' to ''true'' at the click block – or wait briefly before the action. Execution via JavaScript has the disadvantage that it is less close to the click of a real user and, for example, clicks on elements work even if they are hidden by other elements. In general, blocks with element actions automatically wait until the corresponding element is available. In the cases described here, however, this is not sufficient. Therefore you will find the setting ''execution delay'' in the plugin settings for Chrome. During execution, the system waits accordingly long between each action. If you experience the described error, you can increase its value. Of course, a higher value has an effect on the test run executio times.

=Recorder=
The following description applies to all GUI technologies which support remote recording in the integrated expecco recorder: the behaviour of the recorder is (apart from small differences due to technology-specific limitations) the same across different connections.

Use of this recorder has some advantages over direct recording in the browser:
* it can be used with remote machines/connections/mobil devices especially for mobile devices, which may be all located in a separate (server-) room
* it provides precise control over which event is to be recorded. For example, for clicks, there are alternative ways to record: as "press-release", as "click", as "move-then-click", as "move-then-press-delay-release". Depending on the page's underlying event handling (typically done in JavaScript), either one may be required.

Once connected to a browser, the integrated recorder can be used to record a test case. Start the recorder by selecting the appropriate connection in the GUI browser's left tree and click the ''record'' button. The recorder opens a new window. Each click in the window records an action. More actions are available in the menu. Recorded actions are added to the ''workspace'' of the GUI browser to form a sequence of interactions. This sequence can be edited, parametrized or replayed immediately. When finished, it should be saved into the suite as a new "Test Action".

General actions can be found either directly in the menu bar or there in the Browser Tools menu (see below). To record actions on elements, either change the selection of the element tool in the menu bar (see below) and click on the element or select the corresponding action from the context menu by right-clicking on the element. For text input, you can also place the cursor over the element and enter the text. The input dialog for this action opens. It is also possible to record the imputs ''backspace'', ''return'' and ''tab'' that way.

[[Datei:SeleniumWebDriverRecorder.png]]

'''Components of the recorder window'''
#'''Pause recording''': If the control lamp is red, the recorder is in "''recording''"-mode. Pause the recording by clicking on this lamp. The lamp will turn to grey. In this state you can execute actions with the recorder, but they are not recorded. Click again to resume the recording.
#'''Update''': Update the screenshot on the element tree. Necessary if the recorder view does not fit the browser content.
#'''Follow-Mouse''': The element under the cursor is selected in the GUI browser.
#'''Element Highlighting''': The element under the cursor gets a red frame.
#'''Element Tools''': Select which tool to use for recording. You can choose between all actions that use a certain element. The selected action is triggered by each click in the view and the element is determined by the click position. Not selected actions are available by right click.
#'''Browser Tools''': Actions not refering to ocertain elements, like scrolling or actions on the current URL or the title, can be triggered here.
#'''Page navigation''': Actions for page navigation: ''Back'', ''Forward'' and ''Refresh Page''
#'''Alert Handling''': Click this button if the browser shows an alert, to be able to select the actions for alert handling.
#'''Online Documentation''': Open this online documentation.
#'''View''': Shows a screenshot of the browsers. Actions can be triggered by mouse depending on the selected tool. If a new action can be entered, the frame of the window is green, red otherwise. Scrolling is forwarded to the browser, but not recorded.
#'''Resize Window to Screen Size''': Change the size of the window to show the whole screenshot.
#'''Set Screen Scale to Fit Window''': Scale the screenshot to fully fit in the window
#'''Scale''': Changes the scale of the screenshot. Can also be adjusted by scrolling with pressed <kbd>CTRL</kbd> key.
#'''Notifications''': Shows notifications, e.g. if an action cannot be recorded. The last notification is displayed until it is closed by the button on its right side. '''Window Tabs''': As of expecco 23.1, tabs are displayed above the display for each open window as soon as a connection has more than one browser window. Whether the browser displays this as a tab or in its own window does not matter. You can use the tabs in the recorder to switch the current window and also record this switch. '''Frame context''': As of expecco 23.1, you can see below the display in which frame context you are currently in (see the section [[#Embedded_Content|Embedded Content]]). You can click on the entries to switch to a higher context and record this switch. If you have compound paths enabled, the display will update when you select an embedded item.

=Embedded Content=
In HTML it is possible to include content from another page within one page. The most common element to do this is an iframe (inline frame). The content of an iframe can also be accessed with Selenium, but first you have to switch to this context. In the SeleniumWebDriverLibrary there are corresponding blocks to switch to the context of an iframe, to switch to the parent context and to switch back to the default content, i.e. the top context. All element blocks always resolve the applied paths within the current context. In the GUI browser, you will see an additional element for embedded content, which you can expand to see its elements.

==Compound Paths==
Since expecco 23.1 there is the possibility to also use compound paths at the blocks to access the content of an iframe directly from the standard content. For this purpose, simply the path to the iframe and the path within the iframe content are combined into one. It is important here that no elements may be omitted at the transition, i.e. the front part must end with the iframe element and the back part must begin with ''/body''. In between the paths may be shortened and it is of course also possible to access elements nested to any depth in this way. Both techniques can be used on the blocks as desired, the only important thing is that the paths are always resolved in the context in which Selenium is currently located.

If you want to record the combined paths or use them in the GUI Browser, check the box ''Record Compound Paths'' in the ''GUI Browser'' menu under ''Recording''. This will create and display a compound path for embedded elements relative to the current context, instead of only within its own context as before. You can also address these elements directly in the recorder or find them via Follow-Mouse.

=Shadow Elements=
Shadow DOMs allow you to encapsulate parts of a page from the remaining document. They provide a way to attach hidden shadow elements to an element. You can find a more detailed explanation for example here: [https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM Using shadow DOM - Web APIs | MDN].

The SeleniumWebDirverLibrary has the block ''[Web] Get Shadow DOM'', which gives you the topmost elements, which then can be used like other WebElements.

As the elements are hidden, they are not directly displayed in the GUI browser. However, since expecco 23.1 you can check in the context menu of the elements in the GUI browser the option to find shadow elements. They then will be displayed when updating the children of an element, if there are any, but not when updating the whole tree. If the option is checked, the elements are also available in the recorder.

==Compound Paths==
Similar to elements inside a frame, shadow elements can be accessed by compound paths. These paths can be used directly at the library blocks and the block ''[Web] Get Shadow DOM'' is not required. The paths are of the form
<host path>/shadowRoot/<shadow path>
where ''<host path>'' denotes the path to the element that has the shadow DOM attached, and ''<shadow path>'' denotes the path inside the shadow DOM to the desired element. '/shadowRoot' serves as marker where the switch to the shadow DOM is needed.

=Authentication Alerts=
If a Web page uses HTTP authentication with Basic Authentication, an alert window for entering the user name and password opens when the page is loaded. This window cannot be accessed directly with Selenium. In the GUI browser, it is displayed as an alert. An exception to this is Chrome, where the driver does not respond to any request as long as the dialog is open. At this point, the plugin cannot even determine whether an authentication dialog is open or whether the driver is not responding for other reasons.

For local connections under Windows, authentication can be performed using Windows Access. In the SeleniumWebDriverLibrary there are specific authentication blocks for individual browser types as well as the block ''Authenticate at Alert'', which executes the corresponding block depending on the connection. There are different restrictions for the different browser types:

:'''Chrome:''' The credentials are sent to a chrome window, so it only works if not more than one are open. In this case, the single block has the option to specify the title of the window.
:'''Edge''': With Microsoft Edge a login is not supported.
:'''Firefox''': Sends the credentials to a Firefox dialog box and therefore only works if there are not multiple ones.
:'''Internet Explorer''': With Internet Explorer a login is not supported.

As an additional option, you can also log in using the URL. Instead of the page <nowiki>https://www.example.com</nowiki> call the URL <nowiki>https://user:password@www.example.com</nowiki>. It is important that '':'' and ''@'' do not appear in the user name or password. This method may not be supported by every browser.

With the [[WindowsAutomation_Reference_2.0/en|WindowsAutomation2]]-Plugin it is also possible to execute such a login with all browser types.

=Transferring Old Selenium Tests=
This Plugin replaces the previous [[Selenium_Web_Test_Plugin|Selenium Web Test Plugin]], which is based on [https://www.seleniumhq.org/projects/remote-control/ Selenium RC]. Selenium RC is no longer supported by their authors and it will also no longer be maintained by exept. The successor is [https://www.seleniumhq.org/projects/webdriver/ Selenium WebDriver], also referred to as Selenium 2.

Recording of test actions using [https://www.seleniumhq.org/projects/ide/ Selenim IDE] is also outdated, as the plugin is not supported by newer browsers. The ''Selenium WebDriver Plugin'' uses its own [[#Recorder|Recorder]] instead.

Tests which were created with the old ''Selenium WebTest Plugin'' using SeleniumLibrary can be executed with the new Selenium WebDriver.
For this, go to the plugin settings of "''Webtest Legacy (Selenium)''" and check "''Use WebDriver for execution''". Please verify that your tests are still running after this change, as there is no 100% backward compatibility (which is outside the scope of expecco). However, most of the old test actions should run without problems.

=FAQ=
*'''Scrollbars cannot be handled in the recorder'''
:The scrollbar of the browser which is diplayed if a page is larger than the browser window is no controllable web element. Mostly it is useless to scroll by a certain amount in a test where the size of the browser window is not defined. Instead, use the block <code>[Web] Scroll Element into View</code> to scroll a relevant element to the visible region. The default click block used by the recorder already includes this action (<code>[WebElement] Click (Scroll Element into View)</code>). If you scroll on the recorder window, the action will also be applied to the browser, but is not recorded. If you actually want to scroll by a certain amount, there is an appropriate entry in the browser actions, and more blocks in the SeleniumWebDriverLibrary.

*'''Block fails if element becomes visible too late'''
:All blocks that use an element path have built in that they wait until a corresponding element appears. However, there are cases where an element is already there, but not yet visible. If you click on the element you will get an error. Possible errors in this context are <code>org.openqa.selenium.ElementNotInteractableException: element not interactable</code> and <code>org.openqa.selenium.JavascriptException: javascript error: Cannot read property 'left' of undefined</code>. In this case, use the <code>[Web] Wait for Visibility of Element</code> block or <code>[Web] Wait for Element to Be Clickable</code> before interacting with the element.

*'''Error message <code>Cannot read property 'left' of undefined</code>'''
:The error <code>org.openqa.selenium.JavascriptException: javascript error: Cannot read property 'left' of undefined</code> can occur with the Chrome browser. This means that the used element is not visible. See the point above on that. The error is also known in combination with elements in a dropdown list, i.e. when clicking or moving the mouse over a <nowiki><option></nowiki> element within a <nowiki><select></nowiki> element. Such elements are generally not clickable. Instead, use a suitable <code>[Web] Select</code> block with the <nowiki><select></nowiki> element.

*'''Error message: <code>Stale Element Reference Exception</code>'''
:The error <code>org.openqa.selenium.StaleElementReferenceException</code> occurs whenever a WebElement is used that is no longer there. If that happens during your test and the element should have been there, try using the locator instead to fetch the element again. Maybe the error occurs because the test is currently in a different frame context as the element. If you are using [[#Compound_Paths|compound paths]], the element should switch by itself to the correct context when it is used.
:In rare cases this error can also occur in expecco itself, if at somewhere in the GUI browser or the recorder such a WebElement is used. You should then be able to abort and try again. Should the error persist, switch to the default content and refresh the tree in the GUI browser.

*'''Block runs successfully, but without effect'''
:This case can occur with Chrome. The element is available, the action does not throw an error, but nothing is executed. Usually it helps to wait briefly before the execution, see [[#Execution_Delay_for_Chrome | Execution Delay for Chrome]].

*'''Executions using Chrome are slower'''
:To fix a problem when executing with Chrome, a delay is defined in the plugin settings for Chrome. Check if this value is possibly too high; see [[#Execution_Delay_for_Chrome | Execution Delay for Chrome]].

*'''Errors like: "org.openqa.selenium.InvalidArgumentException: Expected "handle" to be a string..."'''
:This occurs if the driver does not match the browser (any more). Please read the above chapter "[[#Update WebDriver|Update WebDriver]]".

*'''Key Chords with Shortcuts are not working'''
:Pressing keys simultaneously can be simulated using Key Chords. They can also be used to send shortcuts. However, not all inputs will work, as they are only sent to the page content, not to the browser itself. Combinations like ''Ctrl + t'' to open a new browser tab probably wont't work, ''Ctrl + a'' and ''Ctrl c'' on the other hand should be effective.

*'''Additional Window Handles for Opera'''
:The Opera browser returns more window handles as there are opened tabs or windows. They represent Opera internal features like ''Speed Dial'' or ''Better Address Bar Experience'' (BABE), which are embedded in the browser window, but not displayed like regular tabs. You can switch to these tabs using an appropriate action block, however not all actions are possible then, which can be used with the normal tabs. For example you cannot close them and they don't provide a screenshot. Therefore it is better to not even switch to their contexts. So be careful when switching to a tab by index, as the Opera tabs are among the others and the index might be a different one than for the other browser types.

*'''Chrome: Choose your search engine'''
:Newer versions of Chrome show an [https://www.google.com/chrome/choicescreen/ overlay] at startup, where you have to choose a search engine. Usually, this choice is saved in the user profile. However, if you don't explicitly set a Chrome profile for the connection, each connect will use an empty profile and this question will always show up.

:In most cases, the test can run in the back despite the overlay. However, the overlay counts as tap or window, meaning the block ''[Web] Get Window Handles'' for an example returns a window handle for it and you can switch to it. But you have options to get rid of it:
:* ''--disable-search-engine-choice-screen'': In the [[#Advanced_Settings|advanced settings]] you can add the option <code>--disable-search-engine-choice-screen</code> and the overlay won't show up.
:* ''Choose'': You can extend your test, so it actually chooses a search engine and closes the overlay. There are two things you need to bear in mind. First, you have to switch there using a ''Switch to Window'' block (e.g. by index ''2'' or with an empty title) and back to your original tab afterwards as well. Secondly, the interesting elements in the overlay are [[#Shadow_Elemens|shadow elements]] and as such not directly displayed in the GUI-Browser.

Selenium WebDriver Plugin

2024-08-05T13:11:04Z

Matilk: /* FAQ */ Chrome: Wähle deine Suchmaschine

'''Deutsche Version''' | [[Selenium_WebDriver_Plugin/en|English Version]]
=Achtung=
Das Webtest Selenium WebDriver Plugin ersetzt das bisherige [[Selenium_Web_Test_Plugin|Selenium Web Test Plugin]]. Zur Automatisierung wird [https://www.seleniumhq.org/projects/webdriver/ Selenium WebDriver] verwendet (Driver für gängige Browser werden von uns mitgeliefert), der das bisher verwendete Selenium RC ersetzt. Dies wurde einerseits notwendig, da die SeleniumRC Schnittstelle von neuen Browsern nicht mehr unterstützt wird, andererseits, sinnvoll, da auch andere UI Technologien mit diesem Protokoll angesprochen werden können.

Sie können dieses Protokoll nur noch mit älteren Browsern verwenden, und wir empfehlen dringend, auf die neue Version umzusteigen. Hinweise zur Migration älterer Testsuiten finden Sie [[#Portierung_alter_Selenium-Tests | unten]].

=Einleitung=
Mit dem Selenium WebDriver Plugin können Sie Tests von Webapplikationen erstellen oder auch diese automatisieren (*). Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests oder automatisierten Browseraktionen unterstützt. Zudem ist damit das Aufzeichnen von Abläufen möglich.

(*) tatsächlich gibt es auch WebDriver-Schnittstellen um z.B. Windows-Apps oder OPS-Fenster zu manipulieren. Insofern gibt es für dieses Plugin weitere Einsatzbereiche.

=Einstellungen=
Das Plugin verwendet die Java-Bridge und benötigt daher eine Java-Installation. Sie können diese in den Einstellungen unter ''Erweiterungen'' -> ''Java Bridge'' angeben. Wichtig ist hier das Feld ''Pfad zur Java-Installation'', wo Sie ein JDK oder JRE angeben können. Ist nichts angegeben, versucht expecco java im PATH zu finden.

[[Datei:JDKPfadEinstellungen.png|600px]]

Für das Selenium WebDriver Plugin selbst gibt es ebenfalls Einstellungsmöglichkeiten, die Sie unter ''Erweiterungen'' -> ''Webtest (Selenium WebDriver)'' finden. Hier können Sie zum Beispiel die Adresse zu einem remote laufenden Selenium-Server angeben oder eine andere Jar-Datei für Selenium angeben. Einstellungen zu den verschiedenen Browser-Typen teilen sich auf die Unterseiten ''Beliebte Browser'' und ''Andere Browser'' auf. Dort können Sie den Pfad zur Browser-Ausführungsdatei oder zum Webdriver angeben, der verwendet werden soll. Diese Felder können Sie alle leer lassen, expecco wird dann automatisch danach suchen.

=Browser-Unterstützung=
Das Plugin unterstützt die Browser Chrome/Chromium, Edge, Firefox, Internet Explorer und Opera.
 Safari unter OSX muss zumindest in der Version 10 vorliegen und OSX muss mindestens die El Capitan Version sein.
Zur Kommunikation wird die WebDriver Schnittstelle verwendet; somit kann der getestete Browser sowohl lokal als auch auf einem entfernten Rechner laufen.

Da inzwischen eine Vielzahl von weiteren Browsen, Geräten und graphischen Oberflächen eine WebDriver Schnittstelle anbieten, können auch diese - z.T. mit eingeschränktem Funktionsumfang - über diese automatisiert werden. So gibt es z.B. auch Schnittstellen für Windows Mobilgeräte oder Desktopanwendungen.

== WebDriver aktualisieren==
Für jeden Browsertyp gibt es einen Driver, über den das Starten und Ansteuern der Browserfenster funktioniert. Für die wichtigsten Browser finden sich im Lieferumfang aktuelle Driverversionen. Da die Browser fortlaufend aktualisiert werden, teilweise sogar automatisch, müssen Sie früher oder später neue Driverversionen herunterladen. Legen Sie diese dann in Ihrem expecco-Installationsverzeichnis bei den anderen Versionen ab, und zwar unter:
<code>packages/exept/expecco/plugin/seleniumWebDriver/lib/XXX</code>
(unter Microsoft Windows Betriebssystemen mit "\” anstatt "/"), wobei "XXX" für das Betriebssystem steht (Windows, Linux, OSX etc.).

Im Verbindungsdialog warnt expecco, wenn eine Driverversion nicht zur Browserversion passt. In manchen Fällen kann das aber auch nur daran liegen, dass diese Version zum Zeitpunkt der Auslieferung noch nicht bekannt war. Manche Kombinationen können trotz der Warnung funktioniert, aber das können wir im Einzelfall nicht garantieren.

Daher können Sie bei einer solchen Warnung immer die Option "''Diese Warnung nicht mehr anzeigen''" anwählen, damit diese Driver-Browser-Versionskombination in ihren Settings als "kompatibel" vermerkt wird, und in Zukunft nicht mehr gemeldet wird. Dies sollten Sie aber nur machen, wenn Sie sicher sind, dass Ihre Tests nach wie vor korrekt ausgeführt werden. Da wir hier selbst bisweilen auf Kompatibilitätsprobleme stoßen, und nicht immer gleich klar ist, woran es liegt, empfehlen wir aber den Driver zu aktualisieren.

Für Chrome und Microsoft Edge, bei denen es für jede neue Browserversion auch eine neue Driverversion gibt, finden Sie im Verbindungsdialog einen Button, um mit expecco die passende Version herunterzuladen.

Neuere Versionen der Driver bekommen Sie an folgenden Adressen:
{|
|Chrome/Chromium
|[https://sites.google.com/chromium.org/driver/ ChromeDriver]
|-
|Edge
|[https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/ Microsoft WebDriver]
|-
|Firefox
|[https://github.com/mozilla/geckodriver/releases GeckoDriver]
|-
|Internet Explorer
|[https://selenium-release.storage.googleapis.com/index.html IEDriverServer]
|-
|Opera
|[https://github.com/operasoftware/operachromiumdriver/releases OperaDriver]
|-
|Safari
|[https://webkit.org/blog/6900/webdriver-support-in-safari-10 Safari Support]
|}

Laden Sie sich eine passende Version herunter und legen Sie sie im oben genannten Verzeichnis an der entsprechenden Stelle ab. Expecco wird sie dann finden und verwenden.  Alternativ können Sie auch in expecco den Pfad zu einem Driver angeben, entweder im [[#Erweiterte_Einstellungen | Verbindungseditor]] oder in den [[#Plugin-Einstellungen | Plugin-Einstellungen]].

[[Datei:bulb.png|20px]]Bitte verifizieren Sie, daß die Version des Drivers kompatibel ist mit der des Browsers. Im Zweifel suchen Sie nach der Versionshistorie (z.B. für Chrome: https://chromedriver.storage.googleapis.com/2.25/notes.txt).

[[Datei:bulb.png|20px]]Für den Internet Explorer ist zu beachten, dass der geschützte Modus für alle Zonen gleich eingestellt sein muss, damit eine Verbindung möglich ist. (im Internet Explorer: "''Einstellungen''" - "''Internetoptionen''" - "''Sicherheit''" öffnen, und bei allen 4 Zonen "geschützter" Bereich gleich einstellen; ansonsten kommen beim Verbindungsaufbau Fehler- und Warndialoge). Siehe außerdem die [https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver#required-configuration erforderliche Konfiguration] zur Verwendung des InternetExplorerDrivers.

[[Datei:bulb.png|20px]]Das Plugin verwendet für einige Funktionen JavaScript. Stellen Sie daher sicher, dass die Ausführung von JavaScript im verwendeten Browser erlaubt ist, insbesondere wenn Sie den GUI-Browser oder den Recorder verwenden wollen. Das Ausführen von Tests ist auch ohne JavaScript möglich, solange keine Aktionen verwendet werden, welche JavaScript benötigen oder explizit ausführen. Sollten Sie einen Fehler der Art "<code>org.openqa.selenium.JavascriptException: Error executing JavaScript</code>" bekommen, stellen Sie sicher, dass die Ausführung von JavaScript im verwendeten Browser erlaubt ist und Browser- und zugehörige WebDriver-Version kompatibel sind.

= Headless Browser =
Mit "''Headless''" bezeichnet man eine Anwendung, welche ohne Bedienoberfläche abläuft. Einige der Browser unterstützen einen "headless" Modus, bei dem kein Browserfenster angezeigt wird. Der Browser operiert dabei in einem "unsichtbaren Fenster" führt aber alle Operationen aus, und liefert auch die selbe Elementhierarchie.
Bei einigen Browsern sind allerdings die Screenshot (Bild vom Fenster bzw. von Elementen) eingeschränkt bzw. gar nicht verfügbar. Den "headless" Modus können Sie beim Verbindungsaufbau in den "''Advanced Settings''" angeben.

= HTML Unit Browser =
Bei diesem "''Pseudobrowser''" handelt es sich um eine weitere "''headless''" Variante, welche ganz ohne Renderengine operiert, und lediglich die Elementhierarchie sowie Javascript unterstützt. Sein Verhalten kann stark von dem "echter" Browser abweichen.

Diesen Browsertyp können Sie verwenden, wenn ihr Test das Verhalten des Webservices (also der Servierseite) betrifft, und nicht das Verhalten der Anwendung im Browser (End-User-Experience) im Fokus hat. Zum Beispiel kann der "HTML Unit Browser" zum Generieren von Last oder gleichzeitigen Aktionen gegenüber dem Server dienen.
Da sich dieser Browser im Verhalten z.T. stark von dem echter Browser unterscheidet sollte er nur (wenn überhaupt) in besonderen Fällen verwendet werden.

= Schneller Einstieg =
== Browser öffnen / verbinden ==
* Starten Sie expecco
* Klicken Sie auf "''Neue Testsuite''"
* Klicken Sie auf das GUI-Browser Symbol ([[Datei:GUIBrowser.png|24px]])
* Es erscheint der GUI-Browser in einem neuen Reiter
* Klicken Sie auf "''Verbinden''" und wählen Sie "''Webtest (Selenium WebDriver)''" aus. Dann erscheint der [[#Verbindungseditor | Verbindungsdialog]] (Details siehe unten)
* Im Verbindungsdialog geben Sie die zu testende Webseite ein (z.B. "<code><nowiki>http://www.myHost.com</nowiki></code>") und wählen den Browsertyp (z.B. "<code>chrome</code>" oder "<code>firefox</code>") aus
* Klicken Sie auf "''Verbinden''"
* Ein Browser wird nun automatisch gestartet, und die Seite angezeigt.
* Sobald die Verbindung steht, wird im GUIBrowser die Seitenstruktur als Baum angezeigt, und im rechten Diagramm-Fenster erscheint ein passender Verbindungsbaustein. Dieser wird nicht automatisch aufgezeichnet, da man diesen normalerweise nicht in jeder aufgezeichneten Sequenz haben will (mehr dazu unten).

== Recording aufnehmen ==
* Klicken Sie auf das Recording Symbol im GUI-Browser.
[[Datei:Recording_Start.png | 200px]]
* Ein Recorderfenster erscheint (eine Beschreibung der Bedienelemente finden Sie unten)
* Sie zeichnen nun direkt im Rekorder auf. 
* Klicks werden je nach Einstellung als Klick, Mausbewegung, Drag&Drop etc. aufgezeichnet. Während der Aufzeichnung können Sie zwischen diesen Werkzeugen wechseln: 
[[Datei:Recorder_Werkzeuge.png | 300px]]
* die aufgezeichneten Aktionen werden im Tab "''Aufgezeichnete Sequenz''" dargestellt. Sie können dort noch bearbeitet werden.
* Zum Beenden der Aufzeichnung klicken Sie entweder auf den "''Stop Recording''" Knopf im GUI Browser, oder schließen das Rekorderzenster. Es ist auch möglich, das Aufzeichnen temporär zu Pausieren, indem sie im Rekorder auf den "''Aufnahme''"-Knopf oben links drücken.
* Nach dem Aufzeichnen können sie die Sequenz un ihre Testsuite als Testfall oder Teilsequenz übernehmen.

== Aufgezeichnete Aktion wiedergeben ==

* Im Reiter "''Aufgezeichnete Sequenz''" kann die aktuelle Aufzeichnung sofort wiedergegeben werden ("''Play''"-Knopf drücken) Beachten Sie, daß ihre Webseite üblicherweise im gleichen Zustand sein sollte - gegebenenfalls sollten Sie also den "''Back''"-Knopf oder eine andere Navigation anwenden, um dies sicher zu stellen.
* Die Sequenz kann bearbeitet werden. Dazu können entweder weitere Aktionen aufgenommen werden, oder zusätzliche Aktionen entweder via Drag&Drop oder über das Kontextmenü (bzw. <kbd><CTRL-N</kbd>) angelegt werden. Häufig werden zusätzliche Delay- oder Verifikations-Bausteine benötigt, die sie hiermit an geeigneter Stelle einfügen können.

=Verbindungsaufbau=
==Verbindungseditor==
Mit dem Verbindungseditor werden Verbindungen definiert, geändert und aufgebaut. Sie erreichen ihn, indem Sie den GUI-Browser öffnen und dort auf "''Verbinden''" klicken und dann "''Selenium Testing (WebDriver)''" auswählen.

[[Datei:SeleniumWebDriverConnectDialog.png]]

#''Einstellungen aus Anhang laden'': Öffnet einen Anhang im expecco Projekt mit Verbindungseinstellunge. Diese Einstellungen werden in den Editor übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#''Einstellungen aus Datei'': Öffnet eine gespeicherte Einstellungsdatei (*.csf). Diese Einstellungen werden in den Editor übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#''Einstellungen in Anhang speichern'': Hier können Sie die eingetragenen Einstellungen als Anhang im expecco-Projekt anlegen.
#''Einstellungen in JSON-Anhang speichern'': Hier können Sie die eingetragenen Einstellungen im JSON-Format als Anhang im expecco-Projekt anlegen.
#''Einstellungen in Datei speichern'': Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern.
#''Versionsinfo'': Zeigt ein Fenster mit den verwendeten Versionen des Selenium-Servers, des ausgewählten Browser und dessen Driver an.
#''Online-Dokumentation'': Öffnet diese Online-Dokumentation.
#''Verbindungsname'': Tragen Sie hier den Namen ein, unter dem die Verbindung im GUI-Browser angezeigt werden soll. (Optional)
#''Browsertyp'': Wählen Sie hier aus, welchen Browser Sie verwenden möchten. Stellen Sie sicher, dass dieser installiert ist und die Version des verwendeten Drivers zur Browserversion passt.
#''URL'': Tragen Sie hier die URL ein, die zu Beginn aufgerufen werden soll. Sie können das Feld auch frei lassen, dann wird ein leeres Browser-Fenster geöffnet. Um eine lokale Datei zu öffnen, verwenden Sie das Schema "<code>file://</code>", z.B. "<code>file:///C:/Users/admin/Desktop/index.html</code>".
#''Erweiterte Ansicht'': Wechselt zur Ansicht für die Eingabe von [[#Erweiterte Einstellungen|erweiterten Einstellungen]].
#''Informationen zum gewählten Browser'': Hier wird der ausgewählte Browsertyp kurz vorgestellt.
#''Informationen zu den Einstellungen'': Hier wird angezeigt, welche Selenium-, Browser- und Driver-Version mit den aktuellen Einstellungen verwendet wird. Falls Sie [[#Erweiterte Einstellungen|erweiterten Einstellungen]] gesetzt haben, werden diese hier ebenfalls aufgelistet.

===Warnung über mögliche Inkompatibilität ===
Manche Browser benötigen einen versionsspezifischen Webdriver, da die verwendeten Kommunikationsprotokolle unterschiedlich sein können.

Da regelmässig neue Browserversionen erscheinen, und damit einhergehend auch neue Versionen des zug. Webdrivers benötigt werden, kann. es sein, dass die mit expecco mitgelieferten Webdriver nicht mehr zur aktuellen Browserversion passen. Dies trat in der Vergangenheit insbes. beim Chromebrowser mehrfach auf.

Um auf eventuelle Probleme hinzuweisen hält expecco intern eine Liste von Paaren der von exept bereits getesteten Browser- zu Webdriverversion. Falls ihr Browser aktueller ist, und nicht in der Liste enthalten ist, erscheint eine Warnung im Infobereich.

Diese erscheint nur zu Ihrer Information - in den meisten Fällen funktioniert die Interaktion mit dem Browser auch dann. Allerdings ist es in jedem Fall sinnvoll, den Driver zu aktualisieren, um solche Probleme auszuschliessen.
Wenn die Kombination ohne Probleme läuft, ist es möglich, die aktuelle Kombination in die Liste einzutragen (drücken Sie dazu auf "Diese Kombination ist in Ordnung"). Dann erschient der Warndialog nicht mehr.

===Erweiterte Einstellungen===
Neben dem zu verwendenden Browser und der Start-URL kann man noch weitere Einstellungen für eine Verbindung vornehmen. Wechseln Sie dazu im Verbindungsmenü die Ansicht über den entsprechenden Menü-Eintrag. Je nachdem, welchen Browsertypen Sie ausgewählt haben, bekommen Sie andere Eingabefelder.

*''Remote Server'': Falls der Browser auf einem entfernten Rechner gestartet werden soll, starten Sie dort einen Selenium-Server und geben Sie dessen Adresse in diesem Feld an. Natürlich können Sie auch eine lokale Adresse angeben, wenn nicht automatisch ein Selenium-Server gestartet werden soll. Lesen Sie hierzu auch den nächsten Abschnitt [[#Remote-Verbindungen|Remote-Verbindungen]].
*''Binary'': Geben Sie den Pfad zum Binary des ausgewählten Browsers an, wenn dieser nicht automatisch von Selenium gefunden wird oder Sie eine weitere Version installiert haben.
*''Driver'': Zu jedem Browser wird ein spezieller Driver zur Automatisierung benötigt. Für neue Versionen des Browsers braucht man häufig auch eine neue Version des entsprechenden Drivers. Wenn Sie nicht den von expecco installierten Driver verwenden wollen, geben Sie hier einen entsprechenden Pfad an.
*''Firefox Profile'': Für Firefox gibt es zusätzlich die Möglichkeit, ein Profil bzw. Template anzugeben, das spezifische Einstellungen enthält. Wenn keines angegeben wird, wird für jede Verbindung ein neues, leeres Profil angelegt.
*''Capabilities'': Für Selenium-Verbindungen sind einige Capabilities definiert, mit denen sich Verbindungs-Eigenschaften oder auch das Browserverhalten festlegen lassen.
Solche Capabilities können Sie sie in diesem Feld angeben. Schreiben Sie dazu ''<capability name>: <value>'' oder ''<capability name> = <value>''; jeweils ein Eintrag pro Zeile. Außerdem können Sie hier auch Eigenschaften für den Firefox-Browser setzen. Die Eingabe hierfür erfolgt wie für die Capabilities, nur dass sie dem Namen der Eigenschaft ein ''$'' voranstellen müssen.

:Angegebene Capabilities werden durch die Methode ''setCapability()'' gesetzt. Insbesondere bei der Verwendung von Chrome gibt es einige Einstellungsoptionen, die sich nicht mit dieser Methode setzen lassen, sondern beispielsweise über ''setExperimentalOption()'' angegeben werden müssen. Zu diesem Zweck haben Sie außerdem die Möglichkeit, in diesem Feld einen Methodenaufruf mit Werten anzugeben. Diese Methode wird dann auf das entsprechende Options- bzw. Capabilities-Objekt angewandt. Um die Struktur der Eingabe von normalen Capabilities beizubehalten, müssen Sie am Ende noch '':'' oder ''='' setzen, aber keinen Wert danach. Beispiel: ''setExperimentalOption(“useAutomationExtension”, false)=''

==Lokale-Verbindungen==
Um einen Browser auf ihrer lokalen Maschine zu starten, werden lediglich die Felder "''URL''" sowie "''Browsertyp''" benötigt. Als Voreinstellung für den Browser wird "<code>chrome</code>" erscheinen.

==Remote-Verbindungen==
Um einen Browser auf einem entfernten Rechner zu starten, müssen Sie zunächst den Selenium-Server und die benötigten Driver auf diesen Rechner kopieren. Auf dem Zielrechner muss Java installiert sein. Sie finden die Dateien in Ihrer expecco-Installation unter "<code>packages/exept/expecco/plugin/seleniumWebDriver/lib</code>". Sie können sich auch von [https://www.selenium.dev/downloads/ Selenium] eine aktuelle Version herunterladen.
 Starten Sie dann den Selenium-Sever (auf dem entfernten Rechner) mit:
java -jar selenium-server-standalone-3.141.59.jar
(die Versionsnummer wird in Ihren Fall eine andere sein)

Standardmäßig wird der Server dann auf dem Port 4444 Verbindungen annehmen. Um einen anderen Port zu verwenden,
geben Sie diesen auf der Kommandozeile mit "<code>-port <nr></code>" an.
 Um von expecco eine Verbindung über diesen Server herzustellen, geben Sie beim Verbindungsaufbau als Remote-Server
<Server-Adresse>:4444/wd/hub
an.

Das Starten des Selenium-Servers bzw. die Verbindung muss eventuell von der Firewall zugelassen werden.

Falls der Server beim Verbinden die jeweiligen Driver nicht finden, legen Sie diese ins selbe Verzeichnis, in dem Sie den Server starten, oder fügen Sie das Verzeichnis in dem der Driver liegt zum Pfad hinzu. Beachten Sie dabei, dass expecco verschiedene Versionen eines Driver-Typs mitliefert und diese durch einen Namenszusatz unterscheidet. Aufgrund dieser Zusätze erkennt der Server die Dateien aber häufig nicht.

Für neue Versionen von '''Microsoft Edge''', die Chromium basieren, starten Sie anstatt eines Selenium-Servers direkt den MSEdgeDriver ("msedgedriver.exe") in der Version, die zur Edge-Version auf diesem Rechner passt.
msedgedriver.exe [--port=9515]
Wenn Sie keine Portnummer angeben, wird der Service auf dem Port 9515 gestartet. Geben Sie dann beim Verbindungsaufbau in expecco als Remote-Server die Adresse
<Server-Adresse>:9515
an. Die Erweiterung "/wd/hub" ist hier nicht erforderlich.

==Verbindungsbausteine==
Der Verbindungsaufbau, welcher im GUI Browser interaktiv erfolgt, muss natürlich bei einem automatisierten Ablauf über einen Aktionsbaustein erfolgen.
Dazu gibt es in der SeleniumWebDriverLibrary im Ordner "''Connection''" verschiedene Bausteine, welche die Verbindungsparameter von verschiedenen Quellen erhalten:
* Connect Dieser Baustein erhält die Verbindungsparameter über Eingangspins
* Connect from File Hier werden die Einstellungen aus einer Datei (Anhang) gelesen (typischerweise im JSON Format)
* Connect from Spec Die Verbindungsparameter werden in einem Dictionaryobjekt geliefert
* Reuse or Start Connection Im Gegensatz zu obigen Bausteinen, welche immer eine neue Browserverbindung aufbauen (i.e. ein neues Browserfenster öffnen), wird dieser Baustein zunächst prüfen, ob bereits eine Verbindung besteht, und diese gegebenenfalls wiederverwenden. Dieser Baustein kann daher mehrfach (i.e. zu Beginn von Teilsequenzen) platziert werden, und damit die Teilsequenzen sowohl innerhalb eines komplexeren Gesamttests als auch "stand-alone", d.h. einzeln ausgeführt werden.

Alle "Connect" Bausteine benötigen die Angabe eines "''Verbindungsnamens''".
Dieser hat die Aufgabe, die Verbindung im weiteren Testverlauf zu identifizieren, wenn zwischen mehreren Verbindungen gewechselt wird, und zum Abbauen der Verbindung.

Wenn Sie im GUI Browser im Elementbaum auf eine Verbindung klicken, erscheint in der rechten "Test" Kachel ein Connect Baustein mit entsprechend vorgelegten Parametern. Diesen können Sie bei Bedarf gleich in die Rekordersequenz übertragen, oder (besser) als separate Aktion speichern (es ist sinnvoll, den Verbindungsaufbau von den aufgezeichneten Teilsequenzen zu trennen; damit haben Sie es später leichter, andere Browser zu verwenden, die Parameter der Verbindung zu ändern und auch neue Teilsequenzen aufzuzeichnen oder zu modifizieren.

Verbindungen mit komplexen Einstellungen werden typischerweise im Verbindungsdialog angelegt, und die Einstellungen von dort über die Menüfunktion "''Sichern in Anhang/Datei''" in einer Datei gesichert. So können Sie verschiedene Konfigurationen in einzelnen Dateianhängen in ihrer Testsuite oder auch außerhalb aufbewahren. Zum Verbinden verwenden Sie dann den Aktionsbaustein "[''Connect From File'']".

=Plugin-Einstellungen=
Wenn Sie eine bestimmte Browser-Installationen oder Driver standardmäßig als Voreinstellung verwenden möchten, können Sie diese in den Einstellungen des Plugins eintragen. Sie finden sie über das Menü unter dem Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" → "''Webtest (Selenium WebDriver)''". Einstellungen für spezifische Browser finden Sie unter den Unterpunkten "''Beliebteste Browser''" bzw. "''Andere Browser''".
Die dortigen Einstellungen gelten als Voreinstellung für jede Verbindung, es sei denn in einer konkreten Verbindungseinstellungen ist etwas anderes angegeben.

===Ausführungsverzögerung für Chrome===
In manchen Fällen kann es bei Verwendung des Chrome-Browsers vorkommen, dass Bausteine mit Element-Aktionen, beispielsweise ein Klick, im Test erfolgreich durchlaufen, die eigentliche Aktion aber gar nicht ausgeführt wurde. Dies ist ein bekannter Fehler [https://github.com/MPDL/imeji-gui-testing/issues/37], [https://github.com/SeleniumHQ/selenium/issues/4075], der von Selenium bzw. chromedriver behoben werden muss.

Der Fehler lässt sich verhindern, indem entweder der Klick über JavaScript aufgerufen wird (setzen Sie dazu im Klick-Baustein ''invokeDirectly'' auf ''true'' ) oder vor der Aktion kurz gewartet wird. Die Ausführung über JavaScript hat den Nachteil, dass sie weniger nah am Klick eines echten Benutzers ist; beispielsweise funktionieren Klicks auf Elemente auch dann, wenn sie von anderen Elementen verdeckt werden (was bei einem "normalen"Klick nicht geht).

Generell warten die Bausteine mit Element-Aktionen automatisch, bis das entsprechende Element verfügbar ist (existiert). In den hier beschriebenen Fällen reicht das aber nicht aus. Deshalb finden Sie in den Plugin-Einstellungen für Chrome die Einstellung "''Ausführungsverzögerung''". Bei der Ausführung wird dann zwischen den Aktionen entsprechend lange gewartet. Falls bei Ihnen der beschriebene Fehler eintritt, können Sie diesen Wert erhöhen. Ein größerer Wert hat natürlich Auswirkung auf die Gesamtlaufzeit.

=Recorder=

Die folgende Beschreibung des Recorders gilt prinzipiell für alle von expecco unterstützten GUI Technologien. Verhalten und Bedienung sind bis auf kleine technologiebedingte Unterschiede für alle gleich.

Besteht im GUI-Browser eine Verbindung mit einem Browserfenster, kann der integrierte Recorder verwendet werden, um einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Für jeden Klick im Fenster wird eine Aktion aufgezeichnet. Weitere Aktionen stehen über das Menü zur Verfügung. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

Allgemeine Aktionen finden Sie entweder direkt in der Menüleiste oder dort im Browser-Werkzeuge-Menü (s.u.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Element-Werkzeugs in der Menüleiste (s.u.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion. Auf diese Weise ist es ebenfalls möglich, die Eingaben ''Backspace'', ''Return'' und ''Tab'' aufzuzeichnen.

[[Datei:SeleniumWebDriverRecorder.png]]

'''Komponenten des Recorderfensters'''
#'''Aufnahme Pausieren''': Wenn die Kontrollleuchte rot ist, nimmt der Recorder auf. Durch Klicken können Sie die Aufnahme anhalten. Die Kontrolleuchte leuchtet dann grau. In diesem Zustand können Sie weiter Aktionen über das Recorder-Fenster ausführen, sie werden aber nicht aufgezeichnet. Klicken Sie erneut, um die Aufnahme weiterzuführen.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Browser. Dies wird nötig, wenn die Anzeige des Recorders nicht mit dem tatsächlichen Browserinhalt übereinstimmt.
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Element-Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Es stehen alle Aktionen zur Verfügung, die auf ein bestimmtes Element ausgeführt werden. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst und das Element aus der Position bestimmt. Die nicht ausgewählten Aktionen sind jederzeit über einen Rechtsklick erreichbar.
#'''Browser-Werkzeuge''': Aktionen die sich nicht auf bestimmte Elemente beziehen, wie Scrollen oder Aktionen auf die aktuelle URL oder den Titel, können hier ausgelöst werden.
#'''Seitennavigation''': Aktionen zur Seitennavigation: ''eine Seite zurück'', ''eine Seite vor'' und ''aktuelle Seite neu laden''
#'''Alert-Behandlung''': Wenn der Browser einen Alert anzeigt, klicken Sie auf diesen Button, um die Aktionen zur Alert-Behandlung auswählen zu können.
#'''Online Dokumentation''': Öffnet diese Online-Dokumentation.
#'''Anzeige''': Zeigt einen Screenshot des Browsers. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot. Scrollen wird den Browser weitergeleitet, aber nicht aufgenommen.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Skalierung''': Ändert die Skalierung des Screenshots. Diese kann auch über Scrollen in der Anzeige bei gedrückt gehaltener Strg-Taste angepasst werden.
#'''Meldungen''': Hier werden Meldungen angezeigt, bspw. wenn eine Aktion nicht aufgenommen werden konnte. Die letzte Meldung wird solange angezeigt, bis sie über den Button rechts daneben geschlossen wird. '''Fenster-Tabs''': Ab expecco 23.1 werden oberhalb der Anzeige Tabs für jedes offene Fenster angezeigt, sobald eine Verbindung mehr als ein Browserfenster besitzt. Ob der Browser dieses als Tab oder in einem eigenen Fenster anzeigt, ist dabei egal. Über die Tabs im Recorder können Sie das aktuelle Fenster wechseln und diesen Wechsel auch aufzeichnen. '''Frame-Kontext''': Ab expecco 23.1 sehen Sie unterhalb der Anzeige, in welchem Frame-Kontext Sie sich gerade befinden (siehe dazu den Abschnitt [[#Eingebettete_Inhalte|Eingebettete Inhalte]]). Sie können auf die Einträge klicken, um in einen höheren Kontext zu wechseln und diesen Wechsel aufzuzeichnen. Falls Sie zusammengesetzte Pfade eingestellt haben, wird die Anzeige aktualisiert, wenn Sie ein eingebettetes Element ausgewählt haben.

=Eingebettete Inhalte=
In HTML ist es möglich, auf einer Seite Inhalte einer anderen einzubinden. Das gängigste Elemente dafür ist ein Iframe (Inlineframe). Auf den Inhalt eines Iframes kann ebenfalls mit Selenium zugegriffen werden, allerdings muss dazu zuerst in diesen Kontext gewechselt werden. In der SeleniumWebDriverLibrary gibt es entsprechenden Bausteine, um in den Kontext eines Iframes zu wechseln, um in den Elternkontext zu wechseln und um zurück zum Standardinhalt, also dem obersten Kontext zu wechseln. Alle Element-Bausteine lösen die angelegten Pfade immer innerhalb des aktuellen Kontexts auf. Im GUI-Browser sehen Sie für eingebettete Inhalte ein zusätzliches Element, welches sie aufklappen können um dessen Elemente zu sehen.

==Zusammengesetzte Pfade==
Seit expecco 23.1 gibt es die Möglichkeit, auch zusammengesetzte Pfade an den Bausteinen zu verwenden, um direkt vom Standardinhalt auf den Inhalt eines Iframes zugreifen zu können. Dazu werden einfach der Pfad zum Iframe und der Pfad innerhalb des Iframe-Inhalts zu einem zusammengesetzt. Wichtig ist hierbei, dass beim Übergang keine Elemente ausgelassen werden dürfen, d.h. der vordere Teil muss mit dem Iframe-Element enden und der hintere Teil mit ''/body'' beginnen. Dazwischen dürfen die Pfade gekürzt werden und es ist natürlich auch möglich auf diese Art beliebig tief geschachtelte Elemente zu erreichen. An den Bausteinen können beide Techniken nach belieben verwendet werden, wichtig ist nur, dass die Pfade immer in dem Kontext aufgelöst werden, in dem sich Selenium gerade befindet.

Wenn Sie die kombinierten Pfade aufzeichnen, bzw. im GUI-Browser verwenden wollen, setzen Sie im Menü ''GUI Browser'' unter ''Aufzeichnung'' den Haken bei ''Zusammengesetzte Pfade aufzeichnen''. Damit wird für eingebettete Elemente ein zusammengesetzter Pfad relativ zum aktuellen Kontext erzeugt und angezeigt, anstatt wie bisher nur innerhalb seines eigenen Kontexts. Außerdem können Sie diese Elemente auch direkt im Recorder ansprechen oder über Follow-Mouse finden.

=Shadow-Elemente=
Shadow-DOMs sind eine Möglichkeit, um Teile einer Seite vom übrigen Dokument abzukapseln. Dabei werden an ein Element versteckte Shadow-Elemente angehängt. Eine ausführlichere Erklärung finden Sie zum Beispiel hier: [https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM Using shadow DOM - Web APIs | MDN].

In der SeleniumWebDirverLibrary gibt es den Baustein ''[Web] Get Shadow DOM'', der die obersten Elemente liefert, die dann wie andere WebElemente verwendet werden können.

Da die Elemente versteckt sind, werden sie vom GUI-Browser nicht direkt angezeigt. Ab expecco 23.1 kann man allerdings im Kontextmenü der Elemente im GUI-Browser einen Haken setzen, dass Shadow-Elemente gesucht werden sollen. Beim Aktualisieren der Kinder eines Elements werden sie dann angezeigt, falls vorhanden, allerdings nicht, wenn der gesamte Baum aktualisiert wird. Wenn der Haken gesetzt ist, sind die Elemente auch im Recorder verfügbar.

==Zusammengesetzte Pfade==
Ähnlich wie die Elemente innerhalb eines Frames kann auch auf die Shadow-Elemente direkt über zusammengesetzte Pfade zugegriffen werden. Diese Pfade können dann direkt an den Bausteinen verwendet werden, sodass der Baustein ''[Web] Get Shadow DOM'' nicht benötigt wird. Die Pfade haben die Form
<host path>/shadowRoot/<shadow path>
wobei ''<host path>'' den Pfad zum Element angibt, an das der Shadow-DOM angehängt wurde, und ''<shadow path>'' der Pfad innerhalb des Shadow-DOMs zum gewünschten Element ist. '/shadowRoot' dient als Marker, dass an dieser Stelle der Wechsel in den Shadow-DOM erfolgt.

=Authentifizierungs-Alerts=
Falls eine Webseite HTTP-Authentifizierung mit Basic Authentication verwendet, öffnet sich beim Laden der Seite ein Alert-Fenster zur Eingabe von Benutzernamen und Passwort. Dieses Fenster ist nicht direkt mit Selenium bedienbar. Im GUI-Browser wird es wie ein Alert angezeigt. Eine Ausnahme hierzu bildet Chrome, bei dem der Driver auf keine Anfrage antwortet solange der Dialog geöffnet ist. Das Plugin kann zu diesem Zeitpunkt insbesondere nicht feststellen, ob ein Authentifizierungs-Dialog geöffnet ist oder ob der Driver aus anderen Gründen nicht antwortet.

Bei lokalen Verbindungen unter Windows kann eine Authentifizierung mittels Windows Access ausgeführt werden. Es gibt in der SeleniumWebDriverLibrary für einzelne Browsertypen spezifische Authentifizierungs-Bausteine sowie den Baustein ''Authenticate at Alert'', der je nach Verbindung den entsprechenden Baustein ausführt. Für die verschiedenen Browser-Typen gibt es dabei unterschiedliche Einschränkungen:

:'''Chrome:''' Die Anmeldedaten werden an ein Chromefenster geschickt, daher funktioniert es nur, wenn nicht mehrere geöffnet sind. Der Einzelbaustein hat für diesen Fall die Option, den Titel des Fensters anzugeben.
:'''Edge''': Mit Microsoft Edge wird eine Anmeldung nicht unterstützt.
:'''Firefox''': Schickt die Anmeldedaten an ein Firefox-Dialogfenster und funktioniert daher nur, wenn es nicht mehrere gibt.
:'''Internet Explorer''': Mit dem Internet Explorer wird eine Anmeldung nicht unterstützt.

Als zusätzliche Option steht Ihnen auch eine Anmeldung über die URL zur Verfügung. Rufen Sie anstatt der Seite <nowiki>https://www.example.com</nowiki> die URL <nowiki>https://user:password@www.example.com</nowiki> auf. Wichtig ist hierbei, dass '':'' und ''@'' nicht im Benutzernamen oder im Passwort auftauchen. Möglicherweise wird diese Methode nicht von jedem Browser unterstützt.

Mithilfe des [[WindowsAutomation_Reference_2.0|WindowsAutomation2]]-Plugins ist es ebenfalls möglich, solch eine Anmeldung mit allen Browsertypen auszuführen.

=Portierung alter Selenium-Tests=
Dieses Plugin ersetzt das bisherige [[Selenium_Web_Test_Plugin|Selenium Web Test Plugin]]. Dieses basierte auf [https://www.seleniumhq.org/projects/remote-control/ Selenium RC], welches in Zukunft von den Browsern nicht mehr unterstützt wird. Der Nachfolger von Selenium RC ist [https://www.seleniumhq.org/projects/webdriver/ Selenium WebDriver], auch ''Selenium 2'' genannt. Ebenso ist auch das Aufzeichnen von Tests mit [https://www.seleniumhq.org/projects/ide/ Selenim IDE] veraltet, da das Plugin von neueren Browsern nicht mehr unterstützt wird. Das Selenium WebDriver Plugin verwendet stattdessen einen eigenen [[#Recorder|Recorder]].

Tests, die mit dem alten Selenium Web Test Plugin erstellt wurden und die alte SeleniumLibrary verwenden, können über Selenium WebDriver ausgeführt werden. Setzen Sie dazu in den Plugin-Einstellungen von "''Webtest Legacy (Selenium)''" den Haken bei "''WebDriver für die Ausführung verwenden''". Für die wichtigsten Funktionen wurde Wrapper bzw. umsetzende Funktionen erstellt, um die Migration möglichst problemlos zu gestalten.
Testen Sie dann, ob die Tests wie bisher ablaufen. Für den überwiegenden Teil der Bausteine sollte es dabei keine Probleme geben. Einige wenige Aktionen werden in der WebDriver Version nicht mehr unterstützt oder verhalten sich unterschiedlich. Es ist auch nicht garantiert, daß die Emulation der alten Schnittstelle auf Dauer von Selenium unterstützt werden. Wenn möglich sollten Sie daher über kurz oder lang die Testfälle umschreiben.

=FAQ=
*'''Scrollbalken lassen sich im Recorder nicht bedienen'''
:Der Scrollbalken des Browsers, der automatisch angezeigt wird, wenn eine Seite größer als das Browserfenster ist, ist kein bedienbares Webelement. Scrollen um einen bestimmten Betrag ist in einem Test selten sinnvoll, wenn die Größe des Browserfensters nicht festgelegt ist. Verwenden Sie stattdessen den Baustein <code>[Web] Scroll Element into View</code>, um ein entsprechendes Element in den sichtbaren Bereich zu scrollen. Der Klick-Baustein, den der Recorder standardmäßig verwendet, führt diese Aktion bereits automatisch mit aus (<code>[WebElement] Click (Scroll Element into View)</code>). Wenn Sie im Recorder-Fenster scrollen, wird dies automatisch auf den Browser übertragen, aber nicht aufgezeichnet. Falls Sie tatsächlich um einen bestimmten Betrag scrollen möchten, gibt es bei den Browser-Aktionen einen Eintrag dafür und weitere Bausteine in der SeleniumWebDriverLibrary.

*'''Baustein schlägt fehl, wenn Element zu spät sichtbar wird'''
:Alle Bausteine, die einen Elementpfad verwenden, haben automatisch eingebaut, dass sie warten, bis ein entsprechendens Element auftaucht. Es gibt aber Fälle, in denen ein Element zwar bereits da, aber noch nicht sichtbar ist. Bei einem Klick auf das Element bekommen Sie dann einen Fehler. Mögliche Fehler in diesem Zusammenhang sind <code>org.openqa.selenium.ElementNotInteractableException: element not interactable</code> und <code>org.openqa.selenium.JavascriptException: javascript error: Cannot read property 'left' of undefined</code>. Verwenden Sie dann vor einer Interaktion mit dem Element den Baustein <code>[Web] Wait for Visibility of Element</code> oder <code>[Web] Wait for Element to Be Clickable</code>.

*'''Fehlermeldung: <code>Cannot read property 'left' of undefined</code>'''
:Der Fehler <code>org.openqa.selenium.JavascriptException: javascript error: Cannot read property 'left' of undefined</code> kann mit dem Chrome-Browser auftreten. In diesem Fall ist das verwendete Element nicht sichtbar. Lesen Sie dazu den Punkt oben. Der Fehler ist auch im Zusammenhang mit Elementen in einer Dropdown-Liste bekannt, d.h. bei einem Klick oder dem Bewegen der Maus auf ein <nowiki><option></nowiki>-Element innerhalb eines <nowiki><select></nowiki>-Elements. Diese Elemente sind prinzipiell nicht klickbar. Verwenden Sie stattdessen einen passenden <code>[Web] Select</code>-Baustein mit dem <nowiki><select></nowiki>-Element.

*'''Fehlermeldung: <code>Stale Element Reference Exception</code>'''
:Der Fehler <code>org.openqa.selenium.StaleElementReferenceException</code> tritt immer dann auf, wenn ein WebElement verwendet wird, das nicht mehr da ist. Wenn das in Ihrem Test passiert und das Element eigentlich da sein sollte, verwenden Sie an der Stelle stattdessen den Locator, um das Element neu zu holen. Eventuell liegt es auch daran, dass sich der Test momentan in einem anderen Frame-Kontext befindet als das Element. Wenn Sie [[#Zusammengesetzte_Pfade|zusammengesetzte Pfade]] verwenden, sollte das Element selbst in den richtigen Kontext wechseln, bevor Aktionen darauf ausgeführt werden.
:In seltenen Fällen kann der Fehler auch in expecco selbst auftreten, wenn an irgendeiner Stelle im GUI-Browser oder Recorder ein entsprechendes WebElement verwendet wird. Sie sollten dann abbrechen können und es nochmal versuchen. Sollte der Fehler bestehen bleiben, wechseln Sie in den Default Content und laden Sie den Baum im GUI-Browser neu.

*'''Baustein läuft erfolgreich, aber ohne Auswirkungen'''
:Dieser Fall kann mit Chrome auftreten. Das Element ist verfügbar, die Aktion wirft keinen Fehler, aber es wird nichts ausgeführt. In der Regel hilft es, vor der Ausführung kurz zu warten, siehe [[#Ausf.C3.BChrungsverz.C3.B6gerung_f.C3.BCr_Chrome | Ausführungsverzögerung für Chrome]].

*'''Ausführungen mit Chrome sind langsamer'''
:Um ein Problem bei der Ausführung mit Chrome zu beheben, ist in den Plugin-Einstellungen für Chrome eine Verzögerung definiert. Überprüfen Sie, ob dieser Wert eventuell zu hoch eingestellt ist; siehe [[#Ausf.C3.BChrungsverz.C3.B6gerung_f.C3.BCr_Chrome | Ausführungsverzögerung für Chrome]].

*'''Fehlermeldungen wie: "org.openqa.selenium.InvalidArgumentException: Expected "handle" to be a string..."'''
:Dies passiert wenn der Driver nicht (mehr) zum Browser passt. Lesen Sie dazu obiges Kapitel "[[#WebDriver aktualisieren|WebDriver aktualisieren]]".

*'''Key Chords mit Shortcuts funktionieren nicht'''
:Das Drücken mehrerer Tasten gleichzeitig lässt sich als Key Chord simulieren. Dadurch können auch Shortcuts eingegeben werden. Allerdings funktionieren hier nicht alle Eingaben, da diese nur an den Seiteninhalt und nicht an den Browser selbst gehen. Kombinationen wie ''Strg + t'' um einen neuen Browsertab zu öffnen, funktionieren daher vermutlich nicht, ''Strg + a'' oder ''Strg + c'' sollten hingegen möglich sein.

*'''Zusätzliche Window Handles mit Opera'''
:Der Opera-Browser liefert mehr Window Handles als Tabs bzw. Fenster geöffnet sind. Diese kommen von Opera-internen Funktionen wie dem Schnellstart (''Speed Dial'') oder der ''Better Address Bar Experience'' (BABE), die zwar im Browserfenster eingebunden, aber nicht als Tab angezeigt werden. Zu diesen Tabs kann zwar mit den entsprechenden Bausteinen gewechselt werden, es sind dann aber nicht alle Aktionen möglich, die für die normalen Tabs zur Verfügung stehen. Sie können zum Beispiel nicht geschlossen werden und man bekommt von ihnen kein Bild. Am besten wechselt man daher gar nicht erst in diese Kontexte. Seien Sie also vorsichtig, wenn Sie anhand des Index zu einem Tab wechseln wollen, da sich die Opera-Tabs zwischen den anderen befinden und der Index ein anderer als für die anderen Browser sein kann.

*'''Chrome: Wähle deine Suchmaschine'''
:Neuere Chromeversionen zeigen nach dem Starten ein Overlay, bei dem man die verwendete Suchmaschine auswählen soll. Die Entscheidung wird normalerweise im Benutzerprofil gespeichert. Wenn für die Verbindung aber nicht explizit ein Chrome-Profil angegeben wird, hat man bei jedem Verbindungsaufbau ein leeres Profil und es wird immer nachgefragt.

:In vielen Fällen kann der Test auch trotz des Overlays im Hintergrund ablaufen. Das Overlay gilt aber wie ein Tab bzw. Fenster; so liefert beispielsweise vom Baustein ''[Web] Get Window Handles'' einen Handle dafür und es kann auch dorthin gewechselt werden. Es gibt aber auch Möglichkeiten es loszuwerden:
:* ''--disable-search-engine-choice-screen'': In den [[#Erweiterte_Einstellungen|erweiterten Einstellungen]] kann man bei den Optionen <code>--disable-search-engine-choice-screen</code> angeben, dann kommt das Overlay nicht.
:* ''Auswählen'': Sie können Ihren Test auch so erweitern, dass zu Beginn eine Suchmaschine ausgewählt und damit das Overlay geschlossen wird. Dabei müssen Sie zwei Dinge beachten. Zum einen müssen Sie zuerst mit einem ''Switch to Window''-Baustein dorthin wechseln (z.B. mit Index ''2'' oder leerem Titel) und am Ende auch wieder zurück zu Ihrem ursprünglichen Tab. Zum anderen sind interessanten Elemente des Overlays [[#Shadow-Elemente|Shadow-Elemente]] und werden daher im GUI-Browser nicht direkt angezeigt.

Mobile Testing Plugin/en

2024-07-24T14:27:38Z

Matilk: /* Windows */

[[Mobile_Testing_Plugin|Deutsche Version]] | '''English Version'''

= Introduction =
The ''Mobile Testing Plugin'' adds mechanisms to test and automate Android and iOS devices. This includes both real and emulated devices - it does not matter whether real mobile devices or emulated devices are used. The plugin can (and usually is) used in conjunction with the [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]], which supports the creation of tests. It can also be used to record test procedures.

[http://appium.io/ Appium] is used to connect to the devices. Appium is a free open source framework for testing and automating mobile applications.

We recommend to go through the [[Mobile_Testing_Tutorial/en|Tutorial]] to familiarize yourself with the Mobile Plugin. This tutorial leads step by step through the creation of a test case using an example and explains the necessary basics.

= Installation and Setup =
To use the ''Mobile Testing Plugin'', you must have installed expecco together with the corresponding plugin, and you need the appropriate licenses. expecco communicates with the mobile devices via an Appium server, which either runs on the same computer as expecco, or on a second computer. This must be accessible for expecco.

== Installation Overview ==
'''Computer running expecco:'''
* Java JDK version 8, 9, 10 or 11
'''Computer connected to Android devices :'''
* Appium Server, you can install it via the Mobile Testing Supplement (see below), of which we regularly provide a new version
* Android SDK, you can also get it with the Mobile Testing Supplement
* Java JDK version 8, 9, 10 or 11
'''Computer connected to iOS devices*:'''
* Appium Server, you can install it via the Mobile Testing Supplement for MacOS (see below), of which we regularly provide a new version
* Xcode in a version that supports the iOS version used, available from the Apple App Store
* Java JDK version 8, 9, 10 or 11
* Apple Developer Certificate incl. matching private key (to sign the WebDriverAgent)
* Provisioning Profile for the mobile devices to be used

* Please note that due to the requirements (no connection to non-Apple devices available) iOS devices can only be controlled from a Mac.

Depending on the setup, the above-mentioned computers can also be the same device. expecco can either connect to a remote Appium Server and mobile devices connected to it via the network, or start an Appium Server locally itself and use it with local mobile devices. However, some of expecco's functions that make it easier to create test cases are only available if the mobile devices are connected to the same computer on which expecco is running. A possible setup may therefore look like the following figure:

[[Datei:MobileTestingAufbau.png | 400px]]

The following explains how to install Appium and other necessary applications for Windows and Mac OS.

== Windows ==
The easiest way is to install everything from our Mobile Testing Supplement. However, newer versions do not contain a JDK anymore due to a change in Oracle's license terms, so you have to install it additionally. Of course, you are free to install Appium directly to use the version you want. However, to then be able to start an Appium server with expecco, a suitable batch file must be available and specified in the [[Mobile_Testing_Plugin/en#Plugin_Configuration|settings]]. However, connections can also be established to other running Appium servers.
*'''expecco 24.1''': [https://download.exept.de/transfer/h-expecco-24.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.3]
:Same versions as in the predecessor, but with updated chromedriver versions
*expecco 23.2: [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Same versions as in the predecessor, but with updated chromedriver versions
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Same versions as in the predecessor, but the installer now allows to add Appium to the Autostart.
*expecco 22.2 and 22.1: [https://download.exept.de/transfer/h-expecco-22.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 from platform-tools 33.0.2
:''* We added the capability'' chromedriverStartTimeout ''to Appium, to get a timeout earlier, if Chromedriver cannot be initialized. (see [[#startChromedriverTimeout|Problems and Solutions]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Contains Appium version 1.22.0, Node still is version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Only minor changes compared to the previous version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Compared to the previous version, Appium was updated to version 1.16.0-rc.1 and node 12 is used.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:This installs Appium in the version 1.12.0 and now additionally contains build-tools in the version 28.0.3 in the android-sdk. Apart from this, it is the same as the previous version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:This installs Appium in the version 1.8.1. In addition, an installation of ''Android Debug Bridge'' and ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) is offered. This covers drivers for a broad range of Android devices, and you won't have to install an individual driver for each device. A '''JDK is not contained anymore (due to a change in Oracle's license terms)''', you have to download it on your own, e.g. from [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: same procedure as for expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:This installs a Java JDK Version 8, android-sdk and Appium Version 1.6.4. The supplement also offers a universal adb driver ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]). This driver supports a wide range of Android Devise, and avoids the need to search for individual device-specific drivers.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:It installs a Java JDK version 8, android-sdk and Appium version 1.4.16. During the installation the graphical user interface of Appium is started, you can close this window immediately. The supplement also offers a universal adb driver (ClockworkMod). This combines drivers for a wide range of Android devices so that you do not have to search for and install a separate driver for each device.

If expecco has to use mobile devices that are connected to another computer, you have to start an Appium server there. You can do this by using the file <code>appium_standalone.cmd</code>. The server is then started on default port 4723. If you want to use a different port number, start the server with

appium_standalone.cmd -p <portnummer>

The server is ready, as soon as the line
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
is displayed, where you can read the used port number at the end.

If your Android device is connected to a remote machine,
you may want to see the live screen locally using a tool like
[https://github.com/Genymobile/scrcpy scrcpy].

When Appium is started for the first time – either standalone or by expecco – it may happen that the Windows firewall blocks access to the node server. Allow the access or Appium cannot be started.

== Mac OS ==
Note: the following can be ignored if you do not plan to test iOS (iPhone) devices. The Mac setup is not needed for Android devices.

=== Xcode ===
Automation with iOS devices needs [https://developer.apple.com/xcode/ Xcode]. You can install it from the App Store. Please make sure that the version matches the tested iOS versions.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
This table is only a simplified overview, better see [https://xcodereleases.com/ Xcode releases] or [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode versions] for the exact versions. For new iOS minor versions, there is usually also a new release of Xcode, e.g. for iOS 10.2 you need at least Xcode 8.2, for iOS 10.3 at least Xcode 8.3, etc. So if you are upgrading to a newer iOS version, you will usually need a newer Xcode version as well. Newer versions of Xcode may not run on older operating systems, which in turn may require an operating system upgrade. If you also want to test older iOS versions, it can be useful to install the corresponding Xcode versions in parallel.

=== Appium ===
You can install Appium either as command-line tool or use it with [https://github.com/appium/appium-desktop Appium Desktop], which provides a GUI to start the server. Meanwhile there is also Appium 2.0, which is not tested with expecco yet and therefore not recommended to use.

==== Appium Desktop ====
Download the newest version of [https://github.com/appium/appium-desktop/releases/ Appium Desktop]. For the Mac, it is best to take the dmg file and install it to the applications. When starting ''Appium Server GUI'' you will probably get the error message, that it is not possible for security reasons. In this case, open the context menu of the app file (right click or Ctrl + click) and choose ''Open'' there. Then confirm that you really want to open the application. From now on you can open the application normally.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Since Xcode 14 there are problems with signing the WebDriverAgent, which Appium loads on the device for the automation. This means that no connection is possible with version 1.22.3-4 of Appium Desktop. In newer versions of WebDriverAgent, this problem is solved, but currently there is no version of Appium Desktop using such a new version (as of November 2022). However, you can manually download a new version (e.g. 4.10.2) and replace the files in Appium. To do this, download one of the two archive files (zip or tar.gz) containing the source code from the [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent download page]. Then open and extract this file. Copy the contents of the folder ''WebDriverAgent-4.10.2' to

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

If you navigate there by Finder, make a context click (right click or Ctrl + click) on the application and choose ''Show Package Contents'' from the menu. Replace all files that are already present with the same name.

==== Install Appium using npm ====
You can install Appium using npm (Node Package Manager) as well. To do this, you have to install node/npm first. This can be done using [https://github.com/nvm-sh/nvm nvm] (Node Version Manager), which you can get on Github. If the following installation instructions should not work for you, you will find detailed information in the [https://github.com/nvm-sh/nvm#readme Readme] there.

Open a Terminal window. Then clone the Github repository of nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
and load it
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Then execute
command -v nvm
to see if it works. It should print ''nvm''. If there is no response, execute
touch ~/.zshrc
and try again.

Now you can install node with the following command.
nvm install 16.15.1
As there are problems installing Appium using the newest version of node, we recommend this version.

After node is installed, you can use it to install Appium:
npm install -g appium

The Appium server now simply can be started with the command
appium
The output will then be written directly to the terminal.

This version also has problems with signing the WebDriverAgent, like explained in [[#Appium_Desktop | Appium Desktop]]. Therefore download a newer version of WebDriverAgent in this case as well and replace the old files. You will find them at
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
We provide older versions of Appium via the Mobile Testing Supplement for Mac OS, with which you can easily install it:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.2)]
:Contains Appium version 1.18.3 and uses node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.0)]
:Only a few changes compared to the previous version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.98)]
:Appium is updated to version 1.16.0-rc.1 and node 12 is used.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.96)]
:This version contains Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.94)]
:This version contains Appium 1.8.0.

* expecco 2.11:[http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.0.94)]
:This version contains Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement for Mac OS]
:Diese Version entält Appium 1.4.16.

After you have downloaded the supplement, you can move it to a directory of your choice (e.g. your home directory) and unpack it there. A suitable command in a shell could look like this, adjust the version number accordingly:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

If your default Xcode installation is the one you want to use, you can start Appium directly from the file in the ''bin'' directory with the appropriate version number:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

If you want to use another Xcode than the one configured as default, you have to tell Appium the corresponding path by using the environment variable ''DEVELOPER_DIR''. For example, if you have installed Xcode in ''/Applications/Xcode-11.3.app'', you can start Appium this way:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

To find out what is set as the default Xcode installation on your system, use this command:

xcode-select -p

If Appium cannot find your Xcode installation, a message like this appears:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
In such a case, restart Appium by specifying a valid ''DEVELOPER_DIR''.

==== Signing WebDriverAgent ====
For automation, Appium installs an App called WebDriverAgent on the device and therefore has to be able to sign it. You need an Apple account and a respective certificate for this. For evaluation you can use a free account. This has the disadvantage that created profiles are only valid for one week and must be recreated afterwards. Also be careful when sharing the account, as certificates may be revoked or invalidated by automatic generation. As a result, apps that have already been signed can no longer be used.

If you already have a respective certificate and its associated private key in your keychain on the Mac, you can have the WebDriverAgent automatically signed. If not, it is recommended to set and manage the signing using Xcode.

First, connect the device you want to use to your Mac via USB. Make sure both the Mac and the device are in the same network or there will be problems when connection with Appium. Start Xcode and open ''Preferences''. Go to the Accounts page and create an entry with your account. You can then click on ''Manage Certificates...'' to see the certificates that belong to that account. To run tests, you need an iOS Development Certificate and the associated private key. If you do not already have one, create one. If you already have one, but it is not in your keychain (indicated by "Not in Keychain"), you can import it. You can do that by the [https://support.apple.com/en-us/guide/keychain-access/welcome/mac keychain access] on your Mac, if you have exported it previously from the keychain, where it is stored. The certificate with the associated key should be in the keychain ''Login''. It can be exported from there as PKCS#12 file (typical ending .p12). To import a certificate into your keychain, select the option ''Import objects'' from the ''File'' menu. If you don't know where the certificate is stored, you can also revoke it in Xcode and recreate it in your keychain. However, only do this if you know that the old certificate is no longer in use because it can no longer be used afterwards. Now the keychain should contain an iOS development certificate.


Now open the WebDriverAgent project in Xcode. If you have installed the Mobile Testing Supplement, you will find it in this directory at
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
If you have installed Appium Desktop, you will find it at
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''

You can use the Finder to navigate to the Xcode project file and open it by double clicking. Note, that you have to perform a context click (right click or Ctrl + click) on the Appium Server GUI app and select ''Show Package Contents'' in the menu, to get to its subdirectory.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Select ''WebDriverAgentLib'' and the page ''Signing & Capabilities''. In the section ''Signing'' set the option ''Automatically manage signing'' and then select a team. Now switch to ''WebDriverAgentRunner'' and do the same there.

By setting the team, the errors showing up for WebDriverAgentRunner should disappear. If Xcode should not be able to create a Provisioning Profile matching the Bundle ID ''com.facebook.WebDriverAgentRunner'', you can edit the latter so that it fits your certificate. After that you can quit Xcode or you can, like explained further below, directly start the build in Xcode, so the project will be already built when Appium wants to use it.

If you now connect to your device from expecco, the WebDriverAgent will be installed and started on it and then switch to the app to be tested. You may still have to trust the execution of the WebDriverAgent on the device. It maybe a sign that you have to do this, if the app WebDriverAgent first appears on the device and tries to start, but then is uninstalled again. To trust the execution, open the settings during the connection setup on the device and then the entry ''Device management'' under ''General''. This entry is only visible if a developer app is installed on the device. You may therefore have to wait until the WebDriverAgent is installed before the entry appears. Select the entry of your Apple account and trust it. Since the WebDriverAgent will be uninstalled again if the start did not work, you have to do this during the connection setup. If this is too hectic for you, you can also execute the following code:

xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

or
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

This installs the WebDriverAgent on the device without deleting it again.

If there are problems while installing the WebDriverAgent, you can also try and start the build in Xcode. Make sure the right target ''WebDriverAgent'' is selected. Error messages in Xcode might indicate easier what the problem is about. Sometimes it even helps to try for a second time, if it took too long for the first time and got aborted. It may occur, that you are asked several times during the build to enter the password for the keychain.

[[Datei:WebDriverAgentCodesign.png]]

Read also the documentation of Appium on [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Setting up tests with iOS devices]. Refer to the [https://support.apple.com/en-us/HT204460 Apple documentation] for details on installing and trusting of apps.

Once the WebDriverAgent is installed on the device, it will be reused for later connections und connecting should work faster. The signed version is then already on your Mac as well and doesn't have to be built again. This should speed up the connect with other devices as well. If you know, that the connect has to build and sign the WebDriverAgent first, it is advisable to set the capability ''wdaLaunchTimeout''. This timeout specifies how long Appium waits for the WebDriverAgents to start up on the device and is per default set to 60000 ms. Building often takes a little longer than one minute, so the connect attempt will be canceled. A value of 120000 will be more reliable here.

== Plugin Configuration ==
Before you start, please check the settings of the Mobile Testing Plugin and adjust them if necessary. Select the menu item "''Extras''" → "''Settings''" → "''Extensions''" → "''Mobile Testing''" (see fig.). By default, these paths are found automatically (1). To adjust a path manually, deactivate the corresponding check mark at the right. You'll see a drop-down list with some paths to choose from. If an entered path is wrong or cannot be found, the field is marked red and a message appears. Make sure that all paths are specified correctly.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Plugin Configuration]]

*'''appium''': Enter the path to the executable file with which Appium can be started in the command line. Under Windows this file will usually be called "<code>appium.cmd</code>". This path is used when expecco starts an Appium server.
*'''node''': Enter the path to the executable that starts Node (also called (also called "Node.js"). This path is passed to Appium when a server is started so that Appium can find it independently of the PATH variable. Under Windows this file is usually called "<code>node.exe</code>".
*'''JAVA_HOME''': Enter the path to a JDK (Java Development Kit)here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable. To specify which Java should be used by expecco, set this path in the Java Bridge settings.
*'''ANDROID_HOME''': Enter the path to an Android SDK here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable.
*'''adb''': The path to the adb command. Under Windows the file is called "<code>adb.exe</code>". This file is used by expecco, for example, to get the list of connected devices. This path should be selected automatically, if the command is found in the ANDROID_HOME directory. This is also used by Appium. If expecco and Appium use different versions of adb, conflicts may occur.
*'''android.bat''': This file is only needed to start the AVD and the SDK Manager, which deal with phone emulators. The file in the ANDROID_HOME directory will be selected automatically, if present there.
*'''aapt''': The path to the "aapt" command here. Under Windows this file is called "<code>aapt.exe</code>". expecco uses "aapt" only in the connection editor to read the package and activities of an "apk" file. The file in the ANDROID_HOME directory will be selected automatically, if present there.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | JDK Configuration]]

Starting with expecco 2.11, there is an additional field called ''Team ID''. If you run iOS tests, enter the Team ID of your certificate here. This is used for every iOS connection, unless you change the value in the connection settings in individual cases. For information on how to obtain the team ID, please refer to the section on [[#Signing| signing]] for installations on Mac OS. With expecco 2.10 and older, you can only enter the Team ID as capability for each connection setting separately. However, you must use the [[#Extended_View|extended view]] to do this. Enter the capability ''xcodeOrgId'' here and set the Team ID of the certificate as value.

The server address setting at the bottom of the page refers to the behavior of the connection editor. It checks at the end whether the server address ends in ''/wd/hub'' as this is the usual form. If not, a dialog asks how to react. The defined behavior can be viewed and changed here.

Also switch to the entry ''Java Bridge'' (see figure). Here you have to specify the path to your Java installation, which is used by expecco. Enter a JDK here. If you want to use the one from the Mobile Testing Supplement under Windows, the path is
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
You can also use the system settings.

== Prepare Android Device ==
If you connect an Android device under Windows, you may still need an adb driver for the device. You can usually find a suitable driver on the manufacturer's website. If you have installed the universal driver from the Mobile Testing Supplement, everything should already work for most devices. In some cases, Windows will automatically try to install a driver when you connect the device for the first time. 
'''Attention''': Before you can control a mobile device with the Appium plugin, you have to allow this debugging!

For Android devices, you can find this option in the settings under ''[https://developer.android.com/studio/debug/dev-options Developer Options]'' called ''USB-Debugging''. If the developer options are not displayed, you can unlock them by tapping Build Number seven times in About the Phone.

Also enable the ''Stay awake'' feature to prevent the device from turning off the screen during test creation or execution.

For security reasons, USB debugging must be allowed for each computer individually. When connecting the device to the PC via USB, you must agree to the connection on the device. If you haven't done this for your computer yet, but no corresponding dialog appears on the device, it may help to unplug and reconnect the device. This can happen especially if you have installed the ADB driver while the device was already connected via USB. If this doesn't help either, open the notifications by dragging them from the top of the screen. There you will find the USB connection and you can open the options. Select another type of connection; usually MTP or PTP should work.

You can also test on an emulator. It does not need to be prepared separately, as it is already designed for USB debugging. It is even possible to start an emulator at the beginning of the test.

To check if a device you have connected to your computer can be used, open the [[#Connection_Editor|connection editor]]. The device should be displayed there.

=== Connection via WLAN ===
It is possible to connect to Android devices via Wireless LAN. For devices using Android 11 or newer, this can be done wirelessly, else you have to connect initially via USB. Since expecco 22.1, WiFi connections can be established using the [[Mobile_Testing_Plugin/en#Connection_Editor|Connection Editor]]. It is also possible to do this using a command window.
==== Wireless Connect (Android 11) ====
In the developer options of your device, enable wireless debugging and open its options. You initially have to pair your machine with the device. To do this, choose "''Pair device with pairing code''" to get a pairing code and an IP address with port. Then open a command window (terminal window) on your machine and enter:
<nowiki>adb pair <Device IP Address>:<Pairing Port></nowiki>
where <tt><Device IP Address>:<Pairing Port></tt> is the IP address and port as shown on the device. After that, you will be asked for the pairing code. If everything went right, the popup on the device should have closed and your machine is added to the list of paired devices. Then enter at the command window:
<nowiki>adb connect <Device IP Address>:<Debugging Port></nowiki>
The IP address is the same as for pairing, but the port is different. Both are shown as IP address & Port on the device. The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted. Restarting the device often disables wireless debugging and the used port is changed. The pairing, however, is permanent and has not to be done again the next time you connect.
==== Start via USB ====
First, connect your device via USB. Then open a command window (terminal window) and enter:
<nowiki>adb tcpip 5555</nowiki>
The device listens for a TCP/IP connection on port 5555. If you have several devices connected or emulators running, you have to specify which device you mean. Enter in this case:
<nowiki>adb devices -l</nowiki>
to get a list of all devices, where the first column gives the device's ID.
Then, enter:
<nowiki>adb -s <deviceID> tcpip 5555</nowiki>
with the device identification of the desired device. You can now disconnect the USB connection. Now you have to find out the IP address of your device. You can usually find it somewhere in the device's settings, for example in the Status or WLAN settings of the phone. Then type in:
<nowiki>adb connect <IP address of device></nowiki>
The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> again or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted.

== Preparing an iOS-Device and App ==
Control of iOS devices is only possible via a Mac. Please also read the section [[#Mac_OS|Installation under Mac OS]].

Before you can control a mobile device with the Mobile Testing Plugin, you must allow debugging for iOS devices with iOS 8 or higher. Activate the option "''Enable UI Automation''" under the "''Developer''" menu in the device settings. If you cannot find the "''Developer''" entry in the settings, proceed as follows: Connect the device to the Mac via USB. If necessary, you must still agree to the connection on the device. Start Xcode and then select "''Devices''" from the menu bar at the top of the screen in the "''Window''" menu. A window opens in which a list of the connected devices is displayed. Select your device there. Then the entry "''Developer''" should appear in the settings on the device. You may have to exit the settings and restart.

[[Datei:Alert.png | thumb | 270px | Alert unter iOS]]
It is not possible to establish a connection to the device as long as it shows certain alerts. Such an alert may appear if FaceTime is activated (by displaying a message about SMS charges as shown in the screenshot). Be sure to configure the device so that it does not show such alerts when idle.

=== expecco 2.11 and later ===
You can test any app which is executable or already installed on the device used. If the app is available as a development build, the UDID of the device must be stored in the app. In any case, the WebDriverAgent must be signed for the device. Please read the section about [[#Signing|signing]] under Mac OS.

If you want to use the Home button in a test, you must activate "AssistiveTouch" on the device. You will find this option in the settings under "''General''" > "''Operating Help''" > "''AssistiveTouch''". Then place the menu in the middle of the upper edge of the screen. You can then record pressing the Home button with the corresponding menu entry in the recorder or use the "''Press Home Button''" block directly.

=== expecco 2.10 ===
The app you want to use must be available as a development build. The UDID of the device must also be stored in the app.

=== Sign the development build ===
A development build of an app is only allowed for a limited number of devices and cannot be started on other devices. However, it is possible to exchange the certificate and the usable devices in a development build.

* Evaluation with demo app of eXept:
:We will be happy to provide you with a demo app which is available as a development build and which we can sign for your device. Please send the UDID of your device to your eXept contact person. How to determine the UDID of your device is described in the following section.

* Using your own app for your test device:
:If you receive a development build (IPA file) from the app developers that is approved for your test device, you can use it directly. To do this, you must tell the developers the UDID of your device so they can enter it. '''You can use Xcode to read the UDID of a device'''. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window opens in which a list of the connected devices is displayed. Select your device and search for the ''Identifier'' entry in Properties. The UDID is a 40-digit hexadecimal number.

* Externally developed app for your test device:
:You can also re-sign apps to make them run on other devices. However, this process is complicated and requires access to an Apple Developer account. A documentation on the procedure is currently in preparation.

:For the evaluation we will gladly support you with the re-signing of your app..


For more information about using iOS devices, see also the
[http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Appium documentation].

=== Native iOS-Apps ===
You can also use apps that are already natively present on the device. To do this, you must know their bundle ID and then enter it in the connection settings. Here is a small selection of common apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

You can find further Bundle-IDs [https://github.com/joeblau/apple-bundle-identifiers here].

= Examples =
In the demo test suites for expecco you will also find examples for tests with the Mobile Testing Plugin. To do this, select the option "''Example from File''" on the start screen and open the folder named "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
The test suite contains two simple test plans: "''Simple CalculatorTest''" and "''Complex Calculator and Messaging Test''". Both tests use an Android emulator, which you must start before starting. The apps used in the test are part of the basic equipment of the emulator and therefore no longer need to be installed. Since the apps may differ under every Android version, it is important that your emulator runs under Android 6.0. In addition, the language must be set to English.

; Simple CalculatorTest
: This test connects to the calculator and enters the formula ''2+3''. The result of the calculator is compared with the expected value ''5''.

; Complex Calculator and Messaging Test
: This test connects to the calculator and then opens the message service. There it waits for an incoming message from the number ''15555215556'', in which a formula to be calculated is sent. The message is generated before via a socket at the emulator. When the message arrives, it is opened by the test and its contents are read. Then the calculator is opened again, the received formula is entered and the result is read. The test then switches back to the message service and sends the result as an answer.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
These are part of the tutorial for the Mobile Testing Plugin. The included test case is incomplete and will be added during the tutorial. Please read the section [[#Tutorial|Tutorial]].

= Tutorial =
There is a tutorial describing the basic procedure for creating tests with the Mobile Testing Plugin. It is based on a supplied example consisting of a simple app and an expecco test suite.

You find it on the page [[Mobile_Testing_Tutorial/en|Mobile Testing Tutorial]] in two versions for Android and iOS devices.
*  [[Mobile_Testing_Tutorial/en#First_steps_with_Android|First steps with Android]]
*  [[Mobile_Testing_Tutorial/en#First_steps_with_iOS|First steps with iOS]]

= Dialogs of the Mobile Testing Plugin =
== Connection Editor ==
You can use the Connection Editor to quickly define, change, or establish connections. Depending on the task, the dialog has small differences and is opened differently:
*If you want to establish a connection, access the dialog in the GUI browser by clicking on ''Connect'' and then selecting ''Mobile Testing''.
*To change or copy an existing connection in the GUI browser, select it, right-click and select ''Edit Connection'' or ''Copy Connection'' from the context menu.
*If you do not want to create connection settings for the GUI browser but for use in a test, choose ''Create Connection Settings'' from the Mobile Testing Plugin menu.... This only allows you to create the settings for a connection without creating a connection in the GUI browser.

The Connection Editor menu has several buttons, some of which are only visible when creating connection settings:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#''Delete Settings'': Resets all entries. (Only visible when creating settings.)
#''Load settings from file'': Allows to open a saved settings file (*.csf). Its settings are transferred to the dialog. Entries already made without conflict are retained.
#''Load settings from attachment'': Allows you to open an attachment with connection settings from an open project. These settings are applied to the dialog. Entries already made without conflict are retained.
#''Save settings to file'' and
#''Save settings to attachment'': Here you can save the entered settings to a file (*.csf) or create them as an attachment in an open project. Both options have a delayed menu in which you can choose to save only a certain part of the settings. (Only visible when creating settings.)
#''Advanced View'': Allows you to switch to the advanced view to make additional settings. Read more about this at the end of this chapter. (Only visible when creating settings.)
#''Help'': A help text for the respective step is shown or hidden on the right side.

The dialog is divided into three steps. In the first step you select the device you want to use, in the second step you select which App should be used and in the last step the settings for the Appium server are made.

===Step 1: Select Device ===
In the upper part you will see a list of all connected Appium devices that are detected. With the checkbox below you can hide devices that are detected but not ready. If you want to enter a device that is not connected, you can create it with the corresponding button ''Enter Android device'' or ''Enter iOS device''. However, you need to know the required properties of your device. The device is then created in a second device list and can be selected there. If no list with connected elements can be displayed, various messages are displayed instead:
*No devices found
*:expecco could not find any Android devices.
*:To automatically configure a connection to a device, make sure
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*No available devices found
*:expecco could not find any available Android devices. But not available ones were found, e.g. with the status "unauthorized".
*:To configure a connection to a device automatically, make sure that
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*:To view unavailable devices, enable this option below.
*Connection lost
*:expecco has lost the connection to the adb server. Try to re-establish the connection by clicking on the button.
*Connection failed
*:expecco could not connect to the adb server. Possibly it is not running or the specified path is not correct.
*:Check the adb configuration in the settings and try to start the adb server and establish a connection by clicking on the button.
*Connect ...
*:expecco connects to the adb server. This may take a few seconds.
*Start adb-Server ...
*:expecco starts the adb-Server. This may take a few seconds.

With ''Next'' you get to the next step. If you enter settings for the GUI browser, this is only possible once a device has been selected.

Note on unlocking: In newer Android versions the developer options are no longer offered in the settings at first. If your Android device does not show an entry for "''Developer options''" in the settings, first select the entry "''Phone info''", then "''SoftwareVersionsInfo''" and click on the entry "''BuildVersion''" several times.

==== Manage Chromedrivers ====
If the App you want to automate uses WebViews with Chrome, Appium needs to have access to an appropriate Chromedriver. If you have selected a device in the list, you can use "''Manage Chromedrivers''" to see, which Chrome versions are installed on the device and which Chromedriver versions are provided by expecco. With this dialog you can also download required Chromedriver versions. Beware that there may be several Chrome versions on the device. An App doesn't have to use the version of the installed Chrome browser for its WebViews. The Chromedriver you use should fit your app for everything to work properly. You can also change the path to the Chromedriver in the capabilities generated at the end of the connection editor.

==== Connect WiFi Android Device ====

You can connect to Android devices using WiFi as well. In this case, the device has to be connected to ADB first, see [[Mobile_Testing_Plugin/en#Connection_via_WLAN|Connection via WLAN]]. Since expecco 22.1, the connection editor provides a dialog helping to set this up, which can be used instead of the command window. For devices using Android 11 or newer, you can pair the device with your machine here by specifying the appropriate parameters and then establish the connection by specifying the IP address and port. You can also use this to establish a wireless connection for devices that are connected via USB. When you select the corresponding device in the list, the required information is read out automatically.

Note that establishing a wireless connection is not part of the connection settings. If you want to establish a new connection with the generated settings, you must make sure that the device is connected to ADB with the specified IP address and port so that it can be found. The ADB connection will be lost if the ADB server or the device are restarted. The permission for wireless debugging is also often reset when the device is restarted and the debug port can then change. Therefore, a wireless connection must always be established manually.

===Step 2: Select App===
Here you can enter information about the app to be tested. You can decide if you want to use an app that is already installed on the device or if you want to install an app for the test. Select the appropriate tab above. Depending on whether you selected an Android or an iOS device in the previous step, the required input will change.

*'''Android'''
**''App on Device''
**:If you have selected a connected device in the first step, the packages of all installed apps are automatically retrieved and you can select from the drop-down lists. The installed apps are divided into third-party packages and system packages; select the appropriate package list. This selection does not belong to the settings, but only provides the corresponding package list. You can use the filter to further narrow down the list and then select the desired package. The activities of the selected package are also automatically retrieved and made available as a drop-down list. Select the activity you want to start. As a rule, an activity is automatically entered from the list. If you are not using a connected device, you must enter the package and the activity manually.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. If you are using a local Appium server, you can use the right button to navigate to the App installation file and enter this path. If possible, the corresponding package and the activity are also entered in the fields below. However, this entry is not necessary.

*'''iOS'''
**''App on Device''
**:Specify the bundle ID of an installed app. You can find out the IDs of the installed apps using Xcode, for example. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window will open displaying a list of connected devices. If you select your device, you will see a list of the apps you have installed in the overview.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. For the requirements of apps for real devices, please read the section [[#iOS-Ger.C3.A4t_and_App_Preparing|Preparing an iOS-Device and App]].

In the lower part you can specify whether the app should be reset or uninstalled when the connection is terminated, and whether it should be reset initially. Again, the corresponding capability is not set if you select ''(Default)''. With ''Next'' you get to the next step.

===Step 3: Server Settings===
In the last step, a list of all the capabilities that result from your entries in the previous steps is first displayed in the upper part. If you are familiar with Appium and want to set additional capabilities that are not covered by the connection editor, you can click on ''Edit'' to open the extended view. See the section below for more information.

If you enter settings for the GUI browser, you can enter the ''Connection name'' with which the connection is displayed. This is also the name under which devices can use this connection when it is established. If you leave the field blank, a name will be generated. If the box "''Managed by expecco''" is checked, expecco will start a local Appium server on a free port, or use a free server that has already been started. To use your own server, turn this feature off and enter the appropriate address. You will get the local default address and already used addresses to choose from.

In older expecco versions the box is labeled "''Start on demand''". In this case, you must also enter an address if you want expecco to start the server. expecco then tries to start an Appium server at the given address when connecting, if none is running there yet. This server will then also be shut down when the connection is terminated. This only works for local addresses. Make sure that you only use port numbers that are free. It is best to only use odd port numbers from the standard port 4723. The following port number is also used when establishing a connection, which could otherwise lead to conflicts.

Depending on how you opened the dialog, there are now different buttons to close it. In any case you have the option to save. This opens a dialog where you can either select an open project to save the settings there as an attachment, or choose to save it to a file that you can then specify. Saving does not close the dialog, allowing you to select another option.

If you have opened the editor for establishing a connection, you can finally click on ''Connect'' or ''Start and connect server'', depending on whether the check mark for server start is set. For changing or copying a connection in the GUI Browser, this option is called ''Apply'', since in this case only the connection entry is changed or created, but the connection setup is not started. If necessary, you can do this afterwards via the context menu. If you have changed capabilities of an existing connection, a dialog then prompts you to decide whether these changes should be applied directly by closing the connection and establishing the new connection or not. In this case, the changes only take effect after you reestablish the connection.

To use the connection editor, also read the corresponding section in the respective tutorial in step 1. (Android: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo|Run Demo]], iOS: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo_2|Run Demo]]).

===Extended View===
The extended view of the connection editor can be obtained either by clicking on ''Edit'' in the third step or at any time via the corresponding menu item if you have started the editor via the plugin menu. This view displays a list of all configured Appium Capabilities. You can add, change or remove further entries to this list. To add a capability, select it from the drop-down list of the input field. In this list all known capabilities are sorted into the categories ''Common'', ''Android'' and ''iOS''. If you have selected a capability, a short information text is displayed. You can also enter a capability manually in the field. Then click on ''Add'' to add the capability to the list. There you can set the value in the right column. To delete an entry, select it and click on ''Remove''. With ''Back'' you leave the extended view.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Running Appium Servers ==
In the menu of the Mobile Testing Plugin you will find the entry ''Appium-Server...''. This opens a window with an overview of all Appium servers started by expecco and on which port they are running. By clicking on the icon in the column ''Show Log'' you can view the logfile of the corresponding server. This is deleted when the server is shut down. With the icons in the column ''Exit'' the corresponding server can be terminated. However, this is prevented if expecco still has an open connection via this server. The rightmost column shows for which connection the server is in use. If it reads ''<idle>'', the server is currently not used by expecco.

[[Datei:MobileTestingAppiumServer.png]]

When opening the editor to start an Appium connection, an Appium server is started immediately to speed up the connection process. For this purpose, expecco always keeps one idle running Appium server. Additional running servers however, which are not in use anymore, will be terminated automatically after a while.

In the menu of the Mobile Testing Plugin you will also find the entry ''Close all Connections and Servers''. This is intended for cases where connections or servers cannot be terminated in any other way. If possible, always terminate connections in the GUI browser or by executing a corresponding block. Servers that you have started in the server overview should be terminated there; servers that were started with a connection are automatically terminated with this connection.

Note that only servers started and managed by expecco are listed in the overview. Possible other Appium servers that were started in a different way are not recognized.

== Recorder ==
If the GUI browser is connected to a device, the integrated recorder can be used to record a test section with that device. To start the recorder, select the appropriate connection in the GUI browser and click the Record button. A new window opens for the recorder. The recorded actions are created in the GUI browser work area. It is therefore possible to edit the recorded data in parallel.

[[Datei:MobileTestingRecorder.png|caption|]]

====Components of the Recorder Window====
#'''Continue/Pause Recording''': You can pause the recording by clicking the right icon. You will then see a large pause sign in the view. All actions that you perform now in the recorder are executed, but no blocks are recorded. You can switch back to normal recording mode by clicking the left icon.
#'''Stop Recording''': Stops the recording and closes the recorder window.
#'''Update''': Gets the current image and element tree from the device. This is necessary if the device takes longer to execute an action or if something changes without being triggered by the recorder. Since expecco 21.2, there is an additional submenu here that can be used to enable automatic update by checking for changes in the background (see also ''Automatic Update'' further below).
#'''Follow Mouse''': Select the element under the mouse pointer in the GUI browser.
#'''Element Highlighting''': The element under the mouse is outlined in red.
#'''Show Elements''': Show the borders of all elements in the view.
#'''Tools''': Selection, which tool is used for recording. The selected action is triggered with each click on the view. The following actions are available:
#*Element Actions:
#**Click: Short click on the element under cursor. To determine more precisely which element is used, use the Follow Mouse or Element Highlighting function.
#**Tap with Duration (Element): Similar to click, except that the duration of the click will be recorded as well. This allows the recording of long clicks.
#**Tap with Position (Element): Similar to click, but additionally records the position inside the element. The position can be recorded relative to the element size or, when pressing Ctrl while clicking, as absolute position from the upper left corner of the element.
#**Set Text: Allows to set the text of an input field.
#**Clear Text: Clears the text of an input field.
#*Device Actions:
#**Tap (Screen): Triggers a click at the screen position.
#**Tap with Duration (Screen): Triggers a click at the screen position, which also considers the duration.
#**Swipe: Swipe in a straight line from the point where you press the mouse button until you release it. The duration is also recorded.
#:Please note for this actions that the result may differ on different devices, e.g. with different screen resolutions.
#*Test Flow Blocks
#**Check Attribute: Compares the value of a specified attribute of the element with a predefined value. The result triggers the corresponding output.
#**Assert Attribut: Compares the value of a specified attribute of the element with a predefined value. If the values are not equal, the test fails.
#**Get Attribute: Gets the current value of a specified attribute of the element.
#*Auto
#:If the Auto tool is selected, you can use all actions by specific input methods: ''Click'', ''Tap Element'' and ''Swipe'' still work by clicking, but are distinguished by the duration and movement of the cursor. To trigger a ''Tap'', hold down Ctrl while clicking. The remaining actions are available in a context menu by right-clicking on the element.
#'''Context Actions''': Here you can record actions concerning contexts:
#*Switch to Context: Shows a list of all currently available contexts and you can select to which one you want to switch.
#*Get Current Context: Gets the handle of the current context.
#*Get Context Handles: Gets a list of all currently available contexts.
#'''Softkeys''': Only for Android. Simulates pressing the buttons Back, Home, Menu and Power.
#'''Home Button''': Only for iOS since expecco 2.11. Allows pressing the Home button.Prior to expecco 19.2, it only works if AssistiveTouch is activated and the menu is located in the middle of the upper screen border. From expecco 19.2 on, the function no longer uses AssistiveTouch.
#'''Help''': Opens this online documentation on the general page about [[GuiBrowser_Recorder/en|GUI Browser recorders]].
#'''View''': Shows a screenshot of the device. Actions are triggerd by mouse depending on the selected tool. If a new action can be recorded, the window has a green frame, else it is red.
#'''Resize Window to Image''': Resizes the recorder window so that the screenshot can be displayed completely.
#'''Resize Image to Window''': Scales the screenshot to a size that makes use of the full size of the window.
#'''Adjust Display''': Opens a dialog to adjust the displayed image, if expecco does not show it right. You can correct the scaling or rotate the image by 90°.
#'''Correct Orientation''': Corrects the image if it is upside down. Using the arrow to the right, the image can also be rotated by 90°, if this should ever be necessary. Since expecco 19.1 you find this functionality under ''Adjust Display''. The orientation of the image is irrelevant for the functionality of the recorder, it only works on the elements it receives.
#'''Scaling''': Changes the scaling of the screenshots.
#'''Messages''': Shows the path of the current selected element or other messages. It has a context menu to show a list of previous messages.

====Usage====
Each click in the window triggers an action and is recorded in the workspace of the GUI browser. There you can run, edit, or create a new block from what you have recorded. You find the actions to trigger softkeys directly in the menu bar (see above). To record actions on elements, either change the selection of the tool in the menu bar (see above) and then click on the element or select the corresponding action from the context menu by right-clicking on the corresponding element. For text input it is also possible to place the cursor over the element and enter the text. This opens the input dialog for this action. On how to use the recorder, see also step 2 in the tutorial ([[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_Block_with_the_Recorder|Android]] resp. [[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_block_with_the_Recorder_2|iOS]]).

====Hide elements====
Since expecco 21.2 it is also possible to hide the selected element in the recorder from the context menu. This means that this element cannot be selected from now on. This function is useful for ignoring elements that are in the foreground to be able to access elements below them. To undo this state, you have to find the corresponding element in the tree of the GUI browser, which also has such an entry in the context menu.

====Automatic Update====
The recorder doesn't show a live image of the device, but only a snapshot. Therefore an update is needed after changes to match what is displayed on the device. The recorder updates automatically after executing an action. Since expecco 20.2 there are further automatic updates possible. You can enable the, in the menu "View".

One option is, to check after an action has been executed, if there are further changes after the first update. If so, a second update is triggered. This shall fix the problem, that the recorder is not up to date after an action, because the update has been done too early.

The second option is to enable a periodical update. After a set interval the recorder is automatically updated if there are changes. Thereby the recorder view is mostly up to date, but this causes an overhead regarding the communication to the device.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid Apps and WebViews =
'''!!! IMPORTANT NOTICE - If you have problems switching to the webview, please set the "Default Application - Browser App" in Android Settings to "Chrome" !!!'''

Hybrid apps contain platform native elements as well as other elements that are integrated in a WebView. These elements can also be used, but you first have to switch to the corresponding context. With the block ''Get Current Context'' you get the current context. Initially this is ''NATIVE_APP'', i.e. the context of the native elements. With the block ''Get Context Handles'' you get a collection of all existing contexts. If there is a WebView context, it is called ''WEBVIEW_1'' or ''WEBVIEW_<package>'' with the package of the WebView. Several WebView contexts are also possible. For each WebView context, there is a corresponding WebView element in the native context. You can use the ''Switch to Context'' block to switch to such a context and from now on only have access to the elements in this context.

In the GUI browser, the existing contexts are displayed at the top of the tree as well as the tree of a context is inserted below the corresponding WebView element.

=Customizing XPath using the GUI Browser=
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen ''GTIN-13 (EAN-13)'' und ''Verify'', das Eingabefeld der Zahl ''4006381333986'' und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des GTIN-13-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch ''Pfad überprüfen'' (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit ''Verify Path: OK'' (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit * zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert ''GTIN-13 (EAN-13)'' besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer ''hierarchy'' (für iOS wäre es ''AppiumAUT''), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix ''android.widget.'', das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend ''XCUIElementType'' am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. ''FrameLayout'' ist ein Kindelement von ''hierarchy'', ''LinearLayout'' ist ein Kind von ''FrameLayout'' usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element ''hierarchy'' beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben ''TextView''-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ ''Button'' gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut ''resource-id''. Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut ''name'' verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem @ eingeleitet und der Wert mit einem = in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter ''Test'' eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf ''Lauf''. Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu ''Eigenschaften'', wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

=Problems and Solutions=
== Locators depend on the version or are variable ==
In this case consider to either store the locators (xPath) in a variable or to define a locator mapping inside a screenplay attachment. It is also possible to store just parts of an locator (e.g. locator path of a parent or attribute value) in a variable and add them in the freeze value of the locator pin by "''$(varName)''".

== Invisible UI Elements ==
Note that the [[#Recorder|Recorder]] also considers items that you cannot see on the screen. Therefore, turn on element highlighting or use the follow mouse function and the element tree in the GUI browser to determine if the correct element is used. It can happen, that invisible elements are in front of other elements and cover them, so that the desired element cannot be selected in the recorder. See section [[#Hide_elements|Hide elements]] for a solution to this.

==''org.openqa.selenium.StaleElementReferenceException''==
The error <code>org.openqa.selenium.StaleElementReferenceException</code> occurs whenever an element is used that is no longer there. If that happens during your test and the element should have been there, try using the locator (xPath) instead to fetch the element again.

In some cases this error can also occur even if you already use a locator at the action block. This is because the locator is always resolved first and the corresponding element is fetched and the action is then executed with this element. If the app refreshes the element exactly between the resolving and fetching part and the execution, creating a new element, this error occurs. If it happens at a specific point in your test, your best option is to catch the error and retry.

== iOS: Cable not certified ==
In some cases, when connecting an iOS device via USB, a message appears indicating that the cable used is not certified. In this case, replacing the respective cable is the only solution.

== iOS: Alerts when connecting ==
Make sure that no alerts are open when connecting to an iOS device. Otherwise the connection will fail because the app cannot be brought to the foreground. See also [[#Preparing_an_iOS-Device_and_App|Preparing an iOS-Device and App]].

== iOS: .ipa cannot be installed ==
Note that on iOS simulators no ''.ipa'' files can be installed but only ''.app'' files.

==iOS: First Connect is not working==
If there is not already a signed build of the WebDriverAgent on your Mac, it has to be created during the first connect. Usually, this can take a little longer than one minute. Per default Appium uses a timeout of 60000 ms to wait for the WebDriverAgent to start on the device, so the connect will be canceled in that case. You can set this timeout with the capability ''wdaLaunchTimeout'', e.g. to ''120000''.

Moreover, the signing settings have to be correct. In our experience, the most reliable solution is to set automatic signing in the WebDriverAgent Xcode project an selecting the team there. See the explanation in section [[#Signing_WebDriverAgent|Signing WebDriverAgent]] for that. In this case you should '''not''' use the capabilities ''xcodeConfigFile'' resp. ''xcodeOrgId'' and ''xcodeSigningId'', as they could cause a conflict. Caution: If you have set a Team ID in the Mobile Testing settings, expecco will automatically set this as ''xcodeOrgId''!

Pay attention to your device during the first connect. You might have to agree to the installation by entering your password. On the Mac you might need to enter the password to allow access to the key chain for signing, often several times.

== Android: Device not visible in the connect editor ==
If an Android device connected via USB does not appear in the connection editor, try changing the USB connection type. Usually MTP or PTP should work. Check again, if "USB Debugging" is enabled in the developer options on the device (these options are disabled on some devices and have to be enabled first using a trick.) See also [[#Prepare_Android_Device|Prepare Android Device]].

== Android: Truncated Elements at Bottom ==
For Android devices that automatically show and hide the navigation bar/softkeys, the recorder may cut off elements in the lower area that would be hidden by the softkeys, even if they are not displayed at this time. In this case it is advisable to set the softkeys so that they are permanently displayed.

For newer Android versions there usually is no such option. Even if the controls are visible all the time, they don't have their own space, but are on top of the content of the app. Therefore, there is an area on the lower part of the screen, which cannot be automated, because it is not counted to the active area of the app. Appium will then truncate the elements there. This area can even be larger then the needed by the controls. This is a known issue for Samsung devices with Android 11. Since the information about the size of the app area is already provided on Android level, we cannot offer a solution for this, but can only hope that the problem will be fixed by the manufacturer. You may try to get better results by setting the control to gestures, but this bears the same issue.

== Android: Test Hangs While Finding an Element==
The block ''Find Element by XPath'' and all element blocks wait until an element is present for the given path. The timeout for this can be set either directly at the block or in the environment variables. However, if the element should already be present, but the test doesn't continue anyway, the reason could be in the UIAutomator/UIAutomator2. It waits for the app to go to the idle state before it even starts to search for the element. This may take longer, if the app e.g. runs an animation in the background or executes other kinds of actions. Fetching the page source, e.g. when updating in the GUI browser or in the recorder, can also take longer for this reason. There is a default timeout of 10 seconds after which it no longer waits for the idle state. This timeout can be set in Appium (waitForIdleTimeout). If you want to change the value of this timeout, you can do this since expecco 21.2 by executing the Smalltalk code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> before the test. The timeout is given in milliseconds, so the example sets it to 2 seconds.

==Android: Updating the Tree or Switching to Webview Context takes too long==
Especially with older devices it can happen that newer Chromedriver cannot be initialized. This makes it impossible to switch to the webview context. However, this is only detected over a timeout by Appium, which is 4 minutes by default. Since expecco also tries to switch to the webview context when building the tree in the GUI browser, this can lead to very long loading times. Since there is no way to decrease this timeout in Appium, we have added a corresponding capability to the version we provide in the MobileTestingSupplement. Starting with version 1.13.1.0 of the [[#Windows|MobileTestingSupplement]], ''chromedriverStartTimeout'' can be used to set the timeout in milliseconds. The switch still doesn't work then, but expecco doesn't take as long to update the tree and the context switch module fails faster. The connection dialog adds this capability automatically starting with expecco 22.1.

== No Action on Click ==
The block to click on an element is successful, but no action was performed on the device.
:This can happen if the element is hidden by another element and therefore clicking on the element is not possible. In this case, Appium does not throw an error, but simply nothing happens. If you would like to make a click at the position of the element anyways, even if it is hidden, use the block ''Tap'' instead and pass the location of the element to it (''Get Location''). If instead you want to check before a click whether the element is hidden at this moment, try whether the properties ''Is Displayed'' or ''Is Enabled'' might help you.

== No Update After Action ==
An action was triggered on the recorder and a block has been recorded, but the recorder still shows the old image.
:The recorder doesn't show a live image of the device, but only a snapshot. After an action has been executed, the recorder will update automatically. However, it can happen, that the image has already been updated before the effects of the action are fully completed on the device. In this case you should update the recorder by hand using the icon with the blue arrows. Since expecco 20.2 you can also enable automatic updates for this case. See also the description for the [[#Recorder|recorder]].

== Attribute "clickable" is wrong ==
An element has for the attribute/property "''clickable''" the value "''false''", but is actually clickable.
:The attribute "''clickable''" has to be set explicitly by the app developer and does not affect the behavior of the app. You should generally disregard this attribute in your tests. Unfortunately, many apps exist where the programmer was "lazy" about this.

==Connecting Fails==
If the connection to the Appium server fails, you will receive an error message in expecco similar to the one shown below.

[[File:MobileTestingVerbindungsfehler.png]]

Here you can see the type of error that has occurred. Click on "''Details''" to get more information. Possible errors are:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:The specified server is not running or is not reachable. Check the server address.
*''org.openqa.selenium.WebDriverException''
:Read the message after ''Original Error'' in the first line of the details:
:*''Unknown device or simulator UDID''
::Either the device is not connected properly or the udid is not correct.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::This error can have various causes. Either the WebDriverAgent could actually not be built because the signing settings are wrong or the appropriate provisioning profile is missing. Please read the section about [[#Signing|Signing]]. It is also possible that the WebDriverAgent cannot be started on the device, for example because an alert is in the foreground or you did not trust the developer.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::The specified app cannot be installed on the iOS device because it is not entered in the app's Provisioning Profile.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.''
::The path to the app is wrong. Make sure that the file is located in the specified path on your Mac.
:*''packageAndLaunchActivityFromManifest failed.''
::The specified ''apk'' file is probably broken.
:*''Could not find app apk at [...]''
::The path to the app is wrong. Make sure that the ''apk'' file is located in the specified path.

If the error is not due to one of the causes listed above, the automation applications on the device may no longer function properly. In this case it helps to uninstall them from the mobile device. They are then automatically reinstalled the next time a connection is established.

*For iOS devices, this is the WebDriverAgent, which you can simply uninstall from the home screen. This usually solves problems caused by changing the used Mac or the Xcode version.

*For Android devices, it is the UIAutomator2; here, a problem occurs sporadically on some devices, the cause is currently unknown to us. To uninstall, on the device, navigate to "''Settings''" > "''Applications''"* and search the list for the following entries:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Click on the respective application and then on "''Uninstall''".
*''The corresponding entry may have a slightly different name on some devices.''

If this doesn't help, check the output of the Appium server. For a server started by expecco, you can find the log in the list of [[#Running_Appium_Servers|Running Appium Servers]].

==I do not have a Mac==
Maybe this site will help you: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin

2024-07-24T14:27:16Z

Matilk: /* Windows */

'''Deutsche Version''' | [[Mobile_Testing_Plugin/en|English Version]]

= Einleitung =
Mit dem ''Mobile Testing Plugin'' können Anwendungen auf Android- und iOS-Geräten getestet werden. Dabei ist es egal, ob reale mobile Endgeräte oder emulierte Geräte verwendet werden. Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests unterstützt. Zudem ist damit das Aufzeichnen von Testabläufen möglich.

Zur Verbindung mit den Geräten wird [http://appium.io/ Appium] verwendet. Appium ist ein freies Open-Source-Framework zum Testen und Automatisieren von mobilen Anwendungen.

Zur Einarbeitung in das Mobile Plugin empfehlen wir das [[Mobile_Testing_Tutorial|Tutorial]] zu bearbeiten. Dieses führt anhand eines Beispiels Schritt für Schritt durch die Erstellung eines Testfalls und erklärt die nötigen Grundlagen.

= Installation und Aufbau =
Zur Verwendung des Mobile Testing Plugins müssen Sie expecco inkl. des Plugins Mobile Testing installiert haben und Sie benötigen die entsprechenden Lizenzen. expecco kommuniziert mit den Mobilgeräten über einen Appium-Server, der entweder auf demselben Rechner wie expecco läuft, oder auf einem zweiten Rechner. Dieser muss für expecco erreichbar sein.

==Installationsübersicht==

'''Rechner, auf dem expecco läuft:'''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem Android-Geräte angeschlossen sind:'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Android SDK'', dieses erhalten Sie ebenfalls mit dem Mobile Testing Supplement''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem iOS-Geräte angeschlossen sind2):'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement für Mac OS installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Xcode ''in einer Version, die die verwendete iOS-Version unterstützt, erhältlich über den Apple App Store''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
* Apple-Entwickler-Zertifikat mit zugehörigem privaten Schlüssel ''(zum Signieren des WebDriverAgents)''
* Provisioning Profile mit den verwendeten Mobilgeräten

Je nach Aufbau können die oben genannten Rechner auch das selbe Gerät sein. expecco kann sich sowohl über das Netzwerk mit einem entfernten Appium-Server und dort angeschlossenen Mobilgeräten verbinden, als auch lokal selbst einen Appium-Server starten und diesen mit lokalen Mobilgeräten verwenden. Einige Funktionen von expecco, die die Erstellung von Testfällen erleichtern, sind jedoch nur verfügbar, wenn die Mobilgeräte am selben Rechner angeschlossen sind, auf dem auch expecco läuft. Ein möglicher Aufbau kann daher wie in folgender Abbildung aussehen:

[[Datei:MobileTestingAufbau.png | 400px]]

Im Folgenden wird die Installation von Appium und anderer nötiger Programme für Windows und Mac OS erklärt.

1): Zum Zeitpunkt der Erstellung dieses Dokuments wurden Versionen bis 11 auf Funktion verifiziert. Neuere Versionen sollten - sofern nicht grundlegende Änderungen von Oracle vorgenommen wurden, ebenfalls funktionieren.

2): Beachten Sie, dass aufgrund der Voraussetzungen (keine Anbindung an nicht-Apple Geräte verfügbar) iOS-Geräte nur von einem Mac aus angesteuert werden können. Sie benötigen also einen Mac als "Vermittler" (siehe auch unten: [[#Ich habe keinen Mac | "Ich habe keinen Mac"]])

== Windows ==
Am einfachsten installieren Sie alles mit unserem Mobile Testing Supplement1. In neueren Versionen ist allerdings aufgrund geänderter Lizenzbedingungen seitens Oracle kein JDK mehr enthalten, sodass sie dieses zusätzlich installieren müssen. Sie können natürlich Appium auch direkt installieren, um die Version zu verwenden, die Sie möchten. Um dann einen Appium-Server mit expecco starten zu können, muss allerdings eine entsprechende Batchdatei vorhanden sein und in den [[Mobile_Testing_Plugin#Konfiguration_des_Plugins|Einstellungen]] angegeben werden. Verbindungen können aber auch zu anderen laufenden Appium-Servern aufgebaut werden.
*'''expecco 24.1''': [https://download.exept.de/transfer/h-expecco-24.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.3]
:Im Vergleich zum Vorgänger aktualisierte Chromedriver Versionen.
*expecco 23.2: [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Im Vergleich zum Vorgänger aktualisierte Chromedriver Versionen.
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Gleiche Versionen wie der Vorgänger, aber der Installer erlaubt nun, Appium zum Autostart hinzuzufügen.
*expecco 22.2 und 22.1: [https://download.exept.de/transfer/h-expecco-22.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 aus platform-tools 33.0.2
:''* Wir haben Appium um die Capability'' chromedriverStartTimeout ''erweitert, um schneller einen Timeout zu bekommen, wenn der Chromedriver nicht gestartet werden kann. (siehe [[#startChromedriverTimeout|Probleme und Lösungen]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Enthält die Appium-Version 1.22.0, Node ist weiterhin in der Version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Nur kleine Änderungen im Vergleich zur vorigen Version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und node 12 verwendet.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:Dieses installiert Appium in der Version 1.12.0 und enthält nun zusätzlich build-tools der Version 28.0.3 im android-sdk. Ansonsten ist es gleich wie die vorige Version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:Dieses installiert Appium in der Version 1.8.1. Außerdem bietet das Supplement auch an, ''Android Debug Bridge'' und ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) zu installieren. Damit sind Treiber für ein breites Spektrum an Android-Geräten abgedeckt, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen. Ein '''JDK ist (aufgrund geänderter Lizenzbedingungen seitens Oracle) nicht mehr enthalten''', dieses müssen Sie selbst herunterladen, z.B. von [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: wie expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.6.4. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.4.16. Während der Installation wird die grafische Oberfläche von Appium gestartet, dieses Fenster können Sie sofort wieder schließen. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.

Wenn expecco Mobilgeräte verwenden soll, die an einem anderen Rechner angeschlossen sind, müssen Sie dort einen Appium-Server starten. Dies können Sie mit der Datei <code>appium_standalone.cmd</code> tun. Der Server wird dann mit dem Standard-Port 4723 gestartet. Falls Sie eine andere Portnummer verwenden wollen, starten Sie den Server mit

appium_standalone.cmd -p <portnummer>

Der Server ist bereit, sobald die Zeile
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
angezeigt wird, wobei Sie am Ende die verwendete Portnummer ablesen können.

Beim ersten Starten von Appium – sowohl im Standalone als auch gestartet von expecco – kann es vorkommen, dass die Windows-Firewall den Node-Server blockiert. Lassen Sie den Zugriff zu, sonst kann Appium nicht gestartet werden.

1) Sie können natürlich auch die Command Line Tools (adb, sdkmanager, avdmanager etc.) einer vorhandenen Android Studio Version verwenden, sowie Appium separat installieren.
Da sich diese Tools regelmäßig ändern, und es in der Vergangenheit zu Inkompatibilitäten und Fehlern nach Releasewechseln kam, empfehlen wir zu Beginn, das mitgelieferte Paket zu verwenden. Dies ist möglicherweise nicht das aktuellste, wurde aber auf Lauffähigkeit getestet.

Falls das Android Mobilgerät an einem entfernen Rechner angeschlossen ist,
können Sie den aktuellen Bildschirminhalt z.B. mit dem [https://github.com/Genymobile/scrcpy scrcpy] tool live mitverfolgen.

== Mac OS (nicht erforderlich für Android-Tests)==
Hinweis: Wenn Sie nicht vorhaben, iOS-Geräte (iPhone, iPad, etc.) zu testen, können Sie das Folgende ignorieren. '''Der Apple-Rechner sowie das Mac-Setup werden für Android-Geräte nicht benötigt'''.

=== Xcode ===
Zur Automatisierung mit iOS-Geräten wird [https://developer.apple.com/xcode/ Xcode] benötigt. Sie erhalten dieses über den App Store. Dabei ist darauf zu achten, dass die Version zu den getesteten iOS-Versionen passt.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
Diese Tabelle gibt nur eine vereinfachte Übersicht, lesen Sie besser unter [https://xcodereleases.com/ Xcode Releases] oder [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode-Versionen] welche Version Sie brauchen. Für neue iOS Minor-Versionen gibt es in der Regel auch ein Update für Xcode, z.B. brauchen Sie für iOS 10.2 mindestens Xcode 8.2, für iOS 10.3 mindestens Xcode 8.3 usw.
Wenn Sie also auf eine neuere iOS-Version wechseln, benötigen Sie in der Regel auch eine neuere Xcode-Version. Neuere Versionen von Xcode laufen möglicherweise nicht auf älteren Betriebssystemen, was wiederum eine Aktualisierung des Betriebssystems erforderlich machen kann. Falls Sie auch ältere iOS-Versionen testen wollen kann es sinnvoll sein, die entsprechenden Xcode-Versionen parallel zu installieren.

=== Appium ===
Der Appium-Server kann entweder als Kommandozeilen-Anwendung installiert werden oder über [https://github.com/appium/appium-desktop Appium Desktop] verwendet werden, welcher den Server über ein GUI zur Verfügung stellt. Mittlerweile gibt es auch Appium 2.0, was wir aber bisher noch nicht mit expecco getestet haben und daher nicht empfehlen.

==== Appium Desktop ====
Laden Sie die neueste Version von [https://github.com/appium/appium-desktop/releases/ Appium Desktop] herunter. Für den Mac nehmen Sie am besten die dmg-Datei und installieren sie in den Anwendungen. Beim Starten der Anwendung ''Appium Server GUI'' erhalten Sie wahrscheinlich eine Fehlermeldung, dass es aus Sicherheitsgründen nicht möglich ist. Öffnen Sie dann das Kontextmenü auf der Anwendungsdatei (Rechtsklick bzw. Strg + Klick) und wählen Sie dort ''Öffnen'' aus. Bestätigen Sie dann, dass Sie die Anwendung wirklich öffnen wollen. Fortan können Sie die Anwendung normal öffnen.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Ab Xcode 14 gibt es Probleme beim Signieren des WebDriverAgents, den Appium zur Automatisierung auf das Gerät spielt. Dadurch ist mit der Version 1.22.3-4 von Appium Desktop kein Verbindungsaufbau möglich. Das Problem ist in neueren Versionen des WebDriverAgents behoben, es gibt aber aktuell noch keine Version von Appium Desktop, die eine solche Version enthält (Stand November 2022). Sie können aber manuell eine neue Version herunterladen (z.B. 4.10.2) und die Dateien in Appium ersetzen. Laden Sie dazu von der [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent Download-Seite] eine der beiden Archivdateien (zip oder tar.gz) mit dem Source Code herunter. Öffnen und entpacken Sie dann diese Datei. Den Inhalt des Ordners WebDriverAgent-4.10.2 müssen Sie nun nach

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

kopieren. Wenn Sie über den Finder dorthin navigieren, machen Sie auf die Anwendung ''Appium Server GUI'' einen Kontextklick (Rechtsklick bzw. Strg + Klick) und wählen Sie im Menü ''Paketinhalt anzeigen''. Ersetzen Sie alle Dateien, die bereits mit gleichem Namen enthalten sind.

==== Appium über npm installieren ====
Sie können Appium auch über npm (Node Package Manager) installieren. Dazu müsen Sie erst node/npm installieren. Das geht mit [https://github.com/nvm-sh/nvm nvm] (Node Version Manager) was Sie von Github bekommen. Falls die folgende Installationsanleitung bei Ihnen nicht funktionieren sollte, finden Sie dort ausführlichere Informationen im [https://github.com/nvm-sh/nvm#readme Readme].

Öffnen Sie ein Terminal-Fenster. Klonen Sie dann das Github-Repository von nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
und laden Sie es
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Führen Sie danach
command -v nvm
aus, um zu testen, ob es funktioniert hat. Es sollte ''nvm'' ausgegeben werden. Kommt keine Antwort, führen Sie
touch ~/.zshrc
aus, und versuchen Sie es erneut.

Nun können Sie node mit dem folgenden Befehl installieren.
nvm install 16.15.1
Da es mit der aktuellen Version von node Probleme beim Installieren von Appium gibt, empfehlen wir diese Version.

Nachdem node installiert ist, können Sie Appium darüber installieren:
npm install -g appium

Den Appium-Server können Sie nun einfach über den Befehl
appium
starten. Die Ausgabe erfolgt dann direkt im Terminal.

Auch bei dieser Version gibt es das Problem bei der Signierung des WebDriverAgents, wie bei [[#Appium_Desktop | Appium Desktop]] beschrieben. Laden Sie also auch in diesem Fall eine neuere Version des WebDriverAgents herunter und ersetzen Sie die alten Dateien. Diese finden Sie unter
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
Ältere Appium-Versionen stellen wir Ihnen über das Mobile Testing Supplement für Mac OS zur Verfügung, mit dem Sie es einfach installieren können:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.2)]
:Enthält Appium Version 1.18.3 und verwendet node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.0)]
:Nur wenige Änderungen im Vergleich zur vorigen Version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.98)]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und es wird node 12 verwendet.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.96)]
:Diese Version enthält Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.94)]
:Diese Version enthält Appium 1.8.0.

* expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.0.94)]
:Diese Version enthält Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement für Mac OS]
:Diese Version entält Appium 1.4.16.

Nachdem Herunterladen des Supplements, können Sie es in ein Verzeichnis Ihrer Wahl (z. B. Ihr Home-Verzeichnis) verschieben und dort entpacken. Ein geeigneter Befehl in einer Shell könnte wie folgt aussehen, passen Sie dabei die Versionsnummer entsprechend an:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

Wenn Sie Ihre Standard-Xcode-Installation verwenden wollen, können Sie Appium direkt über die Datei im ''bin''-Verzeichnis mit der entsprechenden Versionsnummer starten:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Falls Sie ein anderes Xcode als das als Standard konfigurierte verwenden wollen, müssen Sie Appium den entsprechenden Pfad über die Umgebungsvariable ''DEVELOPER_DIR'' angeben.
Wenn Sie Xcode z. B. in ''/Applications/Xcode-11.3.app'' installiert haben, müssten Sie Appium so starten:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Was als Standard-Xcode-Installation gesetzt ist, zeigt der Befehl:

xcode-select -p

Wenn Appium Ihre Xcode-Installation nicht findet, erscheint beim Verbinden eine Fehlermeldung in der Art:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
Starten Sie in diesem Fall Appium erneut, unter Angabe eines gültigen ''DEVELOPER_DIR''.

==== WebDriverAgent-Signierung ====
Zur Automatisierung lädt Appium eine App namens WebDriverAgent auf das Gerät und muss sie dafür signieren können. Dazu brauchen Sie einen Apple-Account und ein entsprechendes Zertifikat. Zur Evaluierung können Sie einen kostenlosen Account verwenden. Dieser hat den Nachteil, dass erstellte Profile nur eine Woche gültig sind und danach neu erstellt werden müssen. Seien Sie auch vorsichtig, wenn Sie sich den Account teilen, da es vorkommen kann, dass Zertifikate widerrufen werden oder durch automatische Generierung ungültig werden. Als Folge können bereits signierte Apps nicht mehr verwendet werden.

Wenn Sie bereits ein entsprechendes Zertifikat mit dem zugehörigen privaten Schlüssel in Ihrer [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac haben, können Sie den WebDriverAgent automatisch signieren lassen. Ansonsten empfiehlt es sich, die Signierung über Xcode einzustellen und zu verwalten.

Schließen Sie zuerst das Gerät, das Sie verwenden möchten, über USB an den Mac an. Stellen Sie sicher, dass sich der Mac und das Gerät im selben Netzwerk befinden, ansonsten kann es beim Verbindungsaufbau mit Appium zu Problemen kommen. Starten Sie Xcode und öffnen Sie ''Preferences''. Wechseln Sie zur Seite der Accounts und legen Sie einen Eintrag mit Ihrem Account an. Anschließend können Sie auf ''Manage Certificates...'' klicken, um die Zertifikate zu sehen, die zu diesem Account gehören. Zum Ausführen von Tests benötigen Sie ein iOS-Development-Zertifikat und den dazugehörigen privaten Schlüssel. Wenn Sie noch keines besitzen, erstellen Sie eines. Wenn Sie bereits eines haben, aber es nicht in Ihrem Schlüsselbund vorhanden ist (erkennbar an dem Hinweis "Not in Keychain"), können Sie es importieren. Das können Sie über die [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac machen, wenn Sie es zuvor aus dem Schlüsselbund exportiert haben, in dem es sich befindet. Das Zertifikat mit dem zugehörigen Schlüssel sollte sich im Schlüsselbund ''Anmeldung'' befinden. Dort kann es als PKCS#12-Datei (Endung typischerweise .p12) exportiert werden. Um ein Zertifikat in Ihren Schlüsselbund zu importieren, wählen Sie im Menü ''Ablage'' die Option ''Objekte importieren''. Falls Sie nicht wissen, wo das Zertifikat gespeichert ist, können Sie es in Xcode auch widerrufen und in Ihrem Schlüsselbund neu anlegen. Machen Sie das jedoch nur, wenn Sie wissen, dass das alte Zertifikat nicht mehr in Verwendung ist, da es danach nicht mehr benutzt werden kann. Nun sollte Ihr Schlüsselbund ein iOS-Development-Zertifikat enthalten.


Öffnen Sie nun das WebDriverAgent-Projekt in Xcode. Wenn Sie das Mobile Testing Supplement installiert haben, finden Sie es in dessen Verzeichnis unter
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
Wenn Sie Appium Desktop installier haben, finden Sie es unter
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''
Sie können einfach im Finder zu der Xcode-Project-Datei navigieren und Sie über einen Doppelklick öffnen. Beachten Sie dabei, dass Sie dabei auf die Anwendung Appium Server GUI einen Kontextklick (Rechtsklick bzw. Strg + Klick) machen und im Menü ''Paketinhalt anzeigen'' auswählen müssen, um in deren Unterverzeichnis zu gelangen.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Wählen Sie ''WebDriverAgentLib'' und die Seite ''Signing & Capabilities'' aus. Setzen Sie dort im Abschnitt ''Signing'' die Option ''Automatically manage signing'' und wählen Sie dann ein Team aus. Wechseln Sie nun zu ''WebDriverAgentRunner'' und tun Sie dort dasselbe.

Durch das Setzen des Teams sollten die Fehler für den WebDriverAgentRunner verschwinden. Sollte Xcode kein passendes Provisioning Profile für die Bundle ID ''com.facebook.WebDriverAgentRunner'' erstellen können, können Sie diese anpassen, dass sie zu Ihrem Zertifikat passt. Danach können Sie Xcode beenden oder auch, wie weiter unten beschrieben, direkt den Build über Xcode starten, damit das Projekt bereits gebaut ist, wenn Appium es verwenden möchte.

Wenn Sie sich nun von expecco eine Verbindung zu Ihrem Gerät aufbauen, wird der WebDriverAgent darauf installiert und gestartet, um anschließend zur zu testenden App zu wechseln. Eventuell muss auf dem Gerät muss der Ausführung des WebDriverAgents vertraut noch werden. Ein Anzeichnen dafür kann sein, dass die App WebDriverAgent zwar auf dem Gerät erscheint und zu starten versucht, danach aber wieder deinstalliert wird. Öffnen Sie dazu während des Verbindungsaufbaus auf dem Gerät in die Einstellungen und dort unter ''Allgemein'' den Eintrag ''Geräteverwaltung''. Dieser Eintrag ist nur sichtbar, wenn eine Entwickler-App auf dem Gerät installiert ist. Sie müssen daher möglicherweise warten, bis der WebDriverAgent installiert ist, bevor der Eintrag erscheint. Wählen Sie dort den Eintrag Ihres Apple-Accounts und vertrauen Sie ihm. Da der WebDriverAgent wieder deinstalliert wird, wenn der Start nicht funktioniert hat, müssen Sie dies während des Verbindungsaufbaus tun. Falls Ihnen das zu hektisch ist, können Sie auch folgenden Code ausführen:

<nowiki>xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test</nowiki>
bzw.
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

Damit wird der WebDriverAgent auf dem Gerät installiert ohne dass er wieder gelöscht wird.

Wenn es Probleme beim Installieren des WebDriverAgents gibt, können Sie auch versuchen, den Build über Xcode zu starten. Stellen Sie sicher, dass das richtige Target ''WebDriverAgent'' ausgewählt ist. Fehlermeldungen in Xcode zeigen vielleicht einfacher, wo das Problem liegt. Manchmal hilft es auch, es ein zweites Mal zu versuchen, weil es möglicherweise beim ersten Mal zu lange gedauert hat und abgebrochen wurde. Es kann sein, dass Sie während des Builds mehrmals aufgefordert werden, das Passwort für Ihren Schlüsselbund anzugeben.

[[Datei:WebDriverAgentCodesign.png]]

Lesen Sie auch die Dokumentation von Appium zum [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Aufsetzen von Tests mit iOS-Geräten]. In der [https://support.apple.com/en-us/HT204460 Dokumentation von Apple] finden Sie nähere Informationen zum Installieren und Vertrauen von Apps.

Ist der WebDriverAgent einmal auf dem Gerät installiert, wird er für spätere Verbindungen wieder verwendet und der Verbindungsaufbau sollte schneller funktionieren. Ebenso liegt dann die signierte Version bereits auf Ihrem Mac und muss nicht erneut gebaut werden, was die Verbindung zu weiteren Geräten ebenfalls beschleunigt. Wenn Sie wissen, dass bei Ihrem Verbindungsaufbau der WebDriverAgent erst noch signiert und gebaut werden muss, ist es ratsam, die Capability ''wdaLaunchTimeout'' zu setzen. Dieser Timeout, wie lange auf den Start der WebDriverAgents auf dem Gerät gewartet werden soll, liegt standardmäßig bei 60000$nbsp;ms. Der Build dauert aber häufig über eine Minute, sodass der Versuch zum Verbindungsaufbau dann abgebrochen wird. Ein Wert von 120000 hat sich hier als besser erwiesen.

== Konfiguration des Plugins ==
Bevor Sie loslegen, sollten Sie die Einstellungen des Mobile Testing Plugins überprüfen und ggf. anpassen.

Öffnen Sie im Menü den Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" den Eintrag "''Mobile Testing''" (s. Abb.). Standardmäßig werden diese Pfade automatisch gefunden (1). Um einen Pfad manuell anzupassen, deaktivieren Sie den entsprechenden Haken rechts davon. Sie erhalten in einer Drop-down-Liste einige Pfade zur Auswahl. Ist ein eingetragener Pfad falsch oder kann er nicht gefunden werden, wird das Feld rot markiert und es erscheint ein diesbezüglicher Hinweis. Stellen Sie sicher, dass alle Pfade richtig angegeben sind.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Konfiguration des Plugins]]

*'''appium''': Geben Sie hier den Pfad zur ausführbaren Datei an mit der Appium in der Kommandozeile gestartet werden kann. Unter Windows wird diese Datei in der Regel "<code>appium.cmd</code>" heißen. Dieser Pfad wird benutzt, wenn expecco einen Appium-Server startet.
*'''node''': Geben Sie hier den Pfad zur ausführbaren Datei an, die Node (auch "Node.js") startet. Dieser Pfad wird beim Starten eines Servers an Appium weitergegeben, damit Appium ihn unabhängig von der PATH-Variablen findet. Unter Windows heißt diese Datei in der Regel "<code>node.exe</code>".
*'''JAVA_HOME''': Geben Sie hier den Pfad zu einem JDK an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden. Um einzustellen, welches Java von expecco verwendet werden soll, setzen Sie diesen Pfad in den Einstellungen für die Java Bridge.
*'''ANDROID_HOME''': Geben Sie hier den Pfad zu einem SDK von Android an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden.
*'''adb''': Hier steht der Pfad zum adb-Befehl. Unter Windows heißt die Datei adb.exe. Diese wird von expecco beispielsweise verwendet, um die Liste der angeschlossenen Geräte zu erhalten. Diesen Pfad sollten Sie automatisch wählen lassen, da dann der Befehl im ANDROID_HOME-Verzeichnis verwendet wird. Dieser wird auch von Appium verwendet. Falls expecco und Appium jedoch verschiedene Versionen von adb verwenden kann es zu Konflikten kommen.
*'''android.bat''': Diese Datei wird nur benötigt, um damit den AVD und den SDK Manager zu starten. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.
*'''aapt''': Geben Sie hier den Pfad zum aapt-Befehl an. Unter Windows heißt diese Datei ''aapt.exe''. expecco verwendet aapt nur im Verbindungseditor, um das Paket und die Activities einer apk-Datei zu lesen. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | Konfiguration des JDKs]]

Ab expecco 2.11 gibt es das Feld ''Team-ID''. Wenn Sie iOS-Tests ausführen, tragen Sie hier die Team-ID Ihres Zertifikats ein. Diese wird für jede iOS-Verbindung verwendet, außer Sie setzen den Wert im Einzelfall in den Verbindungseinstellungen um. Wie Sie die Team-ID erhalten, lesen Sie im Abschnitt zur [[#Signierung|Signierung]] ber der Installation auf Mac OS. Mit expecco 2.10 können Sie die Team-ID nur für jede Verbindungseinstellung extra als Capability eintragen. Dazu müssen Sie jedoch die [[#Erweiterte_Ansicht|erweiterte Ansicht]] verwenden. Geben Sie hier die Capability ''xcodeOrgId'' an und setzen Sie als Wert die Team-ID des Zertifikats.

Die Einstellung zur Serveradresse unten auf der Seite bezieht sich auf das Verhalten des Verbindungseditors. Dieser prüft am Ende, ob die Serveradresse auf ''/wd/hub'' endet, da dies die übliche Form ist. Falls nicht, wird in einem Dialog gefragt, wie darauf reagiert werden soll. Das festgelegte Verhalten kann hier eingesehen und verändert werden.

Wechseln Sie ebenfalls zum Eintrag ''Java Bridge'' (s. Abb.). Hier muss der Pfad zu Ihrer Java-Installation angegeben werden, die von expecco benutzt wird. Tragen Sie hier ein JDK ein. Falls Sie unter Windows das aus dem Mobile Testing Supplement verwenden möchten, lautet der Pfad
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
Sie können auch die Systemeinstellungen verwenden.

== Android-Gerät vorbereiten ==
Wenn Sie ein Android-Gerät unter Windows anschließen benötigen Sie möglicherweise noch einen adb-Treiber für das Gerät. Einen passenden Treiber finden Sie üblicherweise auf der jeweiligen Webseite des Herstellers. Haben Sie den Universal-Treiber aus dem Mobile Testing Supplement installiert, sollte für die meisten Geräte bereits alles funktionieren. In einigen Fällen versucht auch Windows automatisch einen Treiber zu installieren, wenn Sie das Gerät zum ersten mal anschließen.
 
===USB-Debugging Einschalten===
'''Achtung:'''
Bevor Sie ein Mobilgerät mit dem Appium-Plugin ansteuern können, müssen Sie für dieses Debugging erlauben!

Für Android-Geräte finden Sie diese Option in den Einstellungen unter ''[https://www.droidwiki.org/wiki/Entwickleroptionen Entwickleroptionen]'' mit dem Namen ''[https://www.droidwiki.org/USB-Debugging USB-Debugging]''. Falls die Entwickleroptionen nicht angezeigt werden, können Sie diese freischalten, indem Sie unter "''Über das Telefon''" siebenmal auf "''Build-Nummer''" tippen.

===Wach bleiben Aktivieren===
Aktivieren Sie auch die Funktion ''Wach bleiben'', damit das Gerät nicht während der Testerstellung oder -ausführung den Bildschirm abschaltet.

Aus Sicherheitsgründen muss USB-Debugging für jeden Computer einzeln zugelassen werden. Beim Verbinden des Geräts mit dem PC über USB müssen Sie dabei am Gerät der Verbindung zustimmen. Falls Sie dies für Ihren Computer noch nicht getan haben, aber auf dem Gerät kein entsprechender Dialog erscheint, kann es helfen, das Gerät aus- und wieder einzustecken. Das kann insbesondere dann passieren, wenn Sie den ADB-Treiber installiert haben während das Gerät bereits über USB angeschlossen war. Falls auch das nicht hilft, öffnen Sie die Benachrichtigungen, indem Sie sie vom oberen Bildschirmrand herunter ziehen. Dort finden Sie die USB-Verbindung und Sie können die Optionen dazu öffnen. Wählen Sie einen anderen Verbindungstypen aus; in der Regel sollten MTP oder PTP funktionieren.

Sie können auch auf einem Emulator testen. Dieser muss nicht gesondert vorbereitet werden, da er bereits für USB-Debugging ausgelegt ist. Es ist sogar möglich, einen Emulator bei Testbeginn zu starten.

Um zu überprüfen, ob ein Gerät, das Sie an Ihren Rechner angeschlossen haben, verwendet werden kann, öffnen Sie den [[#Verbindungseditor|Verbindungseditor]]. Das Gerät sollte dort angezeigt werden.

=== Verbindung über WLAN ===
Es ist auch möglich, Android-Geräte über WLAN zu verbinden. Für Geräte mit Android 11 oder neuer ist dies direkt über WLAN möglich, im anderen Fall müssen Sie das Gerät zuerst über USB verbinden. Ab expecco 22.1 können Sie eine WLAN-Verbindung über den [[Mobile Testing Plugin#Verbindungseditor|Verbindungseditor]] aufbauen. Ansonsten ist es auch über die Eingabeaufforderung möglich.
==== Drahtlos verbinden über die Eingabeaufforderung mit expecco Versionen vor 22.1 (ab Android 11) ====
Mit expecco ab Version 22.1 funktioniert das einfacher über den Verbindungseditor.

Erlauben Sie in den Entwickleroptionen des Geräts Debugging über WLAN und öffnen Sie dessen Optionen. Sie müssen zuerst das Gerät mit dem Rechner koppeln. Wählen Sie dazu "''Gerät mit einem Kopplungscode koppeln''", um einen Kopplungscode und eine IP-Adresse mit Port zu erhalten. Öffnen Sie dann auf dem Rechner die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb pair <IP-Adresse des Geräts>:<Kopplungsport></nowiki>
wobei Sie <tt><IP-Adresse des Geräts>:<Kopplungsport></tt> durch die auf dem Gerät angezeigte IP-Adresse & Port ersetzen. Danach werden Sie aufgefordert, den Kopplungscode einzugeben. Wenn alles geklappt hat, sollte sich das Popup auf dem Gerät schließen und der Rechner als gekoppeltes Gerät angezeigt werden. Geben Sie dann in der Eingabeaufforderung ein:
<nowiki>adb connect <IP-Adresse des Geräts>:<Debug-Port></nowiki>
Die IP-Adresse ist hier noch die gleiche wie beim Koppeln, aber der Port ist ein anderer. Beides wird als IP-Adresse & Port auf dem Gerät angezeigt. Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie entweder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden. Häufig wird beim Neustart des Geräts auch die Erlaubnis für das Debugging über WLAN wieder zurückgesetzt und der verwendete Port ändert sich. Die Kopplung bleibt aber bestehen und muss beim nächsten Verbinden nicht noch einmal durchgeführt werden.

==== WLAN Verbindung über USB starten (Android 10 und früher) ====
Verbinden Sie zunächst das Gerät über USB mit dem Rechner. Öffnen Sie dann die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb tcpip 5555</nowiki>
Damit lauscht das Gerät auf eine TCP/IP-Verbindung an Port 5555. Sollten Sie mehrere Geräte angeschlossen oder Emulatoren laufen haben, müssen Sie genauer angeben, welches Gerät Sie meinen. Geben Sie in diesem Fall ein:
<nowiki>adb devices -l</nowiki>
Sie erhalten eine Liste aller Geräte, wobei die erste Spalte deren Kennung ist. Schreiben Sie dann stattdessen
<nowiki>adb -s <Gerätekennung> tcpip 5555</nowiki>
mit der Gerätekennung des gewünschten Geräts. Sie können die USB-Verbindung nun trennen. Jetzt müssen Sie die IP-Adresse Ihres Gerätes in Erfahrung bringen. Sie finden diese üblicherweise irgendwo in den Einstellungen des Geräts, beispielsweise beim Status oder in den WLAN-Einstellungen. Geben Sie dann ein:
<nowiki>adb connect <IP-Adresse des Geräts></nowiki>
Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie wieder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden.

=== Verbindung zu einem Emulator ===
Sie benötigen dazu den Emulator selbst, sowie mindestens ein AVD (Android Virtual Device). Hinweise zu Installation finden Sie in der [https://developer.android.com/studio/run/emulator Android Studio Dokumentation].

Wenn Sie Android Studio bereits mit den Defaulteinstellungen installiert haben 1), sollte der Emulator bereits mitinstalliert sein. Falls nicht, wählen Sie in Android Studio "''Configure''" - "''SDK Manager''" - "''Android SDK''" - "''SDK Tools''" - ''Android Emulator''", sowie dort die "''Platform Tools''".
Alternativ geht das auch über die Kommandzeile mit dem "sdkmanager" Kommando.

Als nächstes benötigen Sie mindestens ein AVD; auch dies geht am einfachsten über den Dialog in Android Studio:
wählen sie "''Configure''" - "''AVD Manager''" und folgen den Anweisungen (Deviceauswahl, Platform und Android Version).

Auch wenn Sie den Emulator automatisieren benötigen sie Appium; installieren Sie dieses entweder mit dem Mobile Testing Supplement, oder direkt von der Appium homepage (https://github.com/appium/appium-desktop/releases).

1)Android Studio selbst wird nicht von expecco benötigt; es bietet aber kompfortable Dialoge zum Installieren von Paketen und AVDs.

== iOS-Gerät und App vorbereiten ==
Das Ansteuern von iOS-Geräten ist nur über einen Mac möglich. Lesen Sie daher auch den Abschnitt zur [[#Mac_OS|Installation unter Mac OS]].

Bevor Sie ein Mobilgerät mit dem Mobile Testing Plugin ansteuern können, müssen Sie für iOS-Geräte ab iOS 8 Debugging erlauben. Aktivieren Sie dazu die Option ''Enable UI Automation'' unter dem Menüpunkt ''Entwickler'' in den Einstellungen des Geräts. Falls Sie den Eintrag ''Entwickler'' in den Einstellungen nicht finden, gehen Sie wie folgt vor: Schließen Sie das Gerät über USB an den Mac an. Dabei müssen Sie ggf. am Gerät noch der Verbindung zustimmen. Starten Sie Xcode und wählen Sie dann in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie dort Ihr Gerät aus. Danach sollte der Eintrag ''Entwickler'' in den Einstellungen auf dem Gerät auftauchen. Dazu müssen Sie möglicherweise die Einstellungen beenden und neu starten.

[[Datei:Alert.png | thumb | 270px | Beispiel für einen Alert unter iOS]]
Ein Verbindungsaufbau zu dem Gerät ist nicht möglich solange es bestimmte Alerts zeigt. Ein solcher Alert kann z. B. erscheinen wenn FaceTime aktiviert ist, indem ein Hinweis auf anfallende SMS-Gebühren angezeigt wird (siehe Screenshot). Achten Sie darauf, das Gerät so zu konfigurieren, dass es im Leerlauf keine solchen Alerts zeigt.

=== expecco 2.11 und später ===
Sie können beliebige Apps testen, die auf dem verwendeten Gerät lauffähig oder bereits installiert sind. Wenn die App als Development-Build vorliegt, muss die UDID des Geräts in der App hinterlegt sein. In jedem Fall muss der WebDriverAgent für das Gerät signiert werden. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]] unter Mac OS.

Falls Sie in einem Test den Home-Button verwenden wollen, müssen Sie auf dem Gerät AssistiveTouch aktivieren. Sie finden diese Option in den Einstellungen unter ''Allgemein'' > ''Bedienungshilfen'' > ''AssistiveTouch''. Platzieren Sie dann das Menü in der Mitte des oberen Bildschirmrands. Sie können das Drücken des Home-Buttons dann mit dem entsprechenden Menüeintrag im Recorder aufzeichnen oder direkt den Baustein ''Press Home Button'' benutzen.

=== expecco 2.10 ===
Die App, die Sie verwenden wollen, muss als Development-Build vorliegen. Außerdem muss die UDID des Geräts in der App hinterlegt sein.

=== Development-Build signieren ===
Ein Development-Build einer App ist nur für eine begrenzte Zahl von Geräten zugelassen und kann auf anderen Geräten nicht gestartet werden. Es ist aber möglich, das Zertifikat und die verwendbaren Geräte in einem Development-Build auszutauschen.

* Evaluierung mit Demo-App von eXept:
:Gerne stellen wir Ihnen eine Demo-App zur Verfügung, die als Development-Build vorliegt und die wir für Ihr Gerät signieren können. Senden Sie dazu bitte Ihrem eXept-Ansprechpartner die UDID Ihres Gerätes zu. Wie Sie die UDID Ihres Gerätes ermitteln können, ist im folgenden Abschnitt beschrieben.

* Eigene App für Ihr Testgerät verwenden:
:Wenn Sie von den App-Entwicklern einen Development-Build (IPA-Datei) erhalten, der für Ihr Testgerät zugelassen ist, können Sie diesen direkt verwenden. Dazu müssen Sie den Entwicklern die UDID Ihres Geräts mitteilen, damit sie diese eintragen können. '''Sie können die UDID eines Gerätes mithilfe von Xcode auslesen'''. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie Ihr Gerät aus und suchen Sie in Eigenschaften den Eintrag ''Identifier''. Die UDID ist eine 40-stellige Hexadezimalzahl.

* Extern entwickelte App für Ihr Testgerät umsignieren:
:Es können auch Apps umsigniert werden, damit Sie auf anderen Geräten lauffähig sind. Dieser Vorgang ist jedoch kompliziert und setzt insbesondere einen Zugang zu einem Apple-Developer-Account voraus. Eine Dokumentation zur Vorgehensweise ist derzeit in Vorbereitung.

:Für die Evaluierung unterstützen wir Sie gerne beim Umsignieren Ihrer App.


Weitere Informationen zur Verwendung von iOS-Geräten finden Sie auch in der [http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Dokumentation von Appium].

=== Native iOS-Apps ===
Sie können auch Apps verwenden, die bereits nativ auf dem Gerät vorhanden sind. Dazu müssen Sie deren Bundle-ID kennen und diese dann in die Verbindungseinstellungen eintragen. Hier eine kleine Auswahl gängiger Apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

Weitere Bundle-IDs finden Sie [https://github.com/joeblau/apple-bundle-identifiers hier].

= Beispiele =
Bei den Demo-Testsuiten für expecco finden Sie auch Beispiele für Tests mit dem Mobile Testing Plugin. Wählen Sie dazu auf dem Startbildschirm die Option "''Beispiel aus Datei''" und öffnen Sie den Ordner "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
Die Testsuite enthält zwei einfache Testpläne: "''Simple CalculatorTest''" und "''Complex Calculator and Messaging Test''". Beide Tests verwenden einen Android-Emulator, den Sie vor Beginn starten müssen. Die Apps, die im Test verwendet werden, gehören zur Grundausstattung des Emulators und müssen daher nicht mehr installiert werden. Da sich die Apps unter jeder Android-Version unterscheiden können, ist es wichtig, dass Ihr Emulator unter Android 6.0 läuft. Außerdem muss die Sprache auf Englisch gestellt sein.

; Simple CalculatorTest
: Dieser Test verbindet sich mit dem Taschenrechner und gibt die Formel ''2+3'' ein. Das Ergebnis des Rechners wird mit dem erwarteten Wert ''5'' verglichen.

; Complex Calculator and Messaging Test
: Dieser Test verbindet sich mit dem Taschenrechner und öffnet anschließend den Nachrichtendienst. Dort wartet er auf eine einkommende Nachricht von der Nummer ''15555215556'', in der eine zu berechnende Formel gesendet wird. Die Nachricht wird zuvor über einen Socket beim Emulator erzeugt. Nach dem Eintreffen der Nachricht wird diese vom Test geöffnet und deren Inhalt gelesen. Danach wird wieder der Taschenrechner geöffnet, die erhaltene Formel eingegeben und das Ergebnis gelesen. Anschließend wechselt der Test wieder zum Nachrichtendienst und sendet das Ergebnis als Antwort.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
Diese sind Bestandteil des Tutorials zum Mobile Testing Plugin. Der jeweils enthaltene Testfall ist unvollständig und wird im Zuge des Tutorials ergänzt. Lesen Sie dazu den Abschnitt [[#Tutorial|Tutorial]].

= Tutorial =
Es gibt ein Tutorial, das das grundsätzliche Vorgehen zur Erstellung von Tests mit dem Mobile Testing Plugin beschreibt. Grundlage dafür ist ein mitgeliefertes Beispiel, bestehend aus einer einfachen App und einer expecco-Testsuite.

Sie finden es auf der Seite [[Mobile_Testing_Tutorial|Mobile Testing Tutorial]] in zwei Versionen für Android und für iOS.
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_Android|Erste Schritte mit Android]]
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_iOS|Erste Schritte mit iOS]]

= Dialoge des Mobile Testing Plugins =
== Verbindungseditor ==
Mithilfe des Verbindungseditors können Sie schnell Verbindungen definieren, ändern oder aufbauen. Je nach Aufgabe weist der Dialog kleine Unterschiede auf und wird unterschiedlich geöffnet:
*Um eine Verbindung aufzubauen, klicken Sie im GUI-Browser auf "''Verbinden'"' klicken und wählen dann "''Mobile Testing''".
*Um eine bestehende Verbindung im GUI-Browser zu ändern oder zu kopieren, wählen Sie diese aus, machen einen Rechtsklick und wählen im Kontextmenü "''Verbindung bearbeiten''" oder "''Verbindung kopieren''" aus.
*Wollen Sie Verbindungseinstellungen nicht für den GUI-Browser sondern zur Verwendung in einem Test erstellen, wählen Sie im Menü des Mobile Testing Plugins den Punkt "''Verbindungseinstellungen erstellen...''". Darüber können nur die Einstellungen für eine Verbindung erstellt werden, ohne dass eine Verbindung tatsächlich angelegt wird.

Einige der Schaltflächen sind nur beim Erstellen von Verbindungseinstellungen sichtbar:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#"''Einstellungen löschen''": Setzt alle Einträge zurück. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Einstellungen aus Datei laden''": Erlaubt das Öffnen einer gespeicherten Einstellungsdatei (*.csf). Deren Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen aus Anhang laden''": Erlaubt das Öffnen eines Anhangs mit Verbindungseinstellungen aus einem geöffneten Projekt. Diese Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen in Datei speichern''" sowie
#"''Einstellungen in Anhang speichern''": Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern oder als Anhang in einem geöffneten Projekt anlegen. Beide Optionen besitzen ein verzögertes Menü, in dem Sie auswählen können, nur einen bestimmten Teil der Einstellungen zu speichern. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Erweiterte Ansicht''": Damit können Sie in die erweiterte Ansicht wechseln, um zusätzliche Einstellungen vorzunehmen. Lesen Sie dazu mehr am Ende des Kapitels. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Hilfe''": An der rechten Seite wird ein Hilfetext zum jeweiligen Schritt ein- oder ausgeblendet.

Der Dialog ist in drei Schritte unterteilt. Im ersten Schritt wählen Sie das Gerät, das Sie verwenden möchten, im zweiten Schritt wählen Sie aus, welche App verwendet werden soll und im letzten Schritt erfolgen die Einstellungen zum Appium-Server.

===Schritt 1: Gerät auswählen===
Im oberen Teil erhalten Sie eine Liste aller angeschlossenen Appium-Geräte, die erkannt werden. Mit der Checkbox darunter können Sie die Geräte ausblenden, die zwar erkannt werden, aber nicht bereit sind. Falls Sie ein Gerät eintragen wollen, das nicht angeschlossen ist, können Sie dies mit dem entsprechenden Knopf "''Android-Gerät eingeben''" bzw. "''iOS-Gerät eingeben''" anlegen. Dazu müssen Sie jedoch die benötigten Eigenschaften Ihres Geräts kennen. Das Gerät wird dann in einer zweiten Geräteliste angelegt und kann dort ausgewählt werden. Wenn keine Liste mit angeschlossenen Elementen angezeigt werden kann, werden stattdessen verschiedene Meldungen angezeigt:
*Keine Geräte gefunden
*:expecco konnte kein Android-Geräte finden.
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*Keine verfügbaren Geräte gefunden
*:expecco konnte keine verfügbaren Android-Geräte finden. Es wurden aber nicht verfügbare gefunden, z.B. mit dem Status "unauthorized".
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*:Um nicht verfügbare Geräte anzuzeigen, aktivieren Sie unten diese Option.
*Verbindung verloren
*:expecco hat die Verbindung zum adb-Server verloren. Versuchen Sie die Verbindung wieder herzustellen, indem Sie auf den Button klicken.
*Verbindung fehlgeschlagen
*:expecco konnte sich nicht mit dem adb-Server verbinden. Möglicherweise läuft er nicht oder der angegebene Pfad stimmt nicht.
*:Überprüfen Sie die adb-Konfiguration in den Einstellungen und versuchen Sie den adb-Server zu starten und eine Verbindung herzustellen indem Sie auf den Knopf klicken.
*Verbinden ...
*:expecco verbindet sich mit dem adb-Server. Dies kann einige Sekunden dauern.
*adb-Server starten ...
*:expecco startet den adb-Server. Dies kann einige Sekunden dauern.

Mit "''Weiter''" gelangen Sie zum nächsten Schritt. Wenn Sie Einstellungen für den GUI-Browser eingeben, ist das erst möglich, wenn ein Gerät ausgewählt wurde.

Anmerkung zum Freischalten: In jüngeren Android Versionen werden die Entwickleroptionen zunächst nicht mehr in den Einstellungen angeboten. Falls ihr Android Gerät in den Einstellungen keinen Eintrag zu "''Entwickleroptionen''" zeigt, wählen Sie zunächst den Eintrag "''Telefoninfo''", dann "''SoftwareVersionsInfo''" und klicken darin mehrfach auf den Eintrag "''BuildVersion''".

==== Chromedriver verwalten ====
Wenn die App, die Sie bedienen wollen, WebViews mit Chrome benutzt, benötigt Appium Zugriff auf einen passenden Chromedriver. Wenn Sie ein Gerät in der Liste auswählen, können Sie über "''Chromedriver verwalten''" sehen, welche Chrome-Versionen auf dem Gerät vorhanden sind und welche Chromedriver-Versionen durch expecco zur Verfügung stehen. Über diesen Dialog können Sie auch benötigte Chromedriver-Versionen herunterladen. Beachten Sie, dass auf dem Gerät verschiedene Chrome-Versionen vorhanden sein können, da die Apps in ihren WebViews nicht die gleiche Chrome-Version verwenden müssen, wie die als Browser installierte. Damit alles funktioniert, sollte der verwendete Chromedriver zur entsprechenden App passen. Sie können den Pfad zum Chromedriver auch am Ende des Verbindungsdialogs in den erstellten Capabilities ändern.

==== WLAN-Android-Geräte verbinden ====
Sie können sich auch über WLAN zu Android-Geräten verbinden. Dazu muss das Gerät zunächst mit adb verbunden werden, siehe [[Mobile_Testing_Plugin#Verbindung_.C3.BCber_WLAN|Verbindung über WLAN]]. Ab expecco 22.1 bietet der Verbindungseditor hierfür einen Dialog, der Ihnen dabei hilft und den Sie anstatt der Eingabeaufforderung verwenden können. Für Geräte mit Android 11 oder höher können Sie hier das Gerät mit dem Rechner zu koppeln, indem Sie die entsprechenden Parameter angeben und anschließend die Verbindung unter Angabe von IP-Adresse und Port aufbauen. Sie können damit auch für Geräte, die über USB verbunden sind, eine WLAN-Verbindung aufbauen. Wenn Sie das entsprechende Gerät in der Liste auswählen, werden die benötigten Angaben automatisch ausgelesen.

Beachten Sie, dass der Aufbau einer WLAN-Verbindung nicht Teil der Verbindungseinstellungen ist. Wenn Sie mit den erzeugten Einstellungen eine neue Verbindung aufbauen wollen, müssen Sie sicherstellen, dass das Gerät über mit der angegebenen IP-Adresse und dem Port mit adb verbunden ist, damit es gefunden wird. Die ADB-Verbindung geht verloren, wenn der ADB-Server oder das Gerät neu gestartet werden. Die Erlaubnis für das WLAN-Debugging wird beim Neustart des Geräts auch häufig zurückgesetzt und der Debug-Port kann dann wechseln. Daher muss eine WLAN-Verbindung immer manuell hergestellt werden.

===Schritt 2: App auswählen===
Hier können Sie Angaben zur App machen, die getestet werden soll. Dabei können Sie entscheiden, ob Sie eine App verwenden wollen, die bereits auf dem Gerät installiert ist, oder ob für den Test eine App installiert werden soll. Wählen Sie oben den entsprechenden Reiter aus. Je nachdem, ob Sie im vorigen Schritt ein Android- oder ein iOS-Gerät ausgewählt haben, ändert sich die erforderte Eingabe.

*'''Android'''
**''App auf dem Gerät''
**:Wenn Sie im ersten Schritt ein angeschlossenes Gerät ausgewählt haben, werden die Pakete aller installierten Apps automatisch abgerufen und Sie können die Auswahl aus den Drop-down-Listen treffen. Die installierten Apps sind in Fremdpakete und Systempakete unterteilt; wählen Sie die entsprechende Paketliste aus. Diese Auswahl gehört nicht zu den Einstellungen, sondern stellt nur die entsprechende Paketliste zur Verfügung. Sie können den Filter benutzen, um die Liste weiter einzuschränken und dann das gewünschte Paket auswählen. Die Activities des ausgwählten Pakets werden ebenfalls automatisch abgerufen und als Drop-down-Liste zur Verfügung gestellt. Wählen Sie die Activity aus, die gestartet werden soll. In der Regel wird automatisch eine Activity aus der Liste eingetragen. Falls Sie kein verbundenes Gerät verwenden, müssen Sie die Eingabe des Pakets und der Activity von Hand vornehmen.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Benutzen Sie einen lokalen Appium-Server, können Sie den rechten Butten benutzen, um zu der Installationsdatei der App zu navigieren und diesen Pfad einzutragen. Wenn möglich werden dabei auch das entsprechende Paket und die Activity in den Feldern darunter eingetragen. Diese Angabe ist aber nicht notwendig.

*'''iOS'''
**''App auf dem Gerät''
**:Geben Sie die Bundle-ID einer installierten App an. Sie können die IDs der installierten Apps bspw. mithilfe von Xcode erfahren. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü "''Window''" den Eintrag "''Devices''". Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wenn Sie Ihr Gerät auswählen, sehen Sie in der Übersicht eine Auflistung der von Ihnen installierten Apps.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Zu den Vorraussetzungen an Apps für reale Geräte lesen Sie bitte den Abschnitt [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Geräte und App vorbereiten]].

Im unteren Teil können Sie festlegen, ob die App beim Verbindungsabbau zurückgesetzt bzw. deinstalliert werden soll, und ob sie initial zurückgesetzt werden soll. Auch hier wird die entsprechende Capability gar nicht gesetzt, wenn Sie "''(Default)''" auswählen. Mit "''Weiter''" gelangen Sie zum nächsten Schritt.

===Schritt 3: Servereinstellungen===
Im letzten Schritt befindet sich zunächst im oberen Teil eine Liste aller Capabilities, die sich aus Ihren Angaben der vorigen Schritte ergeben. Wenn Sie sich mit Appium auskennen und noch zusätzliche Capabilities setzen möchten, die der Verbindungseditor nicht abdeckt, können Sie durch Klicken auf "''Bearbeiten''" in die erweiterte Ansicht gelangen. Lesen Sie dazu den Abschnitt weiter unten.

Wenn Sie Einstellungen für den GUI-Browser eingeben, können Sie den ''Verbindungsnamen'' eintragen, mit dem die Verbindung angezeigt wird. Dies ist auch der Name unter dem Bausteine diese Verbindung verwenden können, wenn sie aufgebaut ist. Wenn Sie das Feld frei lassen, wird ein Name generiert. Wenn der Haken für "''Von expecco gesteuert''" gesetzt ist, wird expecco einen lokalen Appium-Server an einem freien Port starten, oder einen bereits gestarteten freien Server verwenden. Um einen eigenen Server zu verwenden, schalten Sie diese Funktion ab und geben Sie die entsprechende Adresse ein. Sie erhalten die lokale Standard-Adresse und bereits verwendete Adressen zur Auswahl.

In älteren expecco-Versionen ist der Haken mit "''Bei Bedarf starten''" beschriftet. In diesem Fall müssen Sie auch eine Adresse angeben, wenn expecco den Server starten soll. expecco versucht dann beim Verbinden einen Appium-Server an der angegebenen Adresse zu starten, wenn dort noch keiner läuft. Dieser Server wird dann beim Beenden der Verbindung ebenfalls heruntergefahren. Dies funktioniert nur für lokale Adressen. Achten Sie darauf, nur Portnummern zu verwenden, die auch frei sind. Verwenden Sie am besten nur ungerade Portnummern ab dem Standardport 4723. Beim Verbindungsaufbau wird ebenfalls die folgende Portnummer verwendet, wodurch es sonst zu Konflikten kommen könnte.

Je nachdem, wie Sie den Dialog geöffnet haben, gibt es nun verschiedene Schaltflächen um ihn abzuschließen. In jedem Fall haben Sie die Option zu speichern. Dabei öffnet sich ein Dialog, indem Sie entweder ein geöffnet Projekt auswählen können, um die Einstellungen dort als Anhang zu speichern, oder auswählen es in einer Datei zu speichern, die Sie anschließend angeben können. Durch das Speichern wird der Dialog nicht beendet, wodurch Sie anschließend noch eine andere Option auswählen könnten.

Wenn Sie den Editor zum Verbindungsaufbau geöffnet haben, können Sie abschließend auf "''Verbinden''" oder "''Server starten und verbinden''" klicken, je nachdem, ob der Haken für den Serverstart gesetzt ist. Für das Ändern oder Kopieren einer Verbindung im GUI-Brower heißt diese Option "''Übernehmen''", da in diesem Fall nur der Verbindungseintrag geändert bzw. neu angelegt wird, der Verbindungsaufbau aber nicht gestartet wird. Das können Sie bei Bedarf anschließend über das Kontextmenü tun. Falls Sie Capabilities einer bestehenden Verbindung geändert haben, fordert Sie anschließend ein Dialog auf zu entscheiden, ob diese Änderungen direkt übernommen werden sollen, indem die Verbindung abgebaut und mit den neuen Verbindungen aufgebaut wird, oder nicht. In diesem Fall werden die Änderungen erst wirksam, nachdem Sie die Verbindung neu aufbauen.

Zur Verwendung des Verbindungseditors lesen Sie auch den entsprechenden Abschnitt im jeweiligen Tutorial in Schritt 1 (Android: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren|Demo ausführen]], iOS: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren_.28iOS.29|Demo ausführen (iOS)]]).

===Erweiterte Ansicht===
Die erweiterte Ansicht des Verbindungseditors erhalten Sie entweder durch Klicken auf "''Bearbeiten''" im dritten Schritt oder jederzeit über den entsprechenden Menüeintrag, wenn Sie den Editor über das Plugin-Menü gestartet haben. In dieser Ansicht erhalten Sie eine Liste aller eingestellten Appium-Capabilities. Zu dieser können Sie weitere hinzufügen, Einträge ändern oder entfernen. Um eine Capability hinzuzufügen, wählen Sie diese aus der Drop-down-Liste des Eingabefelds aus. In dieser befinden sich alle bekannten Capabilities sortiert in die Kategorien ''Common'', ''Android'' und ''iOS''. Haben Sie eine Capability ausgewählt, wird ein kurzer Informationstext dazu angezeigt. Sie können in das Feld auch von Hand eine Capability eingeben. Klicken Sie dann auf "''Hinzufügen''", um die Capabilitiy in die Liste einzutragen. Dort können Sie in der rechten Spalte den Wert setzen. Um einen Entrag zu löschen, wählen Sie diesen aus und klicken Sie auf "''Entfernen''". Mit "''Zurück''" verlassen Sie die erweiterte Ansicht.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Laufende Appium-Server ==
Im Menü des Mobile Testing Plugins finden Sie den Eintrag "''Appium-Server...''". Mit diesem öffnen Sie ein Fenster mit einer Übersicht aller Appium-Server, die von expecco gestartet wurden und auf welchem Port diese laufen. Durch Klicken auf das Icon in der Spalte "''Log anzeigen''" können Sie das Logfile des entsprechenden Servers anschauen. Dieses wird beim Beenden des Servers wieder gelöscht. Mit den Icons in der Spalte "''Beenden''" kann der entsprechenden Server beendet werden. Allerdings wird dies verhindert, wenn expecco über diesen Server noch eine offene Verbindung hat. Für welche Verbindung ein Server verwendet wird, sehen Sie in der rechten Spalte. Steht dort ''<idle>'' wird er zur Zeit nicht von expecco verwendet.

[[Datei:MobileTestingAppiumServer.png]]

Beim Öffnen des Editors um eine Appium-Verbindung aufzubauen, wird direkt ein Appium-Server gestartet, um den folgenden Verbindungsaufbau zu beschleunigen. Zu diesem Zweck hält sich expecco auch immer einen freien Appium-Server offen. Weitere laufende Server, die nicht mehr verwendet werden, werden jedoch nach einiger Zeit automatisch beendet.

Im Menü des Mobile Testing Plugins finden Sie auch den Eintrag "''Alle Verbindungen und Server beenden''". Dies ist für den Fall gedacht, dass Verbindungen oder Server auf andere Weise nicht beendet werden können. Beenden Sie Verbindungen wenn möglich immer im GUI-Browser oder durch Ausführen eines entsprechenden Bausteins. Server, die Sie in der Server-Übersicht gestartet haben, beenden Sie dort; Server, die mit einer Verbindung gestartet wurden, werden automatisch mit dieser beendet.

Beachten Sie, dass in der Übersicht nur Server aufgelistet sind, die von expecco gestartet und verwaltet werden. Mögliche andere Appium-Server, die auf andere Art gestartet wurden, werden nicht erkannt.

== Recorder ==
Besteht im GUI-Browser eine Verbindung zu einem Gerät, kann der integrierte Recorder verwendet werden, um mit diesem Gerät einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

[[Datei:MobileTestingRecorder.png|caption|]]

====Komponenten des Recorderfensters====
#'''Aufnahme fortsetzen/pausieren''': Über das rechte Symbol können Sie die Aufnahme pausieren. Sie sehen dann ein großes Pause-Symbol in der Anzeige. Alle Aktionen, die Sie währenddessen im Recorder machen werden zwar ausgeführt, es werden aber keine Bausteine aufgezeichnet. Über das linke Symbol können Sie dann wieder in den normalen Aufnahmemodus wechseln.
#'''Aufnahme stoppen''': Stoppt die Aufnahme und schließt das Recorderfenster.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Gerät. Dies wird nötig, wenn das Gerät zur Ausführung einer Aktion länger braucht oder sich etwas ohne das Anstoßen durch den Recorder ändert. Seit expecco 21.2 gibt es hier zusätzlich ein Untermenü, mit dem automatisches Aktualisieren angeschaltet werden kann, indem im Hintergrund auf Änderungen geprüft wird (siehe auch ''Automatisches Aktualisieren'' weiter unten).
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Elemente einzeichnen''': Die Rahmen aller Elemente der Ansicht werden angezeigt.
#'''Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst. Dabei stehen folgende Aktionen zur Verfügung:
#*Aktionen auf Elemente:
#**Klicken: Kurzer Klick auf das Element, über dem der Cursor steht. Zur genaueren Bestimmung, welches Element verwendet wird, benutzen Sie die Funktion Follow-Mouse oder Element-Highlighting.
#**Antippen mit Dauer (Element): Ähnlich zum Klicken, nur dass zusätzlich die Dauer des Klicks aufgezeichnet wird. Dadurch sind auch längere Klicks möglich.
#**Antippen mit Position (Element): Ähnlich zum Klicken, aber zusätzlich wird die Position innerhalb des Elements aufgenommen. Die Position kann relativ zur Größe des Elements aufgenommen werden oder, wenn Sie dabei Strg gedrückt halten, absolut zur linken oberen Ecke des Elements.
#**Text setzen: Ermöglicht das Setzen eines Textes in Eingabefelder.
#**Text löschen: Löscht den Text eines Eingabefelds.
#*Aktionen auf das Gerät:
#**Antippen (Bildschirm): Löst einen Klick auf die Bildschirmposition aus.
#**Antippen mit Dauer (Bildschirm): Löst einen Klick auf die Bildschirmposition aus, bei dem auch die Dauer berücksichtigt wird.
#**Wischen: Wischen in einer geraden Linie vom Punkt des Drückens des Mausknopfes bis zum Loslassen. Die Dauer wird ebenfalls aufgezeichnet.
#:Beachten Sie bei diesen Aktionen, dass das Ergebnis sich auf verschiedenen Geräten unterscheiden kann, bspw. bei verschiedenen Bildschirmauflösungen.
#*Erstellen von Testablauf-Bausteinen
#**Attribut prüfen: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Das Ergebnis triggert den entsprechenden Ausgang.
#**Attribut zusichern: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Bei Ungleichheit schlägt der Test fehl.
#**Attribut holen: Liest den aktuellen Wert eines Attributs aus.
#*Automatisch
#:Ist das Auto-Werkzeug ausgewählt, können alle Aktionen durch spezifische Eingabeweise benutzt werden: ''Klicken'', ''Element antippen'' und ''Wischen'' funktionieren weiterhin durch Klicken, wobei sie anhand der Dauer und der Bewegung des Cursors unterschieden werden. Um ein ''Antippen'' auszulösen, halten Sie beim Klicken Strg gedrückt. Die übrigen Aktionen erhalten Sie durch einen Rechtsklick auf das Element in einem Kontextmenü.
#'''Kontext-Aktionen''': Hier können Sie Aktionen aufzeichnen, die Kontexte betreffen:
#*Zu Kontext wechseln: Bietet eine Liste der aktuell verfügbaren Kontexte und Sie können auswählen, zu welchem gewechselt werden soll.
#*Aktuellen Kontext holen: Holt den Handle des aktuellen Kontexts.
#*Kontext-Handles holen: Holt eine Liste aller aktuell verfügbaren Kontext-Handles.
#'''Softkeys''': Nur unter Android. Simuliert das Drücken der Knöpfe Zurück, Home, Fensterliste und Power.
#'''Home-Button''': Nur unter iOS ab expecco 2.11. Ermöglicht das Drücken des Home-Buttons. Vor expecco 19.2 funktioniert es nur, wenn AssistiveTouch aktiviert ist und sich das Menü in der Mitte des oberen Bildschirmrands befindet. Ab expecco 19.2 verwendet die Funktion kein AssistiveTouch mehr.
#'''Hilfe''': Öffnet diese Online-Dokumentation auf der allgemeinen Seite zu [[GuiBrowser_Recorder|GUI-Browser Recordern]].
#'''Anzeige''': Zeigt einen Screenshot des Geräts. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Ansicht anpassen''': Öffnet einen Dialog um die Ansicht anzupassen, falls expecco das Bild nicht richtig darstellt. Sie können die Skalierung anpassen oder das Bild um 90° drehen.
#'''Ausrichtung anpassen''': Korrigiert das Bild, falls dieses auf dem Kopf stehen sollte. Über den Pfeil rechts daneben kann das Bild auch um 90° gedreht werden, falls dies einmal nötig sein sollte. Ab expecco 19.1 finden Sie diese Funktion in ''Ansicht anpassen''. Die Ausrichtung des Bildes ist für die Funktion des Recorders unerheblich, dieser arbeitet ausschließlich auf den erhaltenen Elementen.
#'''Skalierung''': Ändert die Skalierung des Screenshots.
#'''Meldungen''': Zeigt den Pfad des ausgewählten Elements oder andere Meldungen an. Es gibt ein Kontextmenü, um eine Liste der vorigen Meldungen zu sehen.

====Verwendung====
Mit jedem Klick im Fenster wird eine Aktion ausgelöst und im Arbeitsbereich des GUI-Browsers aufgezeichnet. Dort können Sie das Aufgenommene abspielen, editieren oder daraus einen neuen Baustein erstellen.
Aktionen zum Auslösen von Sofkeys finden Sie direkt in der Menüleiste (s.o.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Werkzeugs in der Menüleiste (s.o.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion.
Zur Verwendung des Recorders lesen Sie auch Schritt 2 im Tutorial ([[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen|Android]] bzw. [[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen_.28iOS.29|iOS]]).

====Elemente verbergen====
Ab expecco 21.2 gibt es im Kontextmenü außerdem die Möglichkeit, das ausgewählte Element im Recorder zu verbergen. Das bedeutet, dass dieses Element fortan nicht mehr ausgewählt werden kann. Diese Funktion eignet sich dazu, Elemente zu ignorieren, die im Vordergrund liegen, um auf Elemente darunter zugreifen zu können. Um diesen Zustand wieder rückgängig zu machen, müssen Sie das entsprechende Element im Baum des GUI-Browsers finden, dort gibt es im Kontextmenü ebenfalls einen solchen Eintrag.

====Automatisches Aktualisieren====
Der Recorder zeigt kein Livebild des Geräts sondern nur eine Momentaufnahme. Um mit der Anzeige auf dem Gerät übereinzustimmen muss daher nach Änderungen aktualisiert werden. Der Recorder aktualisiert sich automatisch, nachdem er eine Aktion ausgeführt hat. Ab expecco 20.2 sind zudem weitere automatische Updates möglich. Sie können Sie im Menü ''Fenster'' aktivieren.

Zum einen kann kurze Zeit nach dem Ausführen einer Aktion überprüft werden, ob es noch Änderungen nach der ersten Aktualisierung gegeben hat, damit in diesem Fall eine zweite Aktualisierung stattfinden kann. Dies soll das Problem beheben, dass der Recorder nach einer Aktion nicht aktuell ist, weil die Aktualisierung zu früh stattgefunden hat.

Zum anderen kann eine periodische Aktualisierung eingeschaltet werden. Nach einem einstellbaren Interval wird der Recorder automatisch aktualisiert, sollte es Änderungen geben. Dadurch ist die Anzeige im Recorder immer weitgehend aktuell, allerdings entsteht dadurch auch ein Mehraufwand was die Kommunikation mit dem Gerät betrifft.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid-Apps und WebViews =

'''!!! WICHTIGER HINWEIS - Wenn Sie Probleme haben, auf den Webview zu wechseln, geben Sie bitte unter den Android Einstellungen - Apps -Standard Apps "Chrome" als "Browser-App" an !!!
'''

Hybrid-Apps enthalten neben den Plattform-nativen Elementen weitere Elemente, die in einen WebView eingebunden sind. Diese Elemente können ebenfalls bedient werden, allerdings muss zuvor in den entsprechenden Kontext gewechselt werden. Mit dem Baustein "''Get Current Context''" erhalten Sie den aktuellen Kontext. Zu Beginn ist dies "''NATIVE_APP''", also der Kontext der nativen Elemente. Mit dem Baustein "''Get Context Handles''" bekommen Sie eine Collection aller vorhandenen Kontexte. Gibt es einen WebView-Kontext, so heißt dieser "''WEBVIEW_1''" oder "''WEBVIEW_<package>''" mit dem Paket des WebViews. Es kann auch mehrere WebView-Kontexte geben. Zu jedem WebView-Kontext gibt es im nativen Kontext ein entsprechendes WebView-Element. Mit dem Baustein "''Switch to Context''" können Sie in einen solchen Kontext wechseln und haben fortan nur Zugriff auf die Elemente in diesem Kontext.

Im GUI-Browser werden zum einen oben im Baum die vorhandenen Kontexte angezeigt, zum anderen wird der Baum eines Kontexts unterhalb des entsprechenden WebView-Elements eingefügt.

= XPath anpassen mithilfe des GUI-Browsers =
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen "''GTIN-13 (EAN-13)''" und "''Verify''", das Eingabefeld der Zahl "''4006381333986''" und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des "''GTIN-13''"-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch "''Pfad überprüfen''" (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit "''Verify Path: OK''" (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit "*" zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert "''GTIN-13 (EAN-13)''" besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer "''hierarchy''" (für iOS wäre es "''AppiumAUT''"), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix "''android.widget.''", das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend "''XCUIElementType''" am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. "''FrameLayout''" ist ein Kindelement von "''hierarchy''", "''LinearLayout''" ist ein Kind von "''FrameLayout''" usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element "''hierarchy''" beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben "''TextView''"-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ "''Button''" gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut "''resource-id''". Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut "''name''" verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem "@" eingeleitet und der Wert mit einem "=" in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter "''Test''" eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf "''Lauf''". Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu "''Eigenschaften''", wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

== Weitere Locator-Strategien ==
Appium bietet neben XPath noch weitere Strategien zur Adressierung von Elementen an. Einige davon stehen Ihnen '''ab Version 20.1''' ebenfalls mit expecco zur Verfügung. Diese sind nicht ganz so mächtig wie XPath, dafür aber häufig schneller bei der Auflösung auf dem Gerät. Insbesondere bei der Verwendung mit iPhones, wo die Hierarchie bei jeder XPath-Auflösung erst aufgebaut werden muss, bieten alternative Strategien einen Vorteil für die Laufzeit.

XPath ist weiterhin der Standard, das heißt alle Locator ohne besondere Angabe werden als XPath interpretiert. Um eine der anderen Strategien zu verwenden, schreiben Sie diese mit einem Gleichzeichen vor den gewünschten Locator. Diese Technik können Sie sowohl an den Blöcken verwenden, als auch im GUI-Browser testen.

{|
|-
| style="vertical-align:top" | AccessibilityId || style="padding-bottom:0.5em" | Verwendet den Wert des Elements, der dazu dient, die App barrierefrei zu machen. Für iOS ist das das Attribut '''Accessibility-id''', für Android das Attribut '''content-descr'''. ''Beispiel: accessibilityId=Löschen''
|-
| style="vertical-align:top" | className || style="padding-bottom:0.5em" | Verwendet den Namen der Klasse des Elements. ''Beispiel: className=android.widget.FrameLayout''
|-
| style="vertical-align:top" | id || style="padding-bottom:0.5em" | Verwendet die Kennung des Elements. Für iOS ist das das Attribut '''name''', für Android das Attribut '''resource-id'''. ''Beispiel: id=android:id/text1''
|-
| style="vertical-align:top" | iOSClassChain1 || style="padding-bottom:0.5em" | Verwendet die Hierarchie der Elemente ähnlich wie bei XPath. Eine Erklärung zum Aufbau finden Sie [https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules hier]. ''Beispiel: iOSClassChain=XCUIElementTypeWindow/XCUIElementTypeButton[`label == "Ok"`]''
|-
| style="vertical-align:top; padding-right:1em" | iOSNsPredicateString1 || style="padding-bottom:0.5em" | Verwendet einfache Kriterien, wie Attribute, die auch kombiniert werden können. ''Beispiel: iOSNsPredicateString=type == 'XCUIElementTypeButton' AND name == 'Weiter'''
|-
| style="vertical-align:top" | name1 || style="padding-bottom:0.5em" | Verwendet den Namen des Elements. ''Beispiel: name=Bestätigen''
|-
|}

:1 ''nur für iOS''

Um eine direkte Beschleunigung mit iOS zu erzielen, ohne dass Sie Ihre bisherigen Pfade anpassen müssen, wandelt expecco zudem Pfade, die nur aus einem Element mit Klasse und name-Attribut bestehen, zur Laufzeit automatisch in einen entsprechenden Locator der Strategie iOSNsPredicateString um. Wenn Sie einen Pfad explizit als XPath markieren, wird diese Anpassung nicht vorgenommen.

=Probleme und Lösungen=
== Locator sind versionsabhängig oder variabel ==
Dann sollten Sie die Locator (xPath) entweder in einer Variablen halten oder ein Locator-Mapping in einem Screenplay Anhang definieren. Es ist auch möglich, lediglich Teile des Locators (z.B. Locator-Pfad eines Elternelements oder Attributwert) in einer Variable zu halten und im Freezevalue des Locator-Pins mit "''$(varName)''" einzufügen.

==Unsichtbare UI-Elemente==
Beachten Sie, dass im [[#Recorder|Recorder]] auch Elemente berücksichtigt werden, die Sie auf dem Bildschirm nicht sehen. Schalten Sie daher das Element-Highlighting an oder nutzen Sie die Follow-Mouse-Funktion und den Elementbaum im GUI-Browser, um festzustellen, ob das richtige Element verwendet wird. Es kann vorkommen, dass unsichtbare Elemente vor anderen Elementen liegen und diese verdecken, so dass die gewünschten Elemente im Recorder nicht ausgewählt werden können. Lesen Sie dazu den Abschnitt [[#Elemente_verbergen|Elemente verbergen]].

==''org.openqa.selenium.StaleElementReferenceException''==
Der Fehler <code>org.openqa.selenium.StaleElementReferenceException</code> tritt immer dann auf, wenn ein Element verwendet wird, das nicht mehr da ist. Wenn das in Ihrem Test passiert und das Element eigentlich da sein sollte, verwenden Sie an der Stelle stattdessen den Locator (XPath), um das Element neu zu holen.

In manchen Fällen kann dieser Fehler auch dann auftreten, wenn Sie am Baustein bereits Locator angegeben haben. Das liegt daran, dass immer zuerst der Locator aufgelöst und das entsprechende Element geholt wird und dann die Aktionen mit dem Element ausgeführt wird. Wenn die App das Element genau zwischen dem Zeitpunkt des Auflösens und Holens und der Ausführung der Aktion aktualisiert und dabei ein neues Element erzeugt, kommt es zu diesem Fehler. Passiert das an einer bestimmten Stelle in Ihrem Test, bleibt nichts anderes als den Fehler abzufangen und es erneut zu versuchen.

==iOS: Kabel nicht zertifiziert==
In manchen Fällen erscheint beim Verbinden eines iOS-Geräts über USB der Hinweis, das verwendete Kabel sei nicht zertifiziert. In diesem Fall hilft es nur, das entsprechende Kabel auszutauschen.
==iOS: Alerts beim Verbindungsaufbau==
Stellen Sie sicher, dass beim Verbindungsaufbau mit einem iOS-Gerät keine Alerts geöffnet sind. Der Aufbau schlägt sonst fehl, da die App nicht in den Vordergrund kommen kann. Siehe auch [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Gerät und App vorbereiten]].

==iOS: .ipa installieren nicht möglich==
Beachten Sie, dass auf iOS-Simulatoren keine ''.ipa''-Dateien sondern nur ''.app''-Dateien installiert werden können.

==iOS: Erster Verbindungsaufbau funktioniert nicht==
Wenn auf Ihrem Mac noch kein signierter Build des WebDriverAgents liegt, muss dieser beim ersten Verbindungsaufbau erst erzeugt werden. Das kann in der Regel etwas länger als eine Minute dauern. Standardmäßig verwendet Appium aber einen Timeout von 60000 ms um zu warten bis der WebDriverAgent auf dem Gerät startet, so dass der Aufbau in diesen Fällen abgebrochen wird. Sie können den Timeout mit der Capability ''wdaLaunchTimeout'' setzen, z.B. auf ''120000''.

Außerdem müssen die Einstellungen für die Signierung passen. Am zuverlässigsten funktioniert das nach unserer Erfahrung, wenn man im Xcode-Projekt des WebDriverAgents auf automatische Signierung stellt und das Team setzt. Siehe dazu die Erklärung im Abschnitt [[#WebDriverAgent-Signierung|WebDriverAgent-Signierung]]. In diesem Fall sollten Sie die Capabilities ''xcodeConfigFile'' bzw. ''xcodeOrgId'' und ''xcodeSigningId'' '''nicht''' verwenden, da es sonst zu Konflikten kommen kann. Achtung: Wenn Sie eine Team-ID in den Mobile-Testing-Einstellungen gesetzt haben, setzt expecco diese automatisch als ''xcodeOrgId''!

Achten Sie beim ersten Verbindungsaufbau außerdem auf Ihr Gerät, da Sie dort möglicherweise der Installation per Passwort zustimmen müssen. Auf dem Mac kann die Eingabe des Passworts zur Freigabe des Schlüsselbunds für die Signierung nötig werden, häufig auch mehrmals.

==Android: Gerät nicht im Verbindungsdialog==
Wenn ein über USB angeschlossenes Android-Gerät nicht im Verbindungsdialog auftaucht, versuchen Sie, den USB-Verbindungstyp zu ändern. In der Regel sollten MTP oder PTP funktionieren. Prüfen Sie nochmal, ob "USB Debugging" in den Entwicklereinstellungen des Geräts aktiviert ist (diese Einstellungen sind bei manchen Geräten zunächst unsichtbar, und müssen durch einen Trick zugänglich gemacht werden). Siehe auch [[#Android-Ger.C3.A4t_vorbereiten|Android-Gerät vorbereiten]].

==Android: Abgeschnittene Elemente unten==
Bei Android-Geräten, die die Steuerungsleiste bzw. Softkeys automatisch ein- und ausblenden, kann es vorkommen, dass der Recorder im unteren Bereich Elemente abschneidet, die durch die Softkeys verdeckt würden, auch wenn sie zu diesem Zeitpunkt gar nicht angezeigt werden. In diesem Fall hift es, die Softkeys so einzustellen, dass sie in einer permanenten Leiste angezeigt werden.

Bei neueren Android-Versionen gibt es eine solche Einstellung in der Regel nicht. Auch wenn die Steuerelemente permanent eingeblendet sind, liegen sie auf keiner extra Leiste, sondern vor dem Inhalt der App. Es gibt dann im unteren Teil einen Bereich, der nicht bedient werden kann, weil er nicht zum aktiven Bereich der App gezählt wird, weshalb die Elemente von Appium abgeschnitten werden. Dieser Bereich kann auch größer sein als von den Steuerungselementen beansprucht. Bekannt ist dies für Samsung-Geräte mit Android 11. Da die Information über die Größe des App-Bereichs bereits auf Android-Ebene so geliefert wird, können wir hierfür keine Lösung anbieten, sondern können nur hoffen, dass das Problem vom Hersteller behoben wird. Sie können versuchen, ob Sie mit der Einstellung von Gestensteuerung bessere Ergebnisse bekommen, allerdings gibt es hier das gleiche Problem.

== Android: Test hängt beim Suchen eines Elements==
Der Baustein ''Find Element by XPath'' und alle Element-Bausteine warten bis ein Element zum angegebenen Pfad auftaucht. Den Timeout dafür kann man entweder am Baustein direkt oder in den Umgebungsvariablen ändern. Wenn das Element aber bereits da sein sollte und es dennoch sehr lange dauert, bis der Test weitergeht, kann das am UIAutomator/UIAutomator2 liegen. Dieser wartet, bis die App in den Idle-Zustand geht, bevor er überhaupt nach Elementen sucht. Dies kann länger dauern, wenn die App z.B. im Hintergrund noch Animationen abspielt oder andere Aktionen ausführt. Auch das Holen des Page-Sources z.B. beim Aktualisieren im GUI-Browser oder im Recorder kann dadurch länger dauern. Standardmäßig gibt es hierfür einen Timeout von 10 Sekunden, nach dem nicht weiter auf den Idle-Zustand gewartet wird. Dieser Timeout lässt sich durch eine Einstellung in Appium anpassen (waitForIdleTimeout). Falls Sie einen anderen Wert für diesen Timeout setzen möchten, ist dies ab expecco 21.2 möglich, indem Sie vor dem Test den Smalltalk-Code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> ausführen. Der Timeout wird in Millisekunden angegeben, das Beispiel setzt ihn also auf 2 Sekunden.

==Android: Aktualisieren des Trees oder Wechseln zum Webview-Kontext braucht zu lange==
Speziell mit älteren Geräten kann es vorkommen, dass neuere Chromedriver nicht initialisiert werden können. Das führt dann dazu, dass nicht in den Webview-Kontext gewechselt werden kann. Dies wird von Appium allerdings nur über einen Timeout festgestellt, der standardmäßig bei 4 Minuten liegt. Da expecco auch beim Aufbauen des Trees im GUI-Browser versucht in den Webview-Kontext zu wechseln, kann das zu sehr langen Ladezeiten führen. Da es in Appium keine Möglichkeit gibt, diesen Timeout herunter zu setzen, haben wir die Version, die wir im MobileTestingSupplement bereitstellen, um eine entsprechende Capability erweitert. Ab der Version 1.13.1.0 des [[#Windows|MobileTestingSupplements]] kann mit ''chromedriverStartTimeout'' der Timeout in Millisekunden gesetzt werden. Der Wechsel funktioniert dadurch zwar trotzdem nicht, aber expecco braucht dann nicht mehr so lange beim Aktualisieren des Trees und der Baustein zum Wechseln des Kontextes schlägt schneller fehl. Der Verbindungsdialog fügt diese Capability ab expecco 22.1 automatisch hinzu.

==Keine Aktion bei Klick==
Der Baustein zum Klicken auf ein Element ist erfolgreich, aber auf dem Gerät wurde keine Aktion ausgeführt.
:Dies kann vorkommen, wenn das Element von einem anderen Element verdeckt ist und ein Klick auf das Element deshalb nicht möglich ist. In diesem Fall wird von Appium kein Fehler geworfen, sondern es passiert einfach nichts. Wenn Sie dennoch einen Klick an der Position des Elements machen möchten, auch wenn es verdeckt ist, benutzen Sie stattdessen den Baustein ''Tap'' und übergeben Sie diesem die Position des Elements (''Get Location''). Wenn Sie stattdessen vor einem Klick prüfen möchten, ob das Element zu diesem Zeitpunkt verdeckt ist, versuchen Sie, ob Ihnen die Eigenschaften ''Is Displayed'' oder ''Is Enabled'' weiterhelfen.

==Kein Update nach Aktion==
Über den Recorder wurde eine Aktion ausgeführt, für die auch ein Baustein aufgezeichnet wurde, der Recorder zeigt aber immer noch das alte Bild.
:Der Recorder zeigt kein Livebild des Geräts, sondern immer nur eine Momentaufnahme. Nachdem eine Aktion ausgeführt wurde, aktualisiert sich der Recorder automatisch. Es kann aber vorkommen, dass das Bild schon aktualisiert wurde, bevor die Auswirkungen der Aktion auf dem Gerät vollständig abgeschlossen sind. In diesem Fall sollten Sie den Recorder von Hand aktualisieren über das Symbol mit den blauen Pfeilen. Ab expecco 20.2 können Sie für diesen Fall auch automatisches Aktualisieren einstellen. Siehe auch Beschreibung zum [[#Recorder|Recorder]].

=="clickable" Attribut falsch==
Ein Element hat im "''clickable''" Attribut/Property den Wert "''false''", ist aber dennoch anklickbar.
:Das "''clickable''" Attribute muss explizit vom App-Programmierer gesetzt werden, und hat tatsächlich keine Relevanz für das tatsächliche Verhalten der App. Sie sollten dieses Attribut i.A. in Ihren Tests nicht beachten. Leider existieren viele Apps, bei denen der Programmierer hier "lazy" war.

==Verbindungsaufbau schlägt fehl==
Schlägt der Verbindungsaufbau mit dem Appium-Server fehl, erhalten Sie in expecco eine Fehlermeldung ähnlicher der unten abgebildeten.

[[Datei:MobileTestingVerbindungsfehler.png]]

Hier sehen Sie die Art des aufgetretenen Fehlers. Klicken Sie auf "''Details''" um nähere Informationen zu erhalten. Mögliche Fehler sind:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:Der angegebene Server läuft nicht oder ist nicht erreichbar. Überprüfen Sie die Serveradresse.
*''org.openqa.selenium.WebDriverException''
:Lesen Sie in den Details in der ersten Zeile die Meldung hinter ''Original Error'':
:*''Unknown device or simulator UDID''
::Entweder ist das Gerät nicht richtig angeschlossen oder die udid stimmt nicht.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::Dieser Fehler kann verschiedene Ursachen haben. Entweder konnte tatsächlich der WebDriverAgent nicht gebaut werden, weil die Signierungseinstellungen falsch sind oder das passende Provisioning Profile fehlt. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]]. Es kann auch sein, dass der WebDriverAgent auf dem Gerät nicht gestartet werden kann, weil sich beispielsweise ein Alert im Vordergrund befindet oder Sie dem Entwickler nicht vertraut haben.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::Die angegebene App kann nicht auf dem iOS-Gerät installiert werden, weil es nicht im Provisioning Profile der App eingetragen ist.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.'''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die Datei unter dem angegebenen Pfad auf dem Mac befindet.
:*''packageAndLaunchActivityFromManifest failed.''
::Die angegebene ''apk''-Datei ist vermutlich kaputt.
:*''Could not find app apk at [...]''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die ''apk''-Datei am angegebenen Pfad befindet.

Falls der Fehler nicht durch eine der oben gelisteten Ursachen bedingt ist, kann es sein, dass die auf dem Gerät befindlichen Automation-Anwendungen nicht mehr richtig funktionieren. Hier hilft es, diese vom Mobilgerät zu deinstallieren. Beim nächsten Verbindungsaufbau werden sie dann automatisch neu installiert.

*Für iOS-Geräte ist das der WebDriverAgent, den Sie einfach vom Home-Screen deinstallieren können. Dies behebt in der Regel Probleme durch den Wechsel des verwendeten Macs oder der Xcode-Version.

*Für Android-Geräte ist es der UIAutomator2; hier tritt auf einigen Geräten sporadisch ein Problem auf, die Ursache dafür ist uns z.Z. noch nicht bekannt. Zur Deinstallation navigieren Sie auf dem Gerät zu "''Einstellungen''" > "''Anwendungen''"* und suchen in der Liste nach folgenden Einträgen:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Klicken Sie auf die jeweilige Anwendung und dann auf "''Deinstallieren''".
*''Der entsprechende Eintrag heißt auf manchen Geräten möglicherweise etwas anders.''

Falls dies nicht hilft, kann eventuell die Ausgabe des Appium-Servers weiterhelfen. Für einen von expecco gestarteten Server finden Sie das Log in der Liste der [[#Laufende_Appium-Server|laufenden Appium-Server]].

==Ich habe keinen Mac==
Vielleicht hilft Ihnen diese Webseite weiter: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin/en

2024-07-23T09:48:46Z

Matilk: /* Problems and Solutions */ org.openqa.selenium.StaleElementReferenceException

[[Mobile_Testing_Plugin|Deutsche Version]] | '''English Version'''

= Introduction =
The ''Mobile Testing Plugin'' adds mechanisms to test and automate Android and iOS devices. This includes both real and emulated devices - it does not matter whether real mobile devices or emulated devices are used. The plugin can (and usually is) used in conjunction with the [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]], which supports the creation of tests. It can also be used to record test procedures.

[http://appium.io/ Appium] is used to connect to the devices. Appium is a free open source framework for testing and automating mobile applications.

We recommend to go through the [[Mobile_Testing_Tutorial/en|Tutorial]] to familiarize yourself with the Mobile Plugin. This tutorial leads step by step through the creation of a test case using an example and explains the necessary basics.

= Installation and Setup =
To use the ''Mobile Testing Plugin'', you must have installed expecco together with the corresponding plugin, and you need the appropriate licenses. expecco communicates with the mobile devices via an Appium server, which either runs on the same computer as expecco, or on a second computer. This must be accessible for expecco.

== Installation Overview ==
'''Computer running expecco:'''
* Java JDK version 8, 9, 10 or 11
'''Computer connected to Android devices :'''
* Appium Server, you can install it via the Mobile Testing Supplement (see below), of which we regularly provide a new version
* Android SDK, you can also get it with the Mobile Testing Supplement
* Java JDK version 8, 9, 10 or 11
'''Computer connected to iOS devices*:'''
* Appium Server, you can install it via the Mobile Testing Supplement for MacOS (see below), of which we regularly provide a new version
* Xcode in a version that supports the iOS version used, available from the Apple App Store
* Java JDK version 8, 9, 10 or 11
* Apple Developer Certificate incl. matching private key (to sign the WebDriverAgent)
* Provisioning Profile for the mobile devices to be used

* Please note that due to the requirements (no connection to non-Apple devices available) iOS devices can only be controlled from a Mac.

Depending on the setup, the above-mentioned computers can also be the same device. expecco can either connect to a remote Appium Server and mobile devices connected to it via the network, or start an Appium Server locally itself and use it with local mobile devices. However, some of expecco's functions that make it easier to create test cases are only available if the mobile devices are connected to the same computer on which expecco is running. A possible setup may therefore look like the following figure:

[[Datei:MobileTestingAufbau.png | 400px]]

The following explains how to install Appium and other necessary applications for Windows and Mac OS.

== Windows ==
The easiest way is to install everything from our Mobile Testing Supplement. However, newer versions do not contain a JDK anymore due to a change in Oracle's license terms, so you have to install it additionally. Of course, you are free to install Appium directly to use the version you want. However, to then be able to start an Appium server with expecco, a suitable batch file must be available and specified in the [[Mobile_Testing_Plugin/en#Plugin_Configuration|settings]]. However, connections can also be established to other running Appium servers.
*'''expecco 24.1''': [https://download.exept.de/transfer/h-expecco-24.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.3]
:Same versions as in the predecessor, but with updated chromedriver versions
*expecco 23.2: [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Same versions as in the predecessor, but with updated chromedriver versions
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Same versions as in the predecessor, but the installer now allows to add Appium to the Autostart.
*expecco 22.2 and 22.1: [https://download.exept.de/transfer/h-expecco-22.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 from platform-tools 33.0.2
:''* We added the capability'' startChromedriverTimeout ''to Appium, to get a timeout earlier, if Chromedriver cannot be initialized. (see [[#startChromedriverTimeout|Problems and Solutions]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Contains Appium version 1.22.0, Node still is version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Only minor changes compared to the previous version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Compared to the previous version, Appium was updated to version 1.16.0-rc.1 and node 12 is used.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:This installs Appium in the version 1.12.0 and now additionally contains build-tools in the version 28.0.3 in the android-sdk. Apart from this, it is the same as the previous version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:This installs Appium in the version 1.8.1. In addition, an installation of ''Android Debug Bridge'' and ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) is offered. This covers drivers for a broad range of Android devices, and you won't have to install an individual driver for each device. A '''JDK is not contained anymore (due to a change in Oracle's license terms)''', you have to download it on your own, e.g. from [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: same procedure as for expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:This installs a Java JDK Version 8, android-sdk and Appium Version 1.6.4. The supplement also offers a universal adb driver ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]). This driver supports a wide range of Android Devise, and avoids the need to search for individual device-specific drivers.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:It installs a Java JDK version 8, android-sdk and Appium version 1.4.16. During the installation the graphical user interface of Appium is started, you can close this window immediately. The supplement also offers a universal adb driver (ClockworkMod). This combines drivers for a wide range of Android devices so that you do not have to search for and install a separate driver for each device.

If expecco has to use mobile devices that are connected to another computer, you have to start an Appium server there. You can do this by using the file <code>appium_standalone.cmd</code>. The server is then started on default port 4723. If you want to use a different port number, start the server with

appium_standalone.cmd -p <portnummer>

The server is ready, as soon as the line
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
is displayed, where you can read the used port number at the end.

If your Android device is connected to a remote machine,
you may want to see the live screen locally using a tool like
[https://github.com/Genymobile/scrcpy scrcpy].

When Appium is started for the first time – either standalone or by expecco – it may happen that the Windows firewall blocks access to the node server. Allow the access or Appium cannot be started.

== Mac OS ==
Note: the following can be ignored if you do not plan to test iOS (iPhone) devices. The Mac setup is not needed for Android devices.

=== Xcode ===
Automation with iOS devices needs [https://developer.apple.com/xcode/ Xcode]. You can install it from the App Store. Please make sure that the version matches the tested iOS versions.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
This table is only a simplified overview, better see [https://xcodereleases.com/ Xcode releases] or [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode versions] for the exact versions. For new iOS minor versions, there is usually also a new release of Xcode, e.g. for iOS 10.2 you need at least Xcode 8.2, for iOS 10.3 at least Xcode 8.3, etc. So if you are upgrading to a newer iOS version, you will usually need a newer Xcode version as well. Newer versions of Xcode may not run on older operating systems, which in turn may require an operating system upgrade. If you also want to test older iOS versions, it can be useful to install the corresponding Xcode versions in parallel.

=== Appium ===
You can install Appium either as command-line tool or use it with [https://github.com/appium/appium-desktop Appium Desktop], which provides a GUI to start the server. Meanwhile there is also Appium 2.0, which is not tested with expecco yet and therefore not recommended to use.

==== Appium Desktop ====
Download the newest version of [https://github.com/appium/appium-desktop/releases/ Appium Desktop]. For the Mac, it is best to take the dmg file and install it to the applications. When starting ''Appium Server GUI'' you will probably get the error message, that it is not possible for security reasons. In this case, open the context menu of the app file (right click or Ctrl + click) and choose ''Open'' there. Then confirm that you really want to open the application. From now on you can open the application normally.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Since Xcode 14 there are problems with signing the WebDriverAgent, which Appium loads on the device for the automation. This means that no connection is possible with version 1.22.3-4 of Appium Desktop. In newer versions of WebDriverAgent, this problem is solved, but currently there is no version of Appium Desktop using such a new version (as of November 2022). However, you can manually download a new version (e.g. 4.10.2) and replace the files in Appium. To do this, download one of the two archive files (zip or tar.gz) containing the source code from the [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent download page]. Then open and extract this file. Copy the contents of the folder ''WebDriverAgent-4.10.2' to

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

If you navigate there by Finder, make a context click (right click or Ctrl + click) on the application and choose ''Show Package Contents'' from the menu. Replace all files that are already present with the same name.

==== Install Appium using npm ====
You can install Appium using npm (Node Package Manager) as well. To do this, you have to install node/npm first. This can be done using [https://github.com/nvm-sh/nvm nvm] (Node Version Manager), which you can get on Github. If the following installation instructions should not work for you, you will find detailed information in the [https://github.com/nvm-sh/nvm#readme Readme] there.

Open a Terminal window. Then clone the Github repository of nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
and load it
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Then execute
command -v nvm
to see if it works. It should print ''nvm''. If there is no response, execute
touch ~/.zshrc
and try again.

Now you can install node with the following command.
nvm install 16.15.1
As there are problems installing Appium using the newest version of node, we recommend this version.

After node is installed, you can use it to install Appium:
npm install -g appium

The Appium server now simply can be started with the command
appium
The output will then be written directly to the terminal.

This version also has problems with signing the WebDriverAgent, like explained in [[#Appium_Desktop | Appium Desktop]]. Therefore download a newer version of WebDriverAgent in this case as well and replace the old files. You will find them at
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
We provide older versions of Appium via the Mobile Testing Supplement for Mac OS, with which you can easily install it:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.2)]
:Contains Appium version 1.18.3 and uses node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.0)]
:Only a few changes compared to the previous version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.98)]
:Appium is updated to version 1.16.0-rc.1 and node 12 is used.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.96)]
:This version contains Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.94)]
:This version contains Appium 1.8.0.

* expecco 2.11:[http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.0.94)]
:This version contains Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement for Mac OS]
:Diese Version entält Appium 1.4.16.

After you have downloaded the supplement, you can move it to a directory of your choice (e.g. your home directory) and unpack it there. A suitable command in a shell could look like this, adjust the version number accordingly:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

If your default Xcode installation is the one you want to use, you can start Appium directly from the file in the ''bin'' directory with the appropriate version number:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

If you want to use another Xcode than the one configured as default, you have to tell Appium the corresponding path by using the environment variable ''DEVELOPER_DIR''. For example, if you have installed Xcode in ''/Applications/Xcode-11.3.app'', you can start Appium this way:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

To find out what is set as the default Xcode installation on your system, use this command:

xcode-select -p

If Appium cannot find your Xcode installation, a message like this appears:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
In such a case, restart Appium by specifying a valid ''DEVELOPER_DIR''.

==== Signing WebDriverAgent ====
For automation, Appium installs an App called WebDriverAgent on the device and therefore has to be able to sign it. You need an Apple account and a respective certificate for this. For evaluation you can use a free account. This has the disadvantage that created profiles are only valid for one week and must be recreated afterwards. Also be careful when sharing the account, as certificates may be revoked or invalidated by automatic generation. As a result, apps that have already been signed can no longer be used.

If you already have a respective certificate and its associated private key in your keychain on the Mac, you can have the WebDriverAgent automatically signed. If not, it is recommended to set and manage the signing using Xcode.

First, connect the device you want to use to your Mac via USB. Make sure both the Mac and the device are in the same network or there will be problems when connection with Appium. Start Xcode and open ''Preferences''. Go to the Accounts page and create an entry with your account. You can then click on ''Manage Certificates...'' to see the certificates that belong to that account. To run tests, you need an iOS Development Certificate and the associated private key. If you do not already have one, create one. If you already have one, but it is not in your keychain (indicated by "Not in Keychain"), you can import it. You can do that by the [https://support.apple.com/en-us/guide/keychain-access/welcome/mac keychain access] on your Mac, if you have exported it previously from the keychain, where it is stored. The certificate with the associated key should be in the keychain ''Login''. It can be exported from there as PKCS#12 file (typical ending .p12). To import a certificate into your keychain, select the option ''Import objects'' from the ''File'' menu. If you don't know where the certificate is stored, you can also revoke it in Xcode and recreate it in your keychain. However, only do this if you know that the old certificate is no longer in use because it can no longer be used afterwards. Now the keychain should contain an iOS development certificate.


Now open the WebDriverAgent project in Xcode. If you have installed the Mobile Testing Supplement, you will find it in this directory at
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
If you have installed Appium Desktop, you will find it at
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''

You can use the Finder to navigate to the Xcode project file and open it by double clicking. Note, that you have to perform a context click (right click or Ctrl + click) on the Appium Server GUI app and select ''Show Package Contents'' in the menu, to get to its subdirectory.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Select ''WebDriverAgentLib'' and the page ''Signing & Capabilities''. In the section ''Signing'' set the option ''Automatically manage signing'' and then select a team. Now switch to ''WebDriverAgentRunner'' and do the same there.

By setting the team, the errors showing up for WebDriverAgentRunner should disappear. If Xcode should not be able to create a Provisioning Profile matching the Bundle ID ''com.facebook.WebDriverAgentRunner'', you can edit the latter so that it fits your certificate. After that you can quit Xcode or you can, like explained further below, directly start the build in Xcode, so the project will be already built when Appium wants to use it.

If you now connect to your device from expecco, the WebDriverAgent will be installed and started on it and then switch to the app to be tested. You may still have to trust the execution of the WebDriverAgent on the device. It maybe a sign that you have to do this, if the app WebDriverAgent first appears on the device and tries to start, but then is uninstalled again. To trust the execution, open the settings during the connection setup on the device and then the entry ''Device management'' under ''General''. This entry is only visible if a developer app is installed on the device. You may therefore have to wait until the WebDriverAgent is installed before the entry appears. Select the entry of your Apple account and trust it. Since the WebDriverAgent will be uninstalled again if the start did not work, you have to do this during the connection setup. If this is too hectic for you, you can also execute the following code:

xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

or
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

This installs the WebDriverAgent on the device without deleting it again.

If there are problems while installing the WebDriverAgent, you can also try and start the build in Xcode. Make sure the right target ''WebDriverAgent'' is selected. Error messages in Xcode might indicate easier what the problem is about. Sometimes it even helps to try for a second time, if it took too long for the first time and got aborted. It may occur, that you are asked several times during the build to enter the password for the keychain.

[[Datei:WebDriverAgentCodesign.png]]

Read also the documentation of Appium on [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Setting up tests with iOS devices]. Refer to the [https://support.apple.com/en-us/HT204460 Apple documentation] for details on installing and trusting of apps.

Once the WebDriverAgent is installed on the device, it will be reused for later connections und connecting should work faster. The signed version is then already on your Mac as well and doesn't have to be built again. This should speed up the connect with other devices as well. If you know, that the connect has to build and sign the WebDriverAgent first, it is advisable to set the capability ''wdaLaunchTimeout''. This timeout specifies how long Appium waits for the WebDriverAgents to start up on the device and is per default set to 60000 ms. Building often takes a little longer than one minute, so the connect attempt will be canceled. A value of 120000 will be more reliable here.

== Plugin Configuration ==
Before you start, please check the settings of the Mobile Testing Plugin and adjust them if necessary. Select the menu item "''Extras''" → "''Settings''" → "''Extensions''" → "''Mobile Testing''" (see fig.). By default, these paths are found automatically (1). To adjust a path manually, deactivate the corresponding check mark at the right. You'll see a drop-down list with some paths to choose from. If an entered path is wrong or cannot be found, the field is marked red and a message appears. Make sure that all paths are specified correctly.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Plugin Configuration]]

*'''appium''': Enter the path to the executable file with which Appium can be started in the command line. Under Windows this file will usually be called "<code>appium.cmd</code>". This path is used when expecco starts an Appium server.
*'''node''': Enter the path to the executable that starts Node (also called (also called "Node.js"). This path is passed to Appium when a server is started so that Appium can find it independently of the PATH variable. Under Windows this file is usually called "<code>node.exe</code>".
*'''JAVA_HOME''': Enter the path to a JDK (Java Development Kit)here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable. To specify which Java should be used by expecco, set this path in the Java Bridge settings.
*'''ANDROID_HOME''': Enter the path to an Android SDK here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable.
*'''adb''': The path to the adb command. Under Windows the file is called "<code>adb.exe</code>". This file is used by expecco, for example, to get the list of connected devices. This path should be selected automatically, if the command is found in the ANDROID_HOME directory. This is also used by Appium. If expecco and Appium use different versions of adb, conflicts may occur.
*'''android.bat''': This file is only needed to start the AVD and the SDK Manager, which deal with phone emulators. The file in the ANDROID_HOME directory will be selected automatically, if present there.
*'''aapt''': The path to the "aapt" command here. Under Windows this file is called "<code>aapt.exe</code>". expecco uses "aapt" only in the connection editor to read the package and activities of an "apk" file. The file in the ANDROID_HOME directory will be selected automatically, if present there.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | JDK Configuration]]

Starting with expecco 2.11, there is an additional field called ''Team ID''. If you run iOS tests, enter the Team ID of your certificate here. This is used for every iOS connection, unless you change the value in the connection settings in individual cases. For information on how to obtain the team ID, please refer to the section on [[#Signing| signing]] for installations on Mac OS. With expecco 2.10 and older, you can only enter the Team ID as capability for each connection setting separately. However, you must use the [[#Extended_View|extended view]] to do this. Enter the capability ''xcodeOrgId'' here and set the Team ID of the certificate as value.

The server address setting at the bottom of the page refers to the behavior of the connection editor. It checks at the end whether the server address ends in ''/wd/hub'' as this is the usual form. If not, a dialog asks how to react. The defined behavior can be viewed and changed here.

Also switch to the entry ''Java Bridge'' (see figure). Here you have to specify the path to your Java installation, which is used by expecco. Enter a JDK here. If you want to use the one from the Mobile Testing Supplement under Windows, the path is
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
You can also use the system settings.

== Prepare Android Device ==
If you connect an Android device under Windows, you may still need an adb driver for the device. You can usually find a suitable driver on the manufacturer's website. If you have installed the universal driver from the Mobile Testing Supplement, everything should already work for most devices. In some cases, Windows will automatically try to install a driver when you connect the device for the first time. 
'''Attention''': Before you can control a mobile device with the Appium plugin, you have to allow this debugging!

For Android devices, you can find this option in the settings under ''[https://developer.android.com/studio/debug/dev-options Developer Options]'' called ''USB-Debugging''. If the developer options are not displayed, you can unlock them by tapping Build Number seven times in About the Phone.

Also enable the ''Stay awake'' feature to prevent the device from turning off the screen during test creation or execution.

For security reasons, USB debugging must be allowed for each computer individually. When connecting the device to the PC via USB, you must agree to the connection on the device. If you haven't done this for your computer yet, but no corresponding dialog appears on the device, it may help to unplug and reconnect the device. This can happen especially if you have installed the ADB driver while the device was already connected via USB. If this doesn't help either, open the notifications by dragging them from the top of the screen. There you will find the USB connection and you can open the options. Select another type of connection; usually MTP or PTP should work.

You can also test on an emulator. It does not need to be prepared separately, as it is already designed for USB debugging. It is even possible to start an emulator at the beginning of the test.

To check if a device you have connected to your computer can be used, open the [[#Connection_Editor|connection editor]]. The device should be displayed there.

=== Connection via WLAN ===
It is possible to connect to Android devices via Wireless LAN. For devices using Android 11 or newer, this can be done wirelessly, else you have to connect initially via USB. Since expecco 22.1, WiFi connections can be established using the [[Mobile_Testing_Plugin/en#Connection_Editor|Connection Editor]]. It is also possible to do this using a command window.
==== Wireless Connect (Android 11) ====
In the developer options of your device, enable wireless debugging and open its options. You initially have to pair your machine with the device. To do this, choose "''Pair device with pairing code''" to get a pairing code and an IP address with port. Then open a command window (terminal window) on your machine and enter:
<nowiki>adb pair <Device IP Address>:<Pairing Port></nowiki>
where <tt><Device IP Address>:<Pairing Port></tt> is the IP address and port as shown on the device. After that, you will be asked for the pairing code. If everything went right, the popup on the device should have closed and your machine is added to the list of paired devices. Then enter at the command window:
<nowiki>adb connect <Device IP Address>:<Debugging Port></nowiki>
The IP address is the same as for pairing, but the port is different. Both are shown as IP address & Port on the device. The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted. Restarting the device often disables wireless debugging and the used port is changed. The pairing, however, is permanent and has not to be done again the next time you connect.
==== Start via USB ====
First, connect your device via USB. Then open a command window (terminal window) and enter:
<nowiki>adb tcpip 5555</nowiki>
The device listens for a TCP/IP connection on port 5555. If you have several devices connected or emulators running, you have to specify which device you mean. Enter in this case:
<nowiki>adb devices -l</nowiki>
to get a list of all devices, where the first column gives the device's ID.
Then, enter:
<nowiki>adb -s <deviceID> tcpip 5555</nowiki>
with the device identification of the desired device. You can now disconnect the USB connection. Now you have to find out the IP address of your device. You can usually find it somewhere in the device's settings, for example in the Status or WLAN settings of the phone. Then type in:
<nowiki>adb connect <IP address of device></nowiki>
The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> again or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted.

== Preparing an iOS-Device and App ==
Control of iOS devices is only possible via a Mac. Please also read the section [[#Mac_OS|Installation under Mac OS]].

Before you can control a mobile device with the Mobile Testing Plugin, you must allow debugging for iOS devices with iOS 8 or higher. Activate the option "''Enable UI Automation''" under the "''Developer''" menu in the device settings. If you cannot find the "''Developer''" entry in the settings, proceed as follows: Connect the device to the Mac via USB. If necessary, you must still agree to the connection on the device. Start Xcode and then select "''Devices''" from the menu bar at the top of the screen in the "''Window''" menu. A window opens in which a list of the connected devices is displayed. Select your device there. Then the entry "''Developer''" should appear in the settings on the device. You may have to exit the settings and restart.

[[Datei:Alert.png | thumb | 270px | Alert unter iOS]]
It is not possible to establish a connection to the device as long as it shows certain alerts. Such an alert may appear if FaceTime is activated (by displaying a message about SMS charges as shown in the screenshot). Be sure to configure the device so that it does not show such alerts when idle.

=== expecco 2.11 and later ===
You can test any app which is executable or already installed on the device used. If the app is available as a development build, the UDID of the device must be stored in the app. In any case, the WebDriverAgent must be signed for the device. Please read the section about [[#Signing|signing]] under Mac OS.

If you want to use the Home button in a test, you must activate "AssistiveTouch" on the device. You will find this option in the settings under "''General''" > "''Operating Help''" > "''AssistiveTouch''". Then place the menu in the middle of the upper edge of the screen. You can then record pressing the Home button with the corresponding menu entry in the recorder or use the "''Press Home Button''" block directly.

=== expecco 2.10 ===
The app you want to use must be available as a development build. The UDID of the device must also be stored in the app.

=== Sign the development build ===
A development build of an app is only allowed for a limited number of devices and cannot be started on other devices. However, it is possible to exchange the certificate and the usable devices in a development build.

* Evaluation with demo app of eXept:
:We will be happy to provide you with a demo app which is available as a development build and which we can sign for your device. Please send the UDID of your device to your eXept contact person. How to determine the UDID of your device is described in the following section.

* Using your own app for your test device:
:If you receive a development build (IPA file) from the app developers that is approved for your test device, you can use it directly. To do this, you must tell the developers the UDID of your device so they can enter it. '''You can use Xcode to read the UDID of a device'''. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window opens in which a list of the connected devices is displayed. Select your device and search for the ''Identifier'' entry in Properties. The UDID is a 40-digit hexadecimal number.

* Externally developed app for your test device:
:You can also re-sign apps to make them run on other devices. However, this process is complicated and requires access to an Apple Developer account. A documentation on the procedure is currently in preparation.

:For the evaluation we will gladly support you with the re-signing of your app..


For more information about using iOS devices, see also the
[http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Appium documentation].

=== Native iOS-Apps ===
You can also use apps that are already natively present on the device. To do this, you must know their bundle ID and then enter it in the connection settings. Here is a small selection of common apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

You can find further Bundle-IDs [https://github.com/joeblau/apple-bundle-identifiers here].

= Examples =
In the demo test suites for expecco you will also find examples for tests with the Mobile Testing Plugin. To do this, select the option "''Example from File''" on the start screen and open the folder named "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
The test suite contains two simple test plans: "''Simple CalculatorTest''" and "''Complex Calculator and Messaging Test''". Both tests use an Android emulator, which you must start before starting. The apps used in the test are part of the basic equipment of the emulator and therefore no longer need to be installed. Since the apps may differ under every Android version, it is important that your emulator runs under Android 6.0. In addition, the language must be set to English.

; Simple CalculatorTest
: This test connects to the calculator and enters the formula ''2+3''. The result of the calculator is compared with the expected value ''5''.

; Complex Calculator and Messaging Test
: This test connects to the calculator and then opens the message service. There it waits for an incoming message from the number ''15555215556'', in which a formula to be calculated is sent. The message is generated before via a socket at the emulator. When the message arrives, it is opened by the test and its contents are read. Then the calculator is opened again, the received formula is entered and the result is read. The test then switches back to the message service and sends the result as an answer.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
These are part of the tutorial for the Mobile Testing Plugin. The included test case is incomplete and will be added during the tutorial. Please read the section [[#Tutorial|Tutorial]].

= Tutorial =
There is a tutorial describing the basic procedure for creating tests with the Mobile Testing Plugin. It is based on a supplied example consisting of a simple app and an expecco test suite.

You find it on the page [[Mobile_Testing_Tutorial/en|Mobile Testing Tutorial]] in two versions for Android and iOS devices.
*  [[Mobile_Testing_Tutorial/en#First_steps_with_Android|First steps with Android]]
*  [[Mobile_Testing_Tutorial/en#First_steps_with_iOS|First steps with iOS]]

= Dialogs of the Mobile Testing Plugin =
== Connection Editor ==
You can use the Connection Editor to quickly define, change, or establish connections. Depending on the task, the dialog has small differences and is opened differently:
*If you want to establish a connection, access the dialog in the GUI browser by clicking on ''Connect'' and then selecting ''Mobile Testing''.
*To change or copy an existing connection in the GUI browser, select it, right-click and select ''Edit Connection'' or ''Copy Connection'' from the context menu.
*If you do not want to create connection settings for the GUI browser but for use in a test, choose ''Create Connection Settings'' from the Mobile Testing Plugin menu.... This only allows you to create the settings for a connection without creating a connection in the GUI browser.

The Connection Editor menu has several buttons, some of which are only visible when creating connection settings:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#''Delete Settings'': Resets all entries. (Only visible when creating settings.)
#''Load settings from file'': Allows to open a saved settings file (*.csf). Its settings are transferred to the dialog. Entries already made without conflict are retained.
#''Load settings from attachment'': Allows you to open an attachment with connection settings from an open project. These settings are applied to the dialog. Entries already made without conflict are retained.
#''Save settings to file'' and
#''Save settings to attachment'': Here you can save the entered settings to a file (*.csf) or create them as an attachment in an open project. Both options have a delayed menu in which you can choose to save only a certain part of the settings. (Only visible when creating settings.)
#''Advanced View'': Allows you to switch to the advanced view to make additional settings. Read more about this at the end of this chapter. (Only visible when creating settings.)
#''Help'': A help text for the respective step is shown or hidden on the right side.

The dialog is divided into three steps. In the first step you select the device you want to use, in the second step you select which App should be used and in the last step the settings for the Appium server are made.

===Step 1: Select Device ===
In the upper part you will see a list of all connected Appium devices that are detected. With the checkbox below you can hide devices that are detected but not ready. If you want to enter a device that is not connected, you can create it with the corresponding button ''Enter Android device'' or ''Enter iOS device''. However, you need to know the required properties of your device. The device is then created in a second device list and can be selected there. If no list with connected elements can be displayed, various messages are displayed instead:
*No devices found
*:expecco could not find any Android devices.
*:To automatically configure a connection to a device, make sure
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*No available devices found
*:expecco could not find any available Android devices. But not available ones were found, e.g. with the status "unauthorized".
*:To configure a connection to a device automatically, make sure that
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*:To view unavailable devices, enable this option below.
*Connection lost
*:expecco has lost the connection to the adb server. Try to re-establish the connection by clicking on the button.
*Connection failed
*:expecco could not connect to the adb server. Possibly it is not running or the specified path is not correct.
*:Check the adb configuration in the settings and try to start the adb server and establish a connection by clicking on the button.
*Connect ...
*:expecco connects to the adb server. This may take a few seconds.
*Start adb-Server ...
*:expecco starts the adb-Server. This may take a few seconds.

With ''Next'' you get to the next step. If you enter settings for the GUI browser, this is only possible once a device has been selected.

Note on unlocking: In newer Android versions the developer options are no longer offered in the settings at first. If your Android device does not show an entry for "''Developer options''" in the settings, first select the entry "''Phone info''", then "''SoftwareVersionsInfo''" and click on the entry "''BuildVersion''" several times.

==== Manage Chromedrivers ====
If the App you want to automate uses WebViews with Chrome, Appium needs to have access to an appropriate Chromedriver. If you have selected a device in the list, you can use "''Manage Chromedrivers''" to see, which Chrome versions are installed on the device and which Chromedriver versions are provided by expecco. With this dialog you can also download required Chromedriver versions. Beware that there may be several Chrome versions on the device. An App doesn't have to use the version of the installed Chrome browser for its WebViews. The Chromedriver you use should fit your app for everything to work properly. You can also change the path to the Chromedriver in the capabilities generated at the end of the connection editor.

==== Connect WiFi Android Device ====

You can connect to Android devices using WiFi as well. In this case, the device has to be connected to ADB first, see [[Mobile_Testing_Plugin/en#Connection_via_WLAN|Connection via WLAN]]. Since expecco 22.1, the connection editor provides a dialog helping to set this up, which can be used instead of the command window. For devices using Android 11 or newer, you can pair the device with your machine here by specifying the appropriate parameters and then establish the connection by specifying the IP address and port. You can also use this to establish a wireless connection for devices that are connected via USB. When you select the corresponding device in the list, the required information is read out automatically.

Note that establishing a wireless connection is not part of the connection settings. If you want to establish a new connection with the generated settings, you must make sure that the device is connected to ADB with the specified IP address and port so that it can be found. The ADB connection will be lost if the ADB server or the device are restarted. The permission for wireless debugging is also often reset when the device is restarted and the debug port can then change. Therefore, a wireless connection must always be established manually.

===Step 2: Select App===
Here you can enter information about the app to be tested. You can decide if you want to use an app that is already installed on the device or if you want to install an app for the test. Select the appropriate tab above. Depending on whether you selected an Android or an iOS device in the previous step, the required input will change.

*'''Android'''
**''App on Device''
**:If you have selected a connected device in the first step, the packages of all installed apps are automatically retrieved and you can select from the drop-down lists. The installed apps are divided into third-party packages and system packages; select the appropriate package list. This selection does not belong to the settings, but only provides the corresponding package list. You can use the filter to further narrow down the list and then select the desired package. The activities of the selected package are also automatically retrieved and made available as a drop-down list. Select the activity you want to start. As a rule, an activity is automatically entered from the list. If you are not using a connected device, you must enter the package and the activity manually.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. If you are using a local Appium server, you can use the right button to navigate to the App installation file and enter this path. If possible, the corresponding package and the activity are also entered in the fields below. However, this entry is not necessary.

*'''iOS'''
**''App on Device''
**:Specify the bundle ID of an installed app. You can find out the IDs of the installed apps using Xcode, for example. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window will open displaying a list of connected devices. If you select your device, you will see a list of the apps you have installed in the overview.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. For the requirements of apps for real devices, please read the section [[#iOS-Ger.C3.A4t_and_App_Preparing|Preparing an iOS-Device and App]].

In the lower part you can specify whether the app should be reset or uninstalled when the connection is terminated, and whether it should be reset initially. Again, the corresponding capability is not set if you select ''(Default)''. With ''Next'' you get to the next step.

===Step 3: Server Settings===
In the last step, a list of all the capabilities that result from your entries in the previous steps is first displayed in the upper part. If you are familiar with Appium and want to set additional capabilities that are not covered by the connection editor, you can click on ''Edit'' to open the extended view. See the section below for more information.

If you enter settings for the GUI browser, you can enter the ''Connection name'' with which the connection is displayed. This is also the name under which devices can use this connection when it is established. If you leave the field blank, a name will be generated. If the box "''Managed by expecco''" is checked, expecco will start a local Appium server on a free port, or use a free server that has already been started. To use your own server, turn this feature off and enter the appropriate address. You will get the local default address and already used addresses to choose from.

In older expecco versions the box is labeled "''Start on demand''". In this case, you must also enter an address if you want expecco to start the server. expecco then tries to start an Appium server at the given address when connecting, if none is running there yet. This server will then also be shut down when the connection is terminated. This only works for local addresses. Make sure that you only use port numbers that are free. It is best to only use odd port numbers from the standard port 4723. The following port number is also used when establishing a connection, which could otherwise lead to conflicts.

Depending on how you opened the dialog, there are now different buttons to close it. In any case you have the option to save. This opens a dialog where you can either select an open project to save the settings there as an attachment, or choose to save it to a file that you can then specify. Saving does not close the dialog, allowing you to select another option.

If you have opened the editor for establishing a connection, you can finally click on ''Connect'' or ''Start and connect server'', depending on whether the check mark for server start is set. For changing or copying a connection in the GUI Browser, this option is called ''Apply'', since in this case only the connection entry is changed or created, but the connection setup is not started. If necessary, you can do this afterwards via the context menu. If you have changed capabilities of an existing connection, a dialog then prompts you to decide whether these changes should be applied directly by closing the connection and establishing the new connection or not. In this case, the changes only take effect after you reestablish the connection.

To use the connection editor, also read the corresponding section in the respective tutorial in step 1. (Android: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo|Run Demo]], iOS: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo_2|Run Demo]]).

===Extended View===
The extended view of the connection editor can be obtained either by clicking on ''Edit'' in the third step or at any time via the corresponding menu item if you have started the editor via the plugin menu. This view displays a list of all configured Appium Capabilities. You can add, change or remove further entries to this list. To add a capability, select it from the drop-down list of the input field. In this list all known capabilities are sorted into the categories ''Common'', ''Android'' and ''iOS''. If you have selected a capability, a short information text is displayed. You can also enter a capability manually in the field. Then click on ''Add'' to add the capability to the list. There you can set the value in the right column. To delete an entry, select it and click on ''Remove''. With ''Back'' you leave the extended view.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Running Appium Servers ==
In the menu of the Mobile Testing Plugin you will find the entry ''Appium-Server...''. This opens a window with an overview of all Appium servers started by expecco and on which port they are running. By clicking on the icon in the column ''Show Log'' you can view the logfile of the corresponding server. This is deleted when the server is shut down. With the icons in the column ''Exit'' the corresponding server can be terminated. However, this is prevented if expecco still has an open connection via this server. The rightmost column shows for which connection the server is in use. If it reads ''<idle>'', the server is currently not used by expecco.

[[Datei:MobileTestingAppiumServer.png]]

When opening the editor to start an Appium connection, an Appium server is started immediately to speed up the connection process. For this purpose, expecco always keeps one idle running Appium server. Additional running servers however, which are not in use anymore, will be terminated automatically after a while.

In the menu of the Mobile Testing Plugin you will also find the entry ''Close all Connections and Servers''. This is intended for cases where connections or servers cannot be terminated in any other way. If possible, always terminate connections in the GUI browser or by executing a corresponding block. Servers that you have started in the server overview should be terminated there; servers that were started with a connection are automatically terminated with this connection.

Note that only servers started and managed by expecco are listed in the overview. Possible other Appium servers that were started in a different way are not recognized.

== Recorder ==
If the GUI browser is connected to a device, the integrated recorder can be used to record a test section with that device. To start the recorder, select the appropriate connection in the GUI browser and click the Record button. A new window opens for the recorder. The recorded actions are created in the GUI browser work area. It is therefore possible to edit the recorded data in parallel.

[[Datei:MobileTestingRecorder.png|caption|]]

====Components of the Recorder Window====
#'''Continue/Pause Recording''': You can pause the recording by clicking the right icon. You will then see a large pause sign in the view. All actions that you perform now in the recorder are executed, but no blocks are recorded. You can switch back to normal recording mode by clicking the left icon.
#'''Stop Recording''': Stops the recording and closes the recorder window.
#'''Update''': Gets the current image and element tree from the device. This is necessary if the device takes longer to execute an action or if something changes without being triggered by the recorder. Since expecco 21.2, there is an additional submenu here that can be used to enable automatic update by checking for changes in the background (see also ''Automatic Update'' further below).
#'''Follow Mouse''': Select the element under the mouse pointer in the GUI browser.
#'''Element Highlighting''': The element under the mouse is outlined in red.
#'''Show Elements''': Show the borders of all elements in the view.
#'''Tools''': Selection, which tool is used for recording. The selected action is triggered with each click on the view. The following actions are available:
#*Element Actions:
#**Click: Short click on the element under cursor. To determine more precisely which element is used, use the Follow Mouse or Element Highlighting function.
#**Tap with Duration (Element): Similar to click, except that the duration of the click will be recorded as well. This allows the recording of long clicks.
#**Tap with Position (Element): Similar to click, but additionally records the position inside the element. The position can be recorded relative to the element size or, when pressing Ctrl while clicking, as absolute position from the upper left corner of the element.
#**Set Text: Allows to set the text of an input field.
#**Clear Text: Clears the text of an input field.
#*Device Actions:
#**Tap (Screen): Triggers a click at the screen position.
#**Tap with Duration (Screen): Triggers a click at the screen position, which also considers the duration.
#**Swipe: Swipe in a straight line from the point where you press the mouse button until you release it. The duration is also recorded.
#:Please note for this actions that the result may differ on different devices, e.g. with different screen resolutions.
#*Test Flow Blocks
#**Check Attribute: Compares the value of a specified attribute of the element with a predefined value. The result triggers the corresponding output.
#**Assert Attribut: Compares the value of a specified attribute of the element with a predefined value. If the values are not equal, the test fails.
#**Get Attribute: Gets the current value of a specified attribute of the element.
#*Auto
#:If the Auto tool is selected, you can use all actions by specific input methods: ''Click'', ''Tap Element'' and ''Swipe'' still work by clicking, but are distinguished by the duration and movement of the cursor. To trigger a ''Tap'', hold down Ctrl while clicking. The remaining actions are available in a context menu by right-clicking on the element.
#'''Context Actions''': Here you can record actions concerning contexts:
#*Switch to Context: Shows a list of all currently available contexts and you can select to which one you want to switch.
#*Get Current Context: Gets the handle of the current context.
#*Get Context Handles: Gets a list of all currently available contexts.
#'''Softkeys''': Only for Android. Simulates pressing the buttons Back, Home, Menu and Power.
#'''Home Button''': Only for iOS since expecco 2.11. Allows pressing the Home button.Prior to expecco 19.2, it only works if AssistiveTouch is activated and the menu is located in the middle of the upper screen border. From expecco 19.2 on, the function no longer uses AssistiveTouch.
#'''Help''': Opens this online documentation on the general page about [[GuiBrowser_Recorder/en|GUI Browser recorders]].
#'''View''': Shows a screenshot of the device. Actions are triggerd by mouse depending on the selected tool. If a new action can be recorded, the window has a green frame, else it is red.
#'''Resize Window to Image''': Resizes the recorder window so that the screenshot can be displayed completely.
#'''Resize Image to Window''': Scales the screenshot to a size that makes use of the full size of the window.
#'''Adjust Display''': Opens a dialog to adjust the displayed image, if expecco does not show it right. You can correct the scaling or rotate the image by 90°.
#'''Correct Orientation''': Corrects the image if it is upside down. Using the arrow to the right, the image can also be rotated by 90°, if this should ever be necessary. Since expecco 19.1 you find this functionality under ''Adjust Display''. The orientation of the image is irrelevant for the functionality of the recorder, it only works on the elements it receives.
#'''Scaling''': Changes the scaling of the screenshots.
#'''Messages''': Shows the path of the current selected element or other messages. It has a context menu to show a list of previous messages.

====Usage====
Each click in the window triggers an action and is recorded in the workspace of the GUI browser. There you can run, edit, or create a new block from what you have recorded. You find the actions to trigger softkeys directly in the menu bar (see above). To record actions on elements, either change the selection of the tool in the menu bar (see above) and then click on the element or select the corresponding action from the context menu by right-clicking on the corresponding element. For text input it is also possible to place the cursor over the element and enter the text. This opens the input dialog for this action. On how to use the recorder, see also step 2 in the tutorial ([[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_Block_with_the_Recorder|Android]] resp. [[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_block_with_the_Recorder_2|iOS]]).

====Hide elements====
Since expecco 21.2 it is also possible to hide the selected element in the recorder from the context menu. This means that this element cannot be selected from now on. This function is useful for ignoring elements that are in the foreground to be able to access elements below them. To undo this state, you have to find the corresponding element in the tree of the GUI browser, which also has such an entry in the context menu.

====Automatic Update====
The recorder doesn't show a live image of the device, but only a snapshot. Therefore an update is needed after changes to match what is displayed on the device. The recorder updates automatically after executing an action. Since expecco 20.2 there are further automatic updates possible. You can enable the, in the menu "View".

One option is, to check after an action has been executed, if there are further changes after the first update. If so, a second update is triggered. This shall fix the problem, that the recorder is not up to date after an action, because the update has been done too early.

The second option is to enable a periodical update. After a set interval the recorder is automatically updated if there are changes. Thereby the recorder view is mostly up to date, but this causes an overhead regarding the communication to the device.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid Apps and WebViews =
'''!!! IMPORTANT NOTICE - If you have problems switching to the webview, please set the "Default Application - Browser App" in Android Settings to "Chrome" !!!'''

Hybrid apps contain platform native elements as well as other elements that are integrated in a WebView. These elements can also be used, but you first have to switch to the corresponding context. With the block ''Get Current Context'' you get the current context. Initially this is ''NATIVE_APP'', i.e. the context of the native elements. With the block ''Get Context Handles'' you get a collection of all existing contexts. If there is a WebView context, it is called ''WEBVIEW_1'' or ''WEBVIEW_<package>'' with the package of the WebView. Several WebView contexts are also possible. For each WebView context, there is a corresponding WebView element in the native context. You can use the ''Switch to Context'' block to switch to such a context and from now on only have access to the elements in this context.

In the GUI browser, the existing contexts are displayed at the top of the tree as well as the tree of a context is inserted below the corresponding WebView element.

=Customizing XPath using the GUI Browser=
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen ''GTIN-13 (EAN-13)'' und ''Verify'', das Eingabefeld der Zahl ''4006381333986'' und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des GTIN-13-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch ''Pfad überprüfen'' (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit ''Verify Path: OK'' (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit * zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert ''GTIN-13 (EAN-13)'' besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer ''hierarchy'' (für iOS wäre es ''AppiumAUT''), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix ''android.widget.'', das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend ''XCUIElementType'' am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. ''FrameLayout'' ist ein Kindelement von ''hierarchy'', ''LinearLayout'' ist ein Kind von ''FrameLayout'' usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element ''hierarchy'' beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben ''TextView''-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ ''Button'' gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut ''resource-id''. Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut ''name'' verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem @ eingeleitet und der Wert mit einem = in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter ''Test'' eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf ''Lauf''. Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu ''Eigenschaften'', wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

=Problems and Solutions=
== Locators depend on the version or are variable ==
In this case consider to either store the locators (xPath) in a variable or to define a locator mapping inside a screenplay attachment. It is also possible to store just parts of an locator (e.g. locator path of a parent or attribute value) in a variable and add them in the freeze value of the locator pin by "''$(varName)''".

== Invisible UI Elements ==
Note that the [[#Recorder|Recorder]] also considers items that you cannot see on the screen. Therefore, turn on element highlighting or use the follow mouse function and the element tree in the GUI browser to determine if the correct element is used. It can happen, that invisible elements are in front of other elements and cover them, so that the desired element cannot be selected in the recorder. See section [[#Hide_elements|Hide elements]] for a solution to this.

==''org.openqa.selenium.StaleElementReferenceException''==
The error <code>org.openqa.selenium.StaleElementReferenceException</code> occurs whenever an element is used that is no longer there. If that happens during your test and the element should have been there, try using the locator (xPath) instead to fetch the element again.

In some cases this error can also occur even if you already use a locator at the action block. This is because the locator is always resolved first and the corresponding element is fetched and the action is then executed with this element. If the app refreshes the element exactly between the resolving and fetching part and the execution, creating a new element, this error occurs. If it happens at a specific point in your test, your best option is to catch the error and retry.

== iOS: Cable not certified ==
In some cases, when connecting an iOS device via USB, a message appears indicating that the cable used is not certified. In this case, replacing the respective cable is the only solution.

== iOS: Alerts when connecting ==
Make sure that no alerts are open when connecting to an iOS device. Otherwise the connection will fail because the app cannot be brought to the foreground. See also [[#Preparing_an_iOS-Device_and_App|Preparing an iOS-Device and App]].

== iOS: .ipa cannot be installed ==
Note that on iOS simulators no ''.ipa'' files can be installed but only ''.app'' files.

==iOS: First Connect is not working==
If there is not already a signed build of the WebDriverAgent on your Mac, it has to be created during the first connect. Usually, this can take a little longer than one minute. Per default Appium uses a timeout of 60000 ms to wait for the WebDriverAgent to start on the device, so the connect will be canceled in that case. You can set this timeout with the capability ''wdaLaunchTimeout'', e.g. to ''120000''.

Moreover, the signing settings have to be correct. In our experience, the most reliable solution is to set automatic signing in the WebDriverAgent Xcode project an selecting the team there. See the explanation in section [[#Signing_WebDriverAgent|Signing WebDriverAgent]] for that. In this case you should '''not''' use the capabilities ''xcodeConfigFile'' resp. ''xcodeOrgId'' and ''xcodeSigningId'', as they could cause a conflict. Caution: If you have set a Team ID in the Mobile Testing settings, expecco will automatically set this as ''xcodeOrgId''!

Pay attention to your device during the first connect. You might have to agree to the installation by entering your password. On the Mac you might need to enter the password to allow access to the key chain for signing, often several times.

== Android: Device not visible in the connect editor ==
If an Android device connected via USB does not appear in the connection editor, try changing the USB connection type. Usually MTP or PTP should work. Check again, if "USB Debugging" is enabled in the developer options on the device (these options are disabled on some devices and have to be enabled first using a trick.) See also [[#Prepare_Android_Device|Prepare Android Device]].

== Android: Truncated Elements at Bottom ==
For Android devices that automatically show and hide the navigation bar/softkeys, the recorder may cut off elements in the lower area that would be hidden by the softkeys, even if they are not displayed at this time. In this case it is advisable to set the softkeys so that they are permanently displayed.

For newer Android versions there usually is no such option. Even if the controls are visible all the time, they don't have their own space, but are on top of the content of the app. Therefore, there is an area on the lower part of the screen, which cannot be automated, because it is not counted to the active area of the app. Appium will then truncate the elements there. This area can even be larger then the needed by the controls. This is a known issue for Samsung devices with Android 11. Since the information about the size of the app area is already provided on Android level, we cannot offer a solution for this, but can only hope that the problem will be fixed by the manufacturer. You may try to get better results by setting the control to gestures, but this bears the same issue.

== Android: Test Hangs While Finding an Element==
The block ''Find Element by XPath'' and all element blocks wait until an element is present for the given path. The timeout for this can be set either directly at the block or in the environment variables. However, if the element should already be present, but the test doesn't continue anyway, the reason could be in the UIAutomator/UIAutomator2. It waits for the app to go to the idle state before it even starts to search for the element. This may take longer, if the app e.g. runs an animation in the background or executes other kinds of actions. Fetching the page source, e.g. when updating in the GUI browser or in the recorder, can also take longer for this reason. There is a default timeout of 10 seconds after which it no longer waits for the idle state. This timeout can be set in Appium (waitForIdleTimeout). If you want to change the value of this timeout, you can do this since expecco 21.2 by executing the Smalltalk code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> before the test. The timeout is given in milliseconds, so the example sets it to 2 seconds.

==Android: Updating the Tree or Switching to Webview Context takes too long==
Especially with older devices it can happen that newer Chromedriver cannot be initialized. This makes it impossible to switch to the webview context. However, this is only detected over a timeout by Appium, which is 4 minutes by default. Since expecco also tries to switch to the webview context when building the tree in the GUI browser, this can lead to very long loading times. Since there is no way to decrease this timeout in Appium, we have added a corresponding capability to the version we provide in the MobileTestingSupplement. Starting with version 1.13.1.0 of the [[#Windows|MobileTestingSupplement]], ''chromedriverStartTimeout'' can be used to set the timeout in milliseconds. The switch still doesn't work then, but expecco doesn't take as long to update the tree and the context switch module fails faster. The connection dialog adds this capability automatically starting with expecco 22.1.

== No Action on Click ==
The block to click on an element is successful, but no action was performed on the device.
:This can happen if the element is hidden by another element and therefore clicking on the element is not possible. In this case, Appium does not throw an error, but simply nothing happens. If you would like to make a click at the position of the element anyways, even if it is hidden, use the block ''Tap'' instead and pass the location of the element to it (''Get Location''). If instead you want to check before a click whether the element is hidden at this moment, try whether the properties ''Is Displayed'' or ''Is Enabled'' might help you.

== No Update After Action ==
An action was triggered on the recorder and a block has been recorded, but the recorder still shows the old image.
:The recorder doesn't show a live image of the device, but only a snapshot. After an action has been executed, the recorder will update automatically. However, it can happen, that the image has already been updated before the effects of the action are fully completed on the device. In this case you should update the recorder by hand using the icon with the blue arrows. Since expecco 20.2 you can also enable automatic updates for this case. See also the description for the [[#Recorder|recorder]].

== Attribute "clickable" is wrong ==
An element has for the attribute/property "''clickable''" the value "''false''", but is actually clickable.
:The attribute "''clickable''" has to be set explicitly by the app developer and does not affect the behavior of the app. You should generally disregard this attribute in your tests. Unfortunately, many apps exist where the programmer was "lazy" about this.

==Connecting Fails==
If the connection to the Appium server fails, you will receive an error message in expecco similar to the one shown below.

[[File:MobileTestingVerbindungsfehler.png]]

Here you can see the type of error that has occurred. Click on "''Details''" to get more information. Possible errors are:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:The specified server is not running or is not reachable. Check the server address.
*''org.openqa.selenium.WebDriverException''
:Read the message after ''Original Error'' in the first line of the details:
:*''Unknown device or simulator UDID''
::Either the device is not connected properly or the udid is not correct.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::This error can have various causes. Either the WebDriverAgent could actually not be built because the signing settings are wrong or the appropriate provisioning profile is missing. Please read the section about [[#Signing|Signing]]. It is also possible that the WebDriverAgent cannot be started on the device, for example because an alert is in the foreground or you did not trust the developer.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::The specified app cannot be installed on the iOS device because it is not entered in the app's Provisioning Profile.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.''
::The path to the app is wrong. Make sure that the file is located in the specified path on your Mac.
:*''packageAndLaunchActivityFromManifest failed.''
::The specified ''apk'' file is probably broken.
:*''Could not find app apk at [...]''
::The path to the app is wrong. Make sure that the ''apk'' file is located in the specified path.

If the error is not due to one of the causes listed above, the automation applications on the device may no longer function properly. In this case it helps to uninstall them from the mobile device. They are then automatically reinstalled the next time a connection is established.

*For iOS devices, this is the WebDriverAgent, which you can simply uninstall from the home screen. This usually solves problems caused by changing the used Mac or the Xcode version.

*For Android devices, it is the UIAutomator2; here, a problem occurs sporadically on some devices, the cause is currently unknown to us. To uninstall, on the device, navigate to "''Settings''" > "''Applications''"* and search the list for the following entries:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Click on the respective application and then on "''Uninstall''".
*''The corresponding entry may have a slightly different name on some devices.''

If this doesn't help, check the output of the Appium server. For a server started by expecco, you can find the log in the list of [[#Running_Appium_Servers|Running Appium Servers]].

==I do not have a Mac==
Maybe this site will help you: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin

2024-07-23T09:48:41Z

Matilk: /* Probleme und Lösungen */ org.openqa.selenium.StaleElementReferenceException

'''Deutsche Version''' | [[Mobile_Testing_Plugin/en|English Version]]

= Einleitung =
Mit dem ''Mobile Testing Plugin'' können Anwendungen auf Android- und iOS-Geräten getestet werden. Dabei ist es egal, ob reale mobile Endgeräte oder emulierte Geräte verwendet werden. Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests unterstützt. Zudem ist damit das Aufzeichnen von Testabläufen möglich.

Zur Verbindung mit den Geräten wird [http://appium.io/ Appium] verwendet. Appium ist ein freies Open-Source-Framework zum Testen und Automatisieren von mobilen Anwendungen.

Zur Einarbeitung in das Mobile Plugin empfehlen wir das [[Mobile_Testing_Tutorial|Tutorial]] zu bearbeiten. Dieses führt anhand eines Beispiels Schritt für Schritt durch die Erstellung eines Testfalls und erklärt die nötigen Grundlagen.

= Installation und Aufbau =
Zur Verwendung des Mobile Testing Plugins müssen Sie expecco inkl. des Plugins Mobile Testing installiert haben und Sie benötigen die entsprechenden Lizenzen. expecco kommuniziert mit den Mobilgeräten über einen Appium-Server, der entweder auf demselben Rechner wie expecco läuft, oder auf einem zweiten Rechner. Dieser muss für expecco erreichbar sein.

==Installationsübersicht==

'''Rechner, auf dem expecco läuft:'''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem Android-Geräte angeschlossen sind:'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Android SDK'', dieses erhalten Sie ebenfalls mit dem Mobile Testing Supplement''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem iOS-Geräte angeschlossen sind2):'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement für Mac OS installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Xcode ''in einer Version, die die verwendete iOS-Version unterstützt, erhältlich über den Apple App Store''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
* Apple-Entwickler-Zertifikat mit zugehörigem privaten Schlüssel ''(zum Signieren des WebDriverAgents)''
* Provisioning Profile mit den verwendeten Mobilgeräten

Je nach Aufbau können die oben genannten Rechner auch das selbe Gerät sein. expecco kann sich sowohl über das Netzwerk mit einem entfernten Appium-Server und dort angeschlossenen Mobilgeräten verbinden, als auch lokal selbst einen Appium-Server starten und diesen mit lokalen Mobilgeräten verwenden. Einige Funktionen von expecco, die die Erstellung von Testfällen erleichtern, sind jedoch nur verfügbar, wenn die Mobilgeräte am selben Rechner angeschlossen sind, auf dem auch expecco läuft. Ein möglicher Aufbau kann daher wie in folgender Abbildung aussehen:

[[Datei:MobileTestingAufbau.png | 400px]]

Im Folgenden wird die Installation von Appium und anderer nötiger Programme für Windows und Mac OS erklärt.

1): Zum Zeitpunkt der Erstellung dieses Dokuments wurden Versionen bis 11 auf Funktion verifiziert. Neuere Versionen sollten - sofern nicht grundlegende Änderungen von Oracle vorgenommen wurden, ebenfalls funktionieren.

2): Beachten Sie, dass aufgrund der Voraussetzungen (keine Anbindung an nicht-Apple Geräte verfügbar) iOS-Geräte nur von einem Mac aus angesteuert werden können. Sie benötigen also einen Mac als "Vermittler" (siehe auch unten: [[#Ich habe keinen Mac | "Ich habe keinen Mac"]])

== Windows ==
Am einfachsten installieren Sie alles mit unserem Mobile Testing Supplement1. In neueren Versionen ist allerdings aufgrund geänderter Lizenzbedingungen seitens Oracle kein JDK mehr enthalten, sodass sie dieses zusätzlich installieren müssen. Sie können natürlich Appium auch direkt installieren, um die Version zu verwenden, die Sie möchten. Um dann einen Appium-Server mit expecco starten zu können, muss allerdings eine entsprechende Batchdatei vorhanden sein und in den [[Mobile_Testing_Plugin#Konfiguration_des_Plugins|Einstellungen]] angegeben werden. Verbindungen können aber auch zu anderen laufenden Appium-Servern aufgebaut werden.
*'''expecco 24.1''': [https://download.exept.de/transfer/h-expecco-24.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.3]
:Im Vergleich zum Vorgänger aktualisierte Chromedriver Versionen.
*expecco 23.2: [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Im Vergleich zum Vorgänger aktualisierte Chromedriver Versionen.
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Gleiche Versionen wie der Vorgänger, aber der Installer erlaubt nun, Appium zum Autostart hinzuzufügen.
*expecco 22.2 und 22.1: [https://download.exept.de/transfer/h-expecco-22.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 aus platform-tools 33.0.2
:''* Wir haben Appium um die Capability'' startChromedriverTimeout ''erweitert, um schneller einen Timeout zu bekommen, wenn der Chromedriver nicht gestartet werden kann. (siehe [[#startChromedriverTimeout|Probleme und Lösungen]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Enthält die Appium-Version 1.22.0, Node ist weiterhin in der Version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Nur kleine Änderungen im Vergleich zur vorigen Version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und node 12 verwendet.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:Dieses installiert Appium in der Version 1.12.0 und enthält nun zusätzlich build-tools der Version 28.0.3 im android-sdk. Ansonsten ist es gleich wie die vorige Version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:Dieses installiert Appium in der Version 1.8.1. Außerdem bietet das Supplement auch an, ''Android Debug Bridge'' und ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) zu installieren. Damit sind Treiber für ein breites Spektrum an Android-Geräten abgedeckt, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen. Ein '''JDK ist (aufgrund geänderter Lizenzbedingungen seitens Oracle) nicht mehr enthalten''', dieses müssen Sie selbst herunterladen, z.B. von [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: wie expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.6.4. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.4.16. Während der Installation wird die grafische Oberfläche von Appium gestartet, dieses Fenster können Sie sofort wieder schließen. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.

Wenn expecco Mobilgeräte verwenden soll, die an einem anderen Rechner angeschlossen sind, müssen Sie dort einen Appium-Server starten. Dies können Sie mit der Datei <code>appium_standalone.cmd</code> tun. Der Server wird dann mit dem Standard-Port 4723 gestartet. Falls Sie eine andere Portnummer verwenden wollen, starten Sie den Server mit

appium_standalone.cmd -p <portnummer>

Der Server ist bereit, sobald die Zeile
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
angezeigt wird, wobei Sie am Ende die verwendete Portnummer ablesen können.

Beim ersten Starten von Appium – sowohl im Standalone als auch gestartet von expecco – kann es vorkommen, dass die Windows-Firewall den Node-Server blockiert. Lassen Sie den Zugriff zu, sonst kann Appium nicht gestartet werden.

1) Sie können natürlich auch die Command Line Tools (adb, sdkmanager, avdmanager etc.) einer vorhandenen Android Studio Version verwenden, sowie Appium separat installieren.
Da sich diese Tools regelmäßig ändern, und es in der Vergangenheit zu Inkompatibilitäten und Fehlern nach Releasewechseln kam, empfehlen wir zu Beginn, das mitgelieferte Paket zu verwenden. Dies ist möglicherweise nicht das aktuellste, wurde aber auf Lauffähigkeit getestet.

Falls das Android Mobilgerät an einem entfernen Rechner angeschlossen ist,
können Sie den aktuellen Bildschirminhalt z.B. mit dem [https://github.com/Genymobile/scrcpy scrcpy] tool live mitverfolgen.

== Mac OS (nicht erforderlich für Android-Tests)==
Hinweis: Wenn Sie nicht vorhaben, iOS-Geräte (iPhone, iPad, etc.) zu testen, können Sie das Folgende ignorieren. '''Der Apple-Rechner sowie das Mac-Setup werden für Android-Geräte nicht benötigt'''.

=== Xcode ===
Zur Automatisierung mit iOS-Geräten wird [https://developer.apple.com/xcode/ Xcode] benötigt. Sie erhalten dieses über den App Store. Dabei ist darauf zu achten, dass die Version zu den getesteten iOS-Versionen passt.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
Diese Tabelle gibt nur eine vereinfachte Übersicht, lesen Sie besser unter [https://xcodereleases.com/ Xcode Releases] oder [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode-Versionen] welche Version Sie brauchen. Für neue iOS Minor-Versionen gibt es in der Regel auch ein Update für Xcode, z.B. brauchen Sie für iOS 10.2 mindestens Xcode 8.2, für iOS 10.3 mindestens Xcode 8.3 usw.
Wenn Sie also auf eine neuere iOS-Version wechseln, benötigen Sie in der Regel auch eine neuere Xcode-Version. Neuere Versionen von Xcode laufen möglicherweise nicht auf älteren Betriebssystemen, was wiederum eine Aktualisierung des Betriebssystems erforderlich machen kann. Falls Sie auch ältere iOS-Versionen testen wollen kann es sinnvoll sein, die entsprechenden Xcode-Versionen parallel zu installieren.

=== Appium ===
Der Appium-Server kann entweder als Kommandozeilen-Anwendung installiert werden oder über [https://github.com/appium/appium-desktop Appium Desktop] verwendet werden, welcher den Server über ein GUI zur Verfügung stellt. Mittlerweile gibt es auch Appium 2.0, was wir aber bisher noch nicht mit expecco getestet haben und daher nicht empfehlen.

==== Appium Desktop ====
Laden Sie die neueste Version von [https://github.com/appium/appium-desktop/releases/ Appium Desktop] herunter. Für den Mac nehmen Sie am besten die dmg-Datei und installieren sie in den Anwendungen. Beim Starten der Anwendung ''Appium Server GUI'' erhalten Sie wahrscheinlich eine Fehlermeldung, dass es aus Sicherheitsgründen nicht möglich ist. Öffnen Sie dann das Kontextmenü auf der Anwendungsdatei (Rechtsklick bzw. Strg + Klick) und wählen Sie dort ''Öffnen'' aus. Bestätigen Sie dann, dass Sie die Anwendung wirklich öffnen wollen. Fortan können Sie die Anwendung normal öffnen.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Ab Xcode 14 gibt es Probleme beim Signieren des WebDriverAgents, den Appium zur Automatisierung auf das Gerät spielt. Dadurch ist mit der Version 1.22.3-4 von Appium Desktop kein Verbindungsaufbau möglich. Das Problem ist in neueren Versionen des WebDriverAgents behoben, es gibt aber aktuell noch keine Version von Appium Desktop, die eine solche Version enthält (Stand November 2022). Sie können aber manuell eine neue Version herunterladen (z.B. 4.10.2) und die Dateien in Appium ersetzen. Laden Sie dazu von der [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent Download-Seite] eine der beiden Archivdateien (zip oder tar.gz) mit dem Source Code herunter. Öffnen und entpacken Sie dann diese Datei. Den Inhalt des Ordners WebDriverAgent-4.10.2 müssen Sie nun nach

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

kopieren. Wenn Sie über den Finder dorthin navigieren, machen Sie auf die Anwendung ''Appium Server GUI'' einen Kontextklick (Rechtsklick bzw. Strg + Klick) und wählen Sie im Menü ''Paketinhalt anzeigen''. Ersetzen Sie alle Dateien, die bereits mit gleichem Namen enthalten sind.

==== Appium über npm installieren ====
Sie können Appium auch über npm (Node Package Manager) installieren. Dazu müsen Sie erst node/npm installieren. Das geht mit [https://github.com/nvm-sh/nvm nvm] (Node Version Manager) was Sie von Github bekommen. Falls die folgende Installationsanleitung bei Ihnen nicht funktionieren sollte, finden Sie dort ausführlichere Informationen im [https://github.com/nvm-sh/nvm#readme Readme].

Öffnen Sie ein Terminal-Fenster. Klonen Sie dann das Github-Repository von nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
und laden Sie es
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Führen Sie danach
command -v nvm
aus, um zu testen, ob es funktioniert hat. Es sollte ''nvm'' ausgegeben werden. Kommt keine Antwort, führen Sie
touch ~/.zshrc
aus, und versuchen Sie es erneut.

Nun können Sie node mit dem folgenden Befehl installieren.
nvm install 16.15.1
Da es mit der aktuellen Version von node Probleme beim Installieren von Appium gibt, empfehlen wir diese Version.

Nachdem node installiert ist, können Sie Appium darüber installieren:
npm install -g appium

Den Appium-Server können Sie nun einfach über den Befehl
appium
starten. Die Ausgabe erfolgt dann direkt im Terminal.

Auch bei dieser Version gibt es das Problem bei der Signierung des WebDriverAgents, wie bei [[#Appium_Desktop | Appium Desktop]] beschrieben. Laden Sie also auch in diesem Fall eine neuere Version des WebDriverAgents herunter und ersetzen Sie die alten Dateien. Diese finden Sie unter
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
Ältere Appium-Versionen stellen wir Ihnen über das Mobile Testing Supplement für Mac OS zur Verfügung, mit dem Sie es einfach installieren können:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.2)]
:Enthält Appium Version 1.18.3 und verwendet node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.0)]
:Nur wenige Änderungen im Vergleich zur vorigen Version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.98)]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und es wird node 12 verwendet.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.96)]
:Diese Version enthält Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.94)]
:Diese Version enthält Appium 1.8.0.

* expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.0.94)]
:Diese Version enthält Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement für Mac OS]
:Diese Version entält Appium 1.4.16.

Nachdem Herunterladen des Supplements, können Sie es in ein Verzeichnis Ihrer Wahl (z. B. Ihr Home-Verzeichnis) verschieben und dort entpacken. Ein geeigneter Befehl in einer Shell könnte wie folgt aussehen, passen Sie dabei die Versionsnummer entsprechend an:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

Wenn Sie Ihre Standard-Xcode-Installation verwenden wollen, können Sie Appium direkt über die Datei im ''bin''-Verzeichnis mit der entsprechenden Versionsnummer starten:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Falls Sie ein anderes Xcode als das als Standard konfigurierte verwenden wollen, müssen Sie Appium den entsprechenden Pfad über die Umgebungsvariable ''DEVELOPER_DIR'' angeben.
Wenn Sie Xcode z. B. in ''/Applications/Xcode-11.3.app'' installiert haben, müssten Sie Appium so starten:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Was als Standard-Xcode-Installation gesetzt ist, zeigt der Befehl:

xcode-select -p

Wenn Appium Ihre Xcode-Installation nicht findet, erscheint beim Verbinden eine Fehlermeldung in der Art:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
Starten Sie in diesem Fall Appium erneut, unter Angabe eines gültigen ''DEVELOPER_DIR''.

==== WebDriverAgent-Signierung ====
Zur Automatisierung lädt Appium eine App namens WebDriverAgent auf das Gerät und muss sie dafür signieren können. Dazu brauchen Sie einen Apple-Account und ein entsprechendes Zertifikat. Zur Evaluierung können Sie einen kostenlosen Account verwenden. Dieser hat den Nachteil, dass erstellte Profile nur eine Woche gültig sind und danach neu erstellt werden müssen. Seien Sie auch vorsichtig, wenn Sie sich den Account teilen, da es vorkommen kann, dass Zertifikate widerrufen werden oder durch automatische Generierung ungültig werden. Als Folge können bereits signierte Apps nicht mehr verwendet werden.

Wenn Sie bereits ein entsprechendes Zertifikat mit dem zugehörigen privaten Schlüssel in Ihrer [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac haben, können Sie den WebDriverAgent automatisch signieren lassen. Ansonsten empfiehlt es sich, die Signierung über Xcode einzustellen und zu verwalten.

Schließen Sie zuerst das Gerät, das Sie verwenden möchten, über USB an den Mac an. Stellen Sie sicher, dass sich der Mac und das Gerät im selben Netzwerk befinden, ansonsten kann es beim Verbindungsaufbau mit Appium zu Problemen kommen. Starten Sie Xcode und öffnen Sie ''Preferences''. Wechseln Sie zur Seite der Accounts und legen Sie einen Eintrag mit Ihrem Account an. Anschließend können Sie auf ''Manage Certificates...'' klicken, um die Zertifikate zu sehen, die zu diesem Account gehören. Zum Ausführen von Tests benötigen Sie ein iOS-Development-Zertifikat und den dazugehörigen privaten Schlüssel. Wenn Sie noch keines besitzen, erstellen Sie eines. Wenn Sie bereits eines haben, aber es nicht in Ihrem Schlüsselbund vorhanden ist (erkennbar an dem Hinweis "Not in Keychain"), können Sie es importieren. Das können Sie über die [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac machen, wenn Sie es zuvor aus dem Schlüsselbund exportiert haben, in dem es sich befindet. Das Zertifikat mit dem zugehörigen Schlüssel sollte sich im Schlüsselbund ''Anmeldung'' befinden. Dort kann es als PKCS#12-Datei (Endung typischerweise .p12) exportiert werden. Um ein Zertifikat in Ihren Schlüsselbund zu importieren, wählen Sie im Menü ''Ablage'' die Option ''Objekte importieren''. Falls Sie nicht wissen, wo das Zertifikat gespeichert ist, können Sie es in Xcode auch widerrufen und in Ihrem Schlüsselbund neu anlegen. Machen Sie das jedoch nur, wenn Sie wissen, dass das alte Zertifikat nicht mehr in Verwendung ist, da es danach nicht mehr benutzt werden kann. Nun sollte Ihr Schlüsselbund ein iOS-Development-Zertifikat enthalten.


Öffnen Sie nun das WebDriverAgent-Projekt in Xcode. Wenn Sie das Mobile Testing Supplement installiert haben, finden Sie es in dessen Verzeichnis unter
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
Wenn Sie Appium Desktop installier haben, finden Sie es unter
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''
Sie können einfach im Finder zu der Xcode-Project-Datei navigieren und Sie über einen Doppelklick öffnen. Beachten Sie dabei, dass Sie dabei auf die Anwendung Appium Server GUI einen Kontextklick (Rechtsklick bzw. Strg + Klick) machen und im Menü ''Paketinhalt anzeigen'' auswählen müssen, um in deren Unterverzeichnis zu gelangen.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Wählen Sie ''WebDriverAgentLib'' und die Seite ''Signing & Capabilities'' aus. Setzen Sie dort im Abschnitt ''Signing'' die Option ''Automatically manage signing'' und wählen Sie dann ein Team aus. Wechseln Sie nun zu ''WebDriverAgentRunner'' und tun Sie dort dasselbe.

Durch das Setzen des Teams sollten die Fehler für den WebDriverAgentRunner verschwinden. Sollte Xcode kein passendes Provisioning Profile für die Bundle ID ''com.facebook.WebDriverAgentRunner'' erstellen können, können Sie diese anpassen, dass sie zu Ihrem Zertifikat passt. Danach können Sie Xcode beenden oder auch, wie weiter unten beschrieben, direkt den Build über Xcode starten, damit das Projekt bereits gebaut ist, wenn Appium es verwenden möchte.

Wenn Sie sich nun von expecco eine Verbindung zu Ihrem Gerät aufbauen, wird der WebDriverAgent darauf installiert und gestartet, um anschließend zur zu testenden App zu wechseln. Eventuell muss auf dem Gerät muss der Ausführung des WebDriverAgents vertraut noch werden. Ein Anzeichnen dafür kann sein, dass die App WebDriverAgent zwar auf dem Gerät erscheint und zu starten versucht, danach aber wieder deinstalliert wird. Öffnen Sie dazu während des Verbindungsaufbaus auf dem Gerät in die Einstellungen und dort unter ''Allgemein'' den Eintrag ''Geräteverwaltung''. Dieser Eintrag ist nur sichtbar, wenn eine Entwickler-App auf dem Gerät installiert ist. Sie müssen daher möglicherweise warten, bis der WebDriverAgent installiert ist, bevor der Eintrag erscheint. Wählen Sie dort den Eintrag Ihres Apple-Accounts und vertrauen Sie ihm. Da der WebDriverAgent wieder deinstalliert wird, wenn der Start nicht funktioniert hat, müssen Sie dies während des Verbindungsaufbaus tun. Falls Ihnen das zu hektisch ist, können Sie auch folgenden Code ausführen:

<nowiki>xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test</nowiki>
bzw.
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

Damit wird der WebDriverAgent auf dem Gerät installiert ohne dass er wieder gelöscht wird.

Wenn es Probleme beim Installieren des WebDriverAgents gibt, können Sie auch versuchen, den Build über Xcode zu starten. Stellen Sie sicher, dass das richtige Target ''WebDriverAgent'' ausgewählt ist. Fehlermeldungen in Xcode zeigen vielleicht einfacher, wo das Problem liegt. Manchmal hilft es auch, es ein zweites Mal zu versuchen, weil es möglicherweise beim ersten Mal zu lange gedauert hat und abgebrochen wurde. Es kann sein, dass Sie während des Builds mehrmals aufgefordert werden, das Passwort für Ihren Schlüsselbund anzugeben.

[[Datei:WebDriverAgentCodesign.png]]

Lesen Sie auch die Dokumentation von Appium zum [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Aufsetzen von Tests mit iOS-Geräten]. In der [https://support.apple.com/en-us/HT204460 Dokumentation von Apple] finden Sie nähere Informationen zum Installieren und Vertrauen von Apps.

Ist der WebDriverAgent einmal auf dem Gerät installiert, wird er für spätere Verbindungen wieder verwendet und der Verbindungsaufbau sollte schneller funktionieren. Ebenso liegt dann die signierte Version bereits auf Ihrem Mac und muss nicht erneut gebaut werden, was die Verbindung zu weiteren Geräten ebenfalls beschleunigt. Wenn Sie wissen, dass bei Ihrem Verbindungsaufbau der WebDriverAgent erst noch signiert und gebaut werden muss, ist es ratsam, die Capability ''wdaLaunchTimeout'' zu setzen. Dieser Timeout, wie lange auf den Start der WebDriverAgents auf dem Gerät gewartet werden soll, liegt standardmäßig bei 60000$nbsp;ms. Der Build dauert aber häufig über eine Minute, sodass der Versuch zum Verbindungsaufbau dann abgebrochen wird. Ein Wert von 120000 hat sich hier als besser erwiesen.

== Konfiguration des Plugins ==
Bevor Sie loslegen, sollten Sie die Einstellungen des Mobile Testing Plugins überprüfen und ggf. anpassen.

Öffnen Sie im Menü den Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" den Eintrag "''Mobile Testing''" (s. Abb.). Standardmäßig werden diese Pfade automatisch gefunden (1). Um einen Pfad manuell anzupassen, deaktivieren Sie den entsprechenden Haken rechts davon. Sie erhalten in einer Drop-down-Liste einige Pfade zur Auswahl. Ist ein eingetragener Pfad falsch oder kann er nicht gefunden werden, wird das Feld rot markiert und es erscheint ein diesbezüglicher Hinweis. Stellen Sie sicher, dass alle Pfade richtig angegeben sind.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Konfiguration des Plugins]]

*'''appium''': Geben Sie hier den Pfad zur ausführbaren Datei an mit der Appium in der Kommandozeile gestartet werden kann. Unter Windows wird diese Datei in der Regel "<code>appium.cmd</code>" heißen. Dieser Pfad wird benutzt, wenn expecco einen Appium-Server startet.
*'''node''': Geben Sie hier den Pfad zur ausführbaren Datei an, die Node (auch "Node.js") startet. Dieser Pfad wird beim Starten eines Servers an Appium weitergegeben, damit Appium ihn unabhängig von der PATH-Variablen findet. Unter Windows heißt diese Datei in der Regel "<code>node.exe</code>".
*'''JAVA_HOME''': Geben Sie hier den Pfad zu einem JDK an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden. Um einzustellen, welches Java von expecco verwendet werden soll, setzen Sie diesen Pfad in den Einstellungen für die Java Bridge.
*'''ANDROID_HOME''': Geben Sie hier den Pfad zu einem SDK von Android an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden.
*'''adb''': Hier steht der Pfad zum adb-Befehl. Unter Windows heißt die Datei adb.exe. Diese wird von expecco beispielsweise verwendet, um die Liste der angeschlossenen Geräte zu erhalten. Diesen Pfad sollten Sie automatisch wählen lassen, da dann der Befehl im ANDROID_HOME-Verzeichnis verwendet wird. Dieser wird auch von Appium verwendet. Falls expecco und Appium jedoch verschiedene Versionen von adb verwenden kann es zu Konflikten kommen.
*'''android.bat''': Diese Datei wird nur benötigt, um damit den AVD und den SDK Manager zu starten. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.
*'''aapt''': Geben Sie hier den Pfad zum aapt-Befehl an. Unter Windows heißt diese Datei ''aapt.exe''. expecco verwendet aapt nur im Verbindungseditor, um das Paket und die Activities einer apk-Datei zu lesen. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | Konfiguration des JDKs]]

Ab expecco 2.11 gibt es das Feld ''Team-ID''. Wenn Sie iOS-Tests ausführen, tragen Sie hier die Team-ID Ihres Zertifikats ein. Diese wird für jede iOS-Verbindung verwendet, außer Sie setzen den Wert im Einzelfall in den Verbindungseinstellungen um. Wie Sie die Team-ID erhalten, lesen Sie im Abschnitt zur [[#Signierung|Signierung]] ber der Installation auf Mac OS. Mit expecco 2.10 können Sie die Team-ID nur für jede Verbindungseinstellung extra als Capability eintragen. Dazu müssen Sie jedoch die [[#Erweiterte_Ansicht|erweiterte Ansicht]] verwenden. Geben Sie hier die Capability ''xcodeOrgId'' an und setzen Sie als Wert die Team-ID des Zertifikats.

Die Einstellung zur Serveradresse unten auf der Seite bezieht sich auf das Verhalten des Verbindungseditors. Dieser prüft am Ende, ob die Serveradresse auf ''/wd/hub'' endet, da dies die übliche Form ist. Falls nicht, wird in einem Dialog gefragt, wie darauf reagiert werden soll. Das festgelegte Verhalten kann hier eingesehen und verändert werden.

Wechseln Sie ebenfalls zum Eintrag ''Java Bridge'' (s. Abb.). Hier muss der Pfad zu Ihrer Java-Installation angegeben werden, die von expecco benutzt wird. Tragen Sie hier ein JDK ein. Falls Sie unter Windows das aus dem Mobile Testing Supplement verwenden möchten, lautet der Pfad
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
Sie können auch die Systemeinstellungen verwenden.

== Android-Gerät vorbereiten ==
Wenn Sie ein Android-Gerät unter Windows anschließen benötigen Sie möglicherweise noch einen adb-Treiber für das Gerät. Einen passenden Treiber finden Sie üblicherweise auf der jeweiligen Webseite des Herstellers. Haben Sie den Universal-Treiber aus dem Mobile Testing Supplement installiert, sollte für die meisten Geräte bereits alles funktionieren. In einigen Fällen versucht auch Windows automatisch einen Treiber zu installieren, wenn Sie das Gerät zum ersten mal anschließen.
 
===USB-Debugging Einschalten===
'''Achtung:'''
Bevor Sie ein Mobilgerät mit dem Appium-Plugin ansteuern können, müssen Sie für dieses Debugging erlauben!

Für Android-Geräte finden Sie diese Option in den Einstellungen unter ''[https://www.droidwiki.org/wiki/Entwickleroptionen Entwickleroptionen]'' mit dem Namen ''[https://www.droidwiki.org/USB-Debugging USB-Debugging]''. Falls die Entwickleroptionen nicht angezeigt werden, können Sie diese freischalten, indem Sie unter "''Über das Telefon''" siebenmal auf "''Build-Nummer''" tippen.

===Wach bleiben Aktivieren===
Aktivieren Sie auch die Funktion ''Wach bleiben'', damit das Gerät nicht während der Testerstellung oder -ausführung den Bildschirm abschaltet.

Aus Sicherheitsgründen muss USB-Debugging für jeden Computer einzeln zugelassen werden. Beim Verbinden des Geräts mit dem PC über USB müssen Sie dabei am Gerät der Verbindung zustimmen. Falls Sie dies für Ihren Computer noch nicht getan haben, aber auf dem Gerät kein entsprechender Dialog erscheint, kann es helfen, das Gerät aus- und wieder einzustecken. Das kann insbesondere dann passieren, wenn Sie den ADB-Treiber installiert haben während das Gerät bereits über USB angeschlossen war. Falls auch das nicht hilft, öffnen Sie die Benachrichtigungen, indem Sie sie vom oberen Bildschirmrand herunter ziehen. Dort finden Sie die USB-Verbindung und Sie können die Optionen dazu öffnen. Wählen Sie einen anderen Verbindungstypen aus; in der Regel sollten MTP oder PTP funktionieren.

Sie können auch auf einem Emulator testen. Dieser muss nicht gesondert vorbereitet werden, da er bereits für USB-Debugging ausgelegt ist. Es ist sogar möglich, einen Emulator bei Testbeginn zu starten.

Um zu überprüfen, ob ein Gerät, das Sie an Ihren Rechner angeschlossen haben, verwendet werden kann, öffnen Sie den [[#Verbindungseditor|Verbindungseditor]]. Das Gerät sollte dort angezeigt werden.

=== Verbindung über WLAN ===
Es ist auch möglich, Android-Geräte über WLAN zu verbinden. Für Geräte mit Android 11 oder neuer ist dies direkt über WLAN möglich, im anderen Fall müssen Sie das Gerät zuerst über USB verbinden. Ab expecco 22.1 können Sie eine WLAN-Verbindung über den [[Mobile Testing Plugin#Verbindungseditor|Verbindungseditor]] aufbauen. Ansonsten ist es auch über die Eingabeaufforderung möglich.
==== Drahtlos verbinden über die Eingabeaufforderung mit expecco Versionen vor 22.1 (ab Android 11) ====
Mit expecco ab Version 22.1 funktioniert das einfacher über den Verbindungseditor.

Erlauben Sie in den Entwickleroptionen des Geräts Debugging über WLAN und öffnen Sie dessen Optionen. Sie müssen zuerst das Gerät mit dem Rechner koppeln. Wählen Sie dazu "''Gerät mit einem Kopplungscode koppeln''", um einen Kopplungscode und eine IP-Adresse mit Port zu erhalten. Öffnen Sie dann auf dem Rechner die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb pair <IP-Adresse des Geräts>:<Kopplungsport></nowiki>
wobei Sie <tt><IP-Adresse des Geräts>:<Kopplungsport></tt> durch die auf dem Gerät angezeigte IP-Adresse & Port ersetzen. Danach werden Sie aufgefordert, den Kopplungscode einzugeben. Wenn alles geklappt hat, sollte sich das Popup auf dem Gerät schließen und der Rechner als gekoppeltes Gerät angezeigt werden. Geben Sie dann in der Eingabeaufforderung ein:
<nowiki>adb connect <IP-Adresse des Geräts>:<Debug-Port></nowiki>
Die IP-Adresse ist hier noch die gleiche wie beim Koppeln, aber der Port ist ein anderer. Beides wird als IP-Adresse & Port auf dem Gerät angezeigt. Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie entweder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden. Häufig wird beim Neustart des Geräts auch die Erlaubnis für das Debugging über WLAN wieder zurückgesetzt und der verwendete Port ändert sich. Die Kopplung bleibt aber bestehen und muss beim nächsten Verbinden nicht noch einmal durchgeführt werden.

==== WLAN Verbindung über USB starten (Android 10 und früher) ====
Verbinden Sie zunächst das Gerät über USB mit dem Rechner. Öffnen Sie dann die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb tcpip 5555</nowiki>
Damit lauscht das Gerät auf eine TCP/IP-Verbindung an Port 5555. Sollten Sie mehrere Geräte angeschlossen oder Emulatoren laufen haben, müssen Sie genauer angeben, welches Gerät Sie meinen. Geben Sie in diesem Fall ein:
<nowiki>adb devices -l</nowiki>
Sie erhalten eine Liste aller Geräte, wobei die erste Spalte deren Kennung ist. Schreiben Sie dann stattdessen
<nowiki>adb -s <Gerätekennung> tcpip 5555</nowiki>
mit der Gerätekennung des gewünschten Geräts. Sie können die USB-Verbindung nun trennen. Jetzt müssen Sie die IP-Adresse Ihres Gerätes in Erfahrung bringen. Sie finden diese üblicherweise irgendwo in den Einstellungen des Geräts, beispielsweise beim Status oder in den WLAN-Einstellungen. Geben Sie dann ein:
<nowiki>adb connect <IP-Adresse des Geräts></nowiki>
Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie wieder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden.

=== Verbindung zu einem Emulator ===
Sie benötigen dazu den Emulator selbst, sowie mindestens ein AVD (Android Virtual Device). Hinweise zu Installation finden Sie in der [https://developer.android.com/studio/run/emulator Android Studio Dokumentation].

Wenn Sie Android Studio bereits mit den Defaulteinstellungen installiert haben 1), sollte der Emulator bereits mitinstalliert sein. Falls nicht, wählen Sie in Android Studio "''Configure''" - "''SDK Manager''" - "''Android SDK''" - "''SDK Tools''" - ''Android Emulator''", sowie dort die "''Platform Tools''".
Alternativ geht das auch über die Kommandzeile mit dem "sdkmanager" Kommando.

Als nächstes benötigen Sie mindestens ein AVD; auch dies geht am einfachsten über den Dialog in Android Studio:
wählen sie "''Configure''" - "''AVD Manager''" und folgen den Anweisungen (Deviceauswahl, Platform und Android Version).

Auch wenn Sie den Emulator automatisieren benötigen sie Appium; installieren Sie dieses entweder mit dem Mobile Testing Supplement, oder direkt von der Appium homepage (https://github.com/appium/appium-desktop/releases).

1)Android Studio selbst wird nicht von expecco benötigt; es bietet aber kompfortable Dialoge zum Installieren von Paketen und AVDs.

== iOS-Gerät und App vorbereiten ==
Das Ansteuern von iOS-Geräten ist nur über einen Mac möglich. Lesen Sie daher auch den Abschnitt zur [[#Mac_OS|Installation unter Mac OS]].

Bevor Sie ein Mobilgerät mit dem Mobile Testing Plugin ansteuern können, müssen Sie für iOS-Geräte ab iOS 8 Debugging erlauben. Aktivieren Sie dazu die Option ''Enable UI Automation'' unter dem Menüpunkt ''Entwickler'' in den Einstellungen des Geräts. Falls Sie den Eintrag ''Entwickler'' in den Einstellungen nicht finden, gehen Sie wie folgt vor: Schließen Sie das Gerät über USB an den Mac an. Dabei müssen Sie ggf. am Gerät noch der Verbindung zustimmen. Starten Sie Xcode und wählen Sie dann in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie dort Ihr Gerät aus. Danach sollte der Eintrag ''Entwickler'' in den Einstellungen auf dem Gerät auftauchen. Dazu müssen Sie möglicherweise die Einstellungen beenden und neu starten.

[[Datei:Alert.png | thumb | 270px | Beispiel für einen Alert unter iOS]]
Ein Verbindungsaufbau zu dem Gerät ist nicht möglich solange es bestimmte Alerts zeigt. Ein solcher Alert kann z. B. erscheinen wenn FaceTime aktiviert ist, indem ein Hinweis auf anfallende SMS-Gebühren angezeigt wird (siehe Screenshot). Achten Sie darauf, das Gerät so zu konfigurieren, dass es im Leerlauf keine solchen Alerts zeigt.

=== expecco 2.11 und später ===
Sie können beliebige Apps testen, die auf dem verwendeten Gerät lauffähig oder bereits installiert sind. Wenn die App als Development-Build vorliegt, muss die UDID des Geräts in der App hinterlegt sein. In jedem Fall muss der WebDriverAgent für das Gerät signiert werden. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]] unter Mac OS.

Falls Sie in einem Test den Home-Button verwenden wollen, müssen Sie auf dem Gerät AssistiveTouch aktivieren. Sie finden diese Option in den Einstellungen unter ''Allgemein'' > ''Bedienungshilfen'' > ''AssistiveTouch''. Platzieren Sie dann das Menü in der Mitte des oberen Bildschirmrands. Sie können das Drücken des Home-Buttons dann mit dem entsprechenden Menüeintrag im Recorder aufzeichnen oder direkt den Baustein ''Press Home Button'' benutzen.

=== expecco 2.10 ===
Die App, die Sie verwenden wollen, muss als Development-Build vorliegen. Außerdem muss die UDID des Geräts in der App hinterlegt sein.

=== Development-Build signieren ===
Ein Development-Build einer App ist nur für eine begrenzte Zahl von Geräten zugelassen und kann auf anderen Geräten nicht gestartet werden. Es ist aber möglich, das Zertifikat und die verwendbaren Geräte in einem Development-Build auszutauschen.

* Evaluierung mit Demo-App von eXept:
:Gerne stellen wir Ihnen eine Demo-App zur Verfügung, die als Development-Build vorliegt und die wir für Ihr Gerät signieren können. Senden Sie dazu bitte Ihrem eXept-Ansprechpartner die UDID Ihres Gerätes zu. Wie Sie die UDID Ihres Gerätes ermitteln können, ist im folgenden Abschnitt beschrieben.

* Eigene App für Ihr Testgerät verwenden:
:Wenn Sie von den App-Entwicklern einen Development-Build (IPA-Datei) erhalten, der für Ihr Testgerät zugelassen ist, können Sie diesen direkt verwenden. Dazu müssen Sie den Entwicklern die UDID Ihres Geräts mitteilen, damit sie diese eintragen können. '''Sie können die UDID eines Gerätes mithilfe von Xcode auslesen'''. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie Ihr Gerät aus und suchen Sie in Eigenschaften den Eintrag ''Identifier''. Die UDID ist eine 40-stellige Hexadezimalzahl.

* Extern entwickelte App für Ihr Testgerät umsignieren:
:Es können auch Apps umsigniert werden, damit Sie auf anderen Geräten lauffähig sind. Dieser Vorgang ist jedoch kompliziert und setzt insbesondere einen Zugang zu einem Apple-Developer-Account voraus. Eine Dokumentation zur Vorgehensweise ist derzeit in Vorbereitung.

:Für die Evaluierung unterstützen wir Sie gerne beim Umsignieren Ihrer App.


Weitere Informationen zur Verwendung von iOS-Geräten finden Sie auch in der [http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Dokumentation von Appium].

=== Native iOS-Apps ===
Sie können auch Apps verwenden, die bereits nativ auf dem Gerät vorhanden sind. Dazu müssen Sie deren Bundle-ID kennen und diese dann in die Verbindungseinstellungen eintragen. Hier eine kleine Auswahl gängiger Apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

Weitere Bundle-IDs finden Sie [https://github.com/joeblau/apple-bundle-identifiers hier].

= Beispiele =
Bei den Demo-Testsuiten für expecco finden Sie auch Beispiele für Tests mit dem Mobile Testing Plugin. Wählen Sie dazu auf dem Startbildschirm die Option "''Beispiel aus Datei''" und öffnen Sie den Ordner "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
Die Testsuite enthält zwei einfache Testpläne: "''Simple CalculatorTest''" und "''Complex Calculator and Messaging Test''". Beide Tests verwenden einen Android-Emulator, den Sie vor Beginn starten müssen. Die Apps, die im Test verwendet werden, gehören zur Grundausstattung des Emulators und müssen daher nicht mehr installiert werden. Da sich die Apps unter jeder Android-Version unterscheiden können, ist es wichtig, dass Ihr Emulator unter Android 6.0 läuft. Außerdem muss die Sprache auf Englisch gestellt sein.

; Simple CalculatorTest
: Dieser Test verbindet sich mit dem Taschenrechner und gibt die Formel ''2+3'' ein. Das Ergebnis des Rechners wird mit dem erwarteten Wert ''5'' verglichen.

; Complex Calculator and Messaging Test
: Dieser Test verbindet sich mit dem Taschenrechner und öffnet anschließend den Nachrichtendienst. Dort wartet er auf eine einkommende Nachricht von der Nummer ''15555215556'', in der eine zu berechnende Formel gesendet wird. Die Nachricht wird zuvor über einen Socket beim Emulator erzeugt. Nach dem Eintreffen der Nachricht wird diese vom Test geöffnet und deren Inhalt gelesen. Danach wird wieder der Taschenrechner geöffnet, die erhaltene Formel eingegeben und das Ergebnis gelesen. Anschließend wechselt der Test wieder zum Nachrichtendienst und sendet das Ergebnis als Antwort.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
Diese sind Bestandteil des Tutorials zum Mobile Testing Plugin. Der jeweils enthaltene Testfall ist unvollständig und wird im Zuge des Tutorials ergänzt. Lesen Sie dazu den Abschnitt [[#Tutorial|Tutorial]].

= Tutorial =
Es gibt ein Tutorial, das das grundsätzliche Vorgehen zur Erstellung von Tests mit dem Mobile Testing Plugin beschreibt. Grundlage dafür ist ein mitgeliefertes Beispiel, bestehend aus einer einfachen App und einer expecco-Testsuite.

Sie finden es auf der Seite [[Mobile_Testing_Tutorial|Mobile Testing Tutorial]] in zwei Versionen für Android und für iOS.
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_Android|Erste Schritte mit Android]]
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_iOS|Erste Schritte mit iOS]]

= Dialoge des Mobile Testing Plugins =
== Verbindungseditor ==
Mithilfe des Verbindungseditors können Sie schnell Verbindungen definieren, ändern oder aufbauen. Je nach Aufgabe weist der Dialog kleine Unterschiede auf und wird unterschiedlich geöffnet:
*Um eine Verbindung aufzubauen, klicken Sie im GUI-Browser auf "''Verbinden'"' klicken und wählen dann "''Mobile Testing''".
*Um eine bestehende Verbindung im GUI-Browser zu ändern oder zu kopieren, wählen Sie diese aus, machen einen Rechtsklick und wählen im Kontextmenü "''Verbindung bearbeiten''" oder "''Verbindung kopieren''" aus.
*Wollen Sie Verbindungseinstellungen nicht für den GUI-Browser sondern zur Verwendung in einem Test erstellen, wählen Sie im Menü des Mobile Testing Plugins den Punkt "''Verbindungseinstellungen erstellen...''". Darüber können nur die Einstellungen für eine Verbindung erstellt werden, ohne dass eine Verbindung tatsächlich angelegt wird.

Einige der Schaltflächen sind nur beim Erstellen von Verbindungseinstellungen sichtbar:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#"''Einstellungen löschen''": Setzt alle Einträge zurück. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Einstellungen aus Datei laden''": Erlaubt das Öffnen einer gespeicherten Einstellungsdatei (*.csf). Deren Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen aus Anhang laden''": Erlaubt das Öffnen eines Anhangs mit Verbindungseinstellungen aus einem geöffneten Projekt. Diese Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen in Datei speichern''" sowie
#"''Einstellungen in Anhang speichern''": Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern oder als Anhang in einem geöffneten Projekt anlegen. Beide Optionen besitzen ein verzögertes Menü, in dem Sie auswählen können, nur einen bestimmten Teil der Einstellungen zu speichern. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Erweiterte Ansicht''": Damit können Sie in die erweiterte Ansicht wechseln, um zusätzliche Einstellungen vorzunehmen. Lesen Sie dazu mehr am Ende des Kapitels. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Hilfe''": An der rechten Seite wird ein Hilfetext zum jeweiligen Schritt ein- oder ausgeblendet.

Der Dialog ist in drei Schritte unterteilt. Im ersten Schritt wählen Sie das Gerät, das Sie verwenden möchten, im zweiten Schritt wählen Sie aus, welche App verwendet werden soll und im letzten Schritt erfolgen die Einstellungen zum Appium-Server.

===Schritt 1: Gerät auswählen===
Im oberen Teil erhalten Sie eine Liste aller angeschlossenen Appium-Geräte, die erkannt werden. Mit der Checkbox darunter können Sie die Geräte ausblenden, die zwar erkannt werden, aber nicht bereit sind. Falls Sie ein Gerät eintragen wollen, das nicht angeschlossen ist, können Sie dies mit dem entsprechenden Knopf "''Android-Gerät eingeben''" bzw. "''iOS-Gerät eingeben''" anlegen. Dazu müssen Sie jedoch die benötigten Eigenschaften Ihres Geräts kennen. Das Gerät wird dann in einer zweiten Geräteliste angelegt und kann dort ausgewählt werden. Wenn keine Liste mit angeschlossenen Elementen angezeigt werden kann, werden stattdessen verschiedene Meldungen angezeigt:
*Keine Geräte gefunden
*:expecco konnte kein Android-Geräte finden.
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*Keine verfügbaren Geräte gefunden
*:expecco konnte keine verfügbaren Android-Geräte finden. Es wurden aber nicht verfügbare gefunden, z.B. mit dem Status "unauthorized".
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*:Um nicht verfügbare Geräte anzuzeigen, aktivieren Sie unten diese Option.
*Verbindung verloren
*:expecco hat die Verbindung zum adb-Server verloren. Versuchen Sie die Verbindung wieder herzustellen, indem Sie auf den Button klicken.
*Verbindung fehlgeschlagen
*:expecco konnte sich nicht mit dem adb-Server verbinden. Möglicherweise läuft er nicht oder der angegebene Pfad stimmt nicht.
*:Überprüfen Sie die adb-Konfiguration in den Einstellungen und versuchen Sie den adb-Server zu starten und eine Verbindung herzustellen indem Sie auf den Knopf klicken.
*Verbinden ...
*:expecco verbindet sich mit dem adb-Server. Dies kann einige Sekunden dauern.
*adb-Server starten ...
*:expecco startet den adb-Server. Dies kann einige Sekunden dauern.

Mit "''Weiter''" gelangen Sie zum nächsten Schritt. Wenn Sie Einstellungen für den GUI-Browser eingeben, ist das erst möglich, wenn ein Gerät ausgewählt wurde.

Anmerkung zum Freischalten: In jüngeren Android Versionen werden die Entwickleroptionen zunächst nicht mehr in den Einstellungen angeboten. Falls ihr Android Gerät in den Einstellungen keinen Eintrag zu "''Entwickleroptionen''" zeigt, wählen Sie zunächst den Eintrag "''Telefoninfo''", dann "''SoftwareVersionsInfo''" und klicken darin mehrfach auf den Eintrag "''BuildVersion''".

==== Chromedriver verwalten ====
Wenn die App, die Sie bedienen wollen, WebViews mit Chrome benutzt, benötigt Appium Zugriff auf einen passenden Chromedriver. Wenn Sie ein Gerät in der Liste auswählen, können Sie über "''Chromedriver verwalten''" sehen, welche Chrome-Versionen auf dem Gerät vorhanden sind und welche Chromedriver-Versionen durch expecco zur Verfügung stehen. Über diesen Dialog können Sie auch benötigte Chromedriver-Versionen herunterladen. Beachten Sie, dass auf dem Gerät verschiedene Chrome-Versionen vorhanden sein können, da die Apps in ihren WebViews nicht die gleiche Chrome-Version verwenden müssen, wie die als Browser installierte. Damit alles funktioniert, sollte der verwendete Chromedriver zur entsprechenden App passen. Sie können den Pfad zum Chromedriver auch am Ende des Verbindungsdialogs in den erstellten Capabilities ändern.

==== WLAN-Android-Geräte verbinden ====
Sie können sich auch über WLAN zu Android-Geräten verbinden. Dazu muss das Gerät zunächst mit adb verbunden werden, siehe [[Mobile_Testing_Plugin#Verbindung_.C3.BCber_WLAN|Verbindung über WLAN]]. Ab expecco 22.1 bietet der Verbindungseditor hierfür einen Dialog, der Ihnen dabei hilft und den Sie anstatt der Eingabeaufforderung verwenden können. Für Geräte mit Android 11 oder höher können Sie hier das Gerät mit dem Rechner zu koppeln, indem Sie die entsprechenden Parameter angeben und anschließend die Verbindung unter Angabe von IP-Adresse und Port aufbauen. Sie können damit auch für Geräte, die über USB verbunden sind, eine WLAN-Verbindung aufbauen. Wenn Sie das entsprechende Gerät in der Liste auswählen, werden die benötigten Angaben automatisch ausgelesen.

Beachten Sie, dass der Aufbau einer WLAN-Verbindung nicht Teil der Verbindungseinstellungen ist. Wenn Sie mit den erzeugten Einstellungen eine neue Verbindung aufbauen wollen, müssen Sie sicherstellen, dass das Gerät über mit der angegebenen IP-Adresse und dem Port mit adb verbunden ist, damit es gefunden wird. Die ADB-Verbindung geht verloren, wenn der ADB-Server oder das Gerät neu gestartet werden. Die Erlaubnis für das WLAN-Debugging wird beim Neustart des Geräts auch häufig zurückgesetzt und der Debug-Port kann dann wechseln. Daher muss eine WLAN-Verbindung immer manuell hergestellt werden.

===Schritt 2: App auswählen===
Hier können Sie Angaben zur App machen, die getestet werden soll. Dabei können Sie entscheiden, ob Sie eine App verwenden wollen, die bereits auf dem Gerät installiert ist, oder ob für den Test eine App installiert werden soll. Wählen Sie oben den entsprechenden Reiter aus. Je nachdem, ob Sie im vorigen Schritt ein Android- oder ein iOS-Gerät ausgewählt haben, ändert sich die erforderte Eingabe.

*'''Android'''
**''App auf dem Gerät''
**:Wenn Sie im ersten Schritt ein angeschlossenes Gerät ausgewählt haben, werden die Pakete aller installierten Apps automatisch abgerufen und Sie können die Auswahl aus den Drop-down-Listen treffen. Die installierten Apps sind in Fremdpakete und Systempakete unterteilt; wählen Sie die entsprechende Paketliste aus. Diese Auswahl gehört nicht zu den Einstellungen, sondern stellt nur die entsprechende Paketliste zur Verfügung. Sie können den Filter benutzen, um die Liste weiter einzuschränken und dann das gewünschte Paket auswählen. Die Activities des ausgwählten Pakets werden ebenfalls automatisch abgerufen und als Drop-down-Liste zur Verfügung gestellt. Wählen Sie die Activity aus, die gestartet werden soll. In der Regel wird automatisch eine Activity aus der Liste eingetragen. Falls Sie kein verbundenes Gerät verwenden, müssen Sie die Eingabe des Pakets und der Activity von Hand vornehmen.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Benutzen Sie einen lokalen Appium-Server, können Sie den rechten Butten benutzen, um zu der Installationsdatei der App zu navigieren und diesen Pfad einzutragen. Wenn möglich werden dabei auch das entsprechende Paket und die Activity in den Feldern darunter eingetragen. Diese Angabe ist aber nicht notwendig.

*'''iOS'''
**''App auf dem Gerät''
**:Geben Sie die Bundle-ID einer installierten App an. Sie können die IDs der installierten Apps bspw. mithilfe von Xcode erfahren. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü "''Window''" den Eintrag "''Devices''". Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wenn Sie Ihr Gerät auswählen, sehen Sie in der Übersicht eine Auflistung der von Ihnen installierten Apps.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Zu den Vorraussetzungen an Apps für reale Geräte lesen Sie bitte den Abschnitt [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Geräte und App vorbereiten]].

Im unteren Teil können Sie festlegen, ob die App beim Verbindungsabbau zurückgesetzt bzw. deinstalliert werden soll, und ob sie initial zurückgesetzt werden soll. Auch hier wird die entsprechende Capability gar nicht gesetzt, wenn Sie "''(Default)''" auswählen. Mit "''Weiter''" gelangen Sie zum nächsten Schritt.

===Schritt 3: Servereinstellungen===
Im letzten Schritt befindet sich zunächst im oberen Teil eine Liste aller Capabilities, die sich aus Ihren Angaben der vorigen Schritte ergeben. Wenn Sie sich mit Appium auskennen und noch zusätzliche Capabilities setzen möchten, die der Verbindungseditor nicht abdeckt, können Sie durch Klicken auf "''Bearbeiten''" in die erweiterte Ansicht gelangen. Lesen Sie dazu den Abschnitt weiter unten.

Wenn Sie Einstellungen für den GUI-Browser eingeben, können Sie den ''Verbindungsnamen'' eintragen, mit dem die Verbindung angezeigt wird. Dies ist auch der Name unter dem Bausteine diese Verbindung verwenden können, wenn sie aufgebaut ist. Wenn Sie das Feld frei lassen, wird ein Name generiert. Wenn der Haken für "''Von expecco gesteuert''" gesetzt ist, wird expecco einen lokalen Appium-Server an einem freien Port starten, oder einen bereits gestarteten freien Server verwenden. Um einen eigenen Server zu verwenden, schalten Sie diese Funktion ab und geben Sie die entsprechende Adresse ein. Sie erhalten die lokale Standard-Adresse und bereits verwendete Adressen zur Auswahl.

In älteren expecco-Versionen ist der Haken mit "''Bei Bedarf starten''" beschriftet. In diesem Fall müssen Sie auch eine Adresse angeben, wenn expecco den Server starten soll. expecco versucht dann beim Verbinden einen Appium-Server an der angegebenen Adresse zu starten, wenn dort noch keiner läuft. Dieser Server wird dann beim Beenden der Verbindung ebenfalls heruntergefahren. Dies funktioniert nur für lokale Adressen. Achten Sie darauf, nur Portnummern zu verwenden, die auch frei sind. Verwenden Sie am besten nur ungerade Portnummern ab dem Standardport 4723. Beim Verbindungsaufbau wird ebenfalls die folgende Portnummer verwendet, wodurch es sonst zu Konflikten kommen könnte.

Je nachdem, wie Sie den Dialog geöffnet haben, gibt es nun verschiedene Schaltflächen um ihn abzuschließen. In jedem Fall haben Sie die Option zu speichern. Dabei öffnet sich ein Dialog, indem Sie entweder ein geöffnet Projekt auswählen können, um die Einstellungen dort als Anhang zu speichern, oder auswählen es in einer Datei zu speichern, die Sie anschließend angeben können. Durch das Speichern wird der Dialog nicht beendet, wodurch Sie anschließend noch eine andere Option auswählen könnten.

Wenn Sie den Editor zum Verbindungsaufbau geöffnet haben, können Sie abschließend auf "''Verbinden''" oder "''Server starten und verbinden''" klicken, je nachdem, ob der Haken für den Serverstart gesetzt ist. Für das Ändern oder Kopieren einer Verbindung im GUI-Brower heißt diese Option "''Übernehmen''", da in diesem Fall nur der Verbindungseintrag geändert bzw. neu angelegt wird, der Verbindungsaufbau aber nicht gestartet wird. Das können Sie bei Bedarf anschließend über das Kontextmenü tun. Falls Sie Capabilities einer bestehenden Verbindung geändert haben, fordert Sie anschließend ein Dialog auf zu entscheiden, ob diese Änderungen direkt übernommen werden sollen, indem die Verbindung abgebaut und mit den neuen Verbindungen aufgebaut wird, oder nicht. In diesem Fall werden die Änderungen erst wirksam, nachdem Sie die Verbindung neu aufbauen.

Zur Verwendung des Verbindungseditors lesen Sie auch den entsprechenden Abschnitt im jeweiligen Tutorial in Schritt 1 (Android: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren|Demo ausführen]], iOS: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren_.28iOS.29|Demo ausführen (iOS)]]).

===Erweiterte Ansicht===
Die erweiterte Ansicht des Verbindungseditors erhalten Sie entweder durch Klicken auf "''Bearbeiten''" im dritten Schritt oder jederzeit über den entsprechenden Menüeintrag, wenn Sie den Editor über das Plugin-Menü gestartet haben. In dieser Ansicht erhalten Sie eine Liste aller eingestellten Appium-Capabilities. Zu dieser können Sie weitere hinzufügen, Einträge ändern oder entfernen. Um eine Capability hinzuzufügen, wählen Sie diese aus der Drop-down-Liste des Eingabefelds aus. In dieser befinden sich alle bekannten Capabilities sortiert in die Kategorien ''Common'', ''Android'' und ''iOS''. Haben Sie eine Capability ausgewählt, wird ein kurzer Informationstext dazu angezeigt. Sie können in das Feld auch von Hand eine Capability eingeben. Klicken Sie dann auf "''Hinzufügen''", um die Capabilitiy in die Liste einzutragen. Dort können Sie in der rechten Spalte den Wert setzen. Um einen Entrag zu löschen, wählen Sie diesen aus und klicken Sie auf "''Entfernen''". Mit "''Zurück''" verlassen Sie die erweiterte Ansicht.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Laufende Appium-Server ==
Im Menü des Mobile Testing Plugins finden Sie den Eintrag "''Appium-Server...''". Mit diesem öffnen Sie ein Fenster mit einer Übersicht aller Appium-Server, die von expecco gestartet wurden und auf welchem Port diese laufen. Durch Klicken auf das Icon in der Spalte "''Log anzeigen''" können Sie das Logfile des entsprechenden Servers anschauen. Dieses wird beim Beenden des Servers wieder gelöscht. Mit den Icons in der Spalte "''Beenden''" kann der entsprechenden Server beendet werden. Allerdings wird dies verhindert, wenn expecco über diesen Server noch eine offene Verbindung hat. Für welche Verbindung ein Server verwendet wird, sehen Sie in der rechten Spalte. Steht dort ''<idle>'' wird er zur Zeit nicht von expecco verwendet.

[[Datei:MobileTestingAppiumServer.png]]

Beim Öffnen des Editors um eine Appium-Verbindung aufzubauen, wird direkt ein Appium-Server gestartet, um den folgenden Verbindungsaufbau zu beschleunigen. Zu diesem Zweck hält sich expecco auch immer einen freien Appium-Server offen. Weitere laufende Server, die nicht mehr verwendet werden, werden jedoch nach einiger Zeit automatisch beendet.

Im Menü des Mobile Testing Plugins finden Sie auch den Eintrag "''Alle Verbindungen und Server beenden''". Dies ist für den Fall gedacht, dass Verbindungen oder Server auf andere Weise nicht beendet werden können. Beenden Sie Verbindungen wenn möglich immer im GUI-Browser oder durch Ausführen eines entsprechenden Bausteins. Server, die Sie in der Server-Übersicht gestartet haben, beenden Sie dort; Server, die mit einer Verbindung gestartet wurden, werden automatisch mit dieser beendet.

Beachten Sie, dass in der Übersicht nur Server aufgelistet sind, die von expecco gestartet und verwaltet werden. Mögliche andere Appium-Server, die auf andere Art gestartet wurden, werden nicht erkannt.

== Recorder ==
Besteht im GUI-Browser eine Verbindung zu einem Gerät, kann der integrierte Recorder verwendet werden, um mit diesem Gerät einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

[[Datei:MobileTestingRecorder.png|caption|]]

====Komponenten des Recorderfensters====
#'''Aufnahme fortsetzen/pausieren''': Über das rechte Symbol können Sie die Aufnahme pausieren. Sie sehen dann ein großes Pause-Symbol in der Anzeige. Alle Aktionen, die Sie währenddessen im Recorder machen werden zwar ausgeführt, es werden aber keine Bausteine aufgezeichnet. Über das linke Symbol können Sie dann wieder in den normalen Aufnahmemodus wechseln.
#'''Aufnahme stoppen''': Stoppt die Aufnahme und schließt das Recorderfenster.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Gerät. Dies wird nötig, wenn das Gerät zur Ausführung einer Aktion länger braucht oder sich etwas ohne das Anstoßen durch den Recorder ändert. Seit expecco 21.2 gibt es hier zusätzlich ein Untermenü, mit dem automatisches Aktualisieren angeschaltet werden kann, indem im Hintergrund auf Änderungen geprüft wird (siehe auch ''Automatisches Aktualisieren'' weiter unten).
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Elemente einzeichnen''': Die Rahmen aller Elemente der Ansicht werden angezeigt.
#'''Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst. Dabei stehen folgende Aktionen zur Verfügung:
#*Aktionen auf Elemente:
#**Klicken: Kurzer Klick auf das Element, über dem der Cursor steht. Zur genaueren Bestimmung, welches Element verwendet wird, benutzen Sie die Funktion Follow-Mouse oder Element-Highlighting.
#**Antippen mit Dauer (Element): Ähnlich zum Klicken, nur dass zusätzlich die Dauer des Klicks aufgezeichnet wird. Dadurch sind auch längere Klicks möglich.
#**Antippen mit Position (Element): Ähnlich zum Klicken, aber zusätzlich wird die Position innerhalb des Elements aufgenommen. Die Position kann relativ zur Größe des Elements aufgenommen werden oder, wenn Sie dabei Strg gedrückt halten, absolut zur linken oberen Ecke des Elements.
#**Text setzen: Ermöglicht das Setzen eines Textes in Eingabefelder.
#**Text löschen: Löscht den Text eines Eingabefelds.
#*Aktionen auf das Gerät:
#**Antippen (Bildschirm): Löst einen Klick auf die Bildschirmposition aus.
#**Antippen mit Dauer (Bildschirm): Löst einen Klick auf die Bildschirmposition aus, bei dem auch die Dauer berücksichtigt wird.
#**Wischen: Wischen in einer geraden Linie vom Punkt des Drückens des Mausknopfes bis zum Loslassen. Die Dauer wird ebenfalls aufgezeichnet.
#:Beachten Sie bei diesen Aktionen, dass das Ergebnis sich auf verschiedenen Geräten unterscheiden kann, bspw. bei verschiedenen Bildschirmauflösungen.
#*Erstellen von Testablauf-Bausteinen
#**Attribut prüfen: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Das Ergebnis triggert den entsprechenden Ausgang.
#**Attribut zusichern: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Bei Ungleichheit schlägt der Test fehl.
#**Attribut holen: Liest den aktuellen Wert eines Attributs aus.
#*Automatisch
#:Ist das Auto-Werkzeug ausgewählt, können alle Aktionen durch spezifische Eingabeweise benutzt werden: ''Klicken'', ''Element antippen'' und ''Wischen'' funktionieren weiterhin durch Klicken, wobei sie anhand der Dauer und der Bewegung des Cursors unterschieden werden. Um ein ''Antippen'' auszulösen, halten Sie beim Klicken Strg gedrückt. Die übrigen Aktionen erhalten Sie durch einen Rechtsklick auf das Element in einem Kontextmenü.
#'''Kontext-Aktionen''': Hier können Sie Aktionen aufzeichnen, die Kontexte betreffen:
#*Zu Kontext wechseln: Bietet eine Liste der aktuell verfügbaren Kontexte und Sie können auswählen, zu welchem gewechselt werden soll.
#*Aktuellen Kontext holen: Holt den Handle des aktuellen Kontexts.
#*Kontext-Handles holen: Holt eine Liste aller aktuell verfügbaren Kontext-Handles.
#'''Softkeys''': Nur unter Android. Simuliert das Drücken der Knöpfe Zurück, Home, Fensterliste und Power.
#'''Home-Button''': Nur unter iOS ab expecco 2.11. Ermöglicht das Drücken des Home-Buttons. Vor expecco 19.2 funktioniert es nur, wenn AssistiveTouch aktiviert ist und sich das Menü in der Mitte des oberen Bildschirmrands befindet. Ab expecco 19.2 verwendet die Funktion kein AssistiveTouch mehr.
#'''Hilfe''': Öffnet diese Online-Dokumentation auf der allgemeinen Seite zu [[GuiBrowser_Recorder|GUI-Browser Recordern]].
#'''Anzeige''': Zeigt einen Screenshot des Geräts. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Ansicht anpassen''': Öffnet einen Dialog um die Ansicht anzupassen, falls expecco das Bild nicht richtig darstellt. Sie können die Skalierung anpassen oder das Bild um 90° drehen.
#'''Ausrichtung anpassen''': Korrigiert das Bild, falls dieses auf dem Kopf stehen sollte. Über den Pfeil rechts daneben kann das Bild auch um 90° gedreht werden, falls dies einmal nötig sein sollte. Ab expecco 19.1 finden Sie diese Funktion in ''Ansicht anpassen''. Die Ausrichtung des Bildes ist für die Funktion des Recorders unerheblich, dieser arbeitet ausschließlich auf den erhaltenen Elementen.
#'''Skalierung''': Ändert die Skalierung des Screenshots.
#'''Meldungen''': Zeigt den Pfad des ausgewählten Elements oder andere Meldungen an. Es gibt ein Kontextmenü, um eine Liste der vorigen Meldungen zu sehen.

====Verwendung====
Mit jedem Klick im Fenster wird eine Aktion ausgelöst und im Arbeitsbereich des GUI-Browsers aufgezeichnet. Dort können Sie das Aufgenommene abspielen, editieren oder daraus einen neuen Baustein erstellen.
Aktionen zum Auslösen von Sofkeys finden Sie direkt in der Menüleiste (s.o.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Werkzeugs in der Menüleiste (s.o.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion.
Zur Verwendung des Recorders lesen Sie auch Schritt 2 im Tutorial ([[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen|Android]] bzw. [[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen_.28iOS.29|iOS]]).

====Elemente verbergen====
Ab expecco 21.2 gibt es im Kontextmenü außerdem die Möglichkeit, das ausgewählte Element im Recorder zu verbergen. Das bedeutet, dass dieses Element fortan nicht mehr ausgewählt werden kann. Diese Funktion eignet sich dazu, Elemente zu ignorieren, die im Vordergrund liegen, um auf Elemente darunter zugreifen zu können. Um diesen Zustand wieder rückgängig zu machen, müssen Sie das entsprechende Element im Baum des GUI-Browsers finden, dort gibt es im Kontextmenü ebenfalls einen solchen Eintrag.

====Automatisches Aktualisieren====
Der Recorder zeigt kein Livebild des Geräts sondern nur eine Momentaufnahme. Um mit der Anzeige auf dem Gerät übereinzustimmen muss daher nach Änderungen aktualisiert werden. Der Recorder aktualisiert sich automatisch, nachdem er eine Aktion ausgeführt hat. Ab expecco 20.2 sind zudem weitere automatische Updates möglich. Sie können Sie im Menü ''Fenster'' aktivieren.

Zum einen kann kurze Zeit nach dem Ausführen einer Aktion überprüft werden, ob es noch Änderungen nach der ersten Aktualisierung gegeben hat, damit in diesem Fall eine zweite Aktualisierung stattfinden kann. Dies soll das Problem beheben, dass der Recorder nach einer Aktion nicht aktuell ist, weil die Aktualisierung zu früh stattgefunden hat.

Zum anderen kann eine periodische Aktualisierung eingeschaltet werden. Nach einem einstellbaren Interval wird der Recorder automatisch aktualisiert, sollte es Änderungen geben. Dadurch ist die Anzeige im Recorder immer weitgehend aktuell, allerdings entsteht dadurch auch ein Mehraufwand was die Kommunikation mit dem Gerät betrifft.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid-Apps und WebViews =

'''!!! WICHTIGER HINWEIS - Wenn Sie Probleme haben, auf den Webview zu wechseln, geben Sie bitte unter den Android Einstellungen - Apps -Standard Apps "Chrome" als "Browser-App" an !!!
'''

Hybrid-Apps enthalten neben den Plattform-nativen Elementen weitere Elemente, die in einen WebView eingebunden sind. Diese Elemente können ebenfalls bedient werden, allerdings muss zuvor in den entsprechenden Kontext gewechselt werden. Mit dem Baustein "''Get Current Context''" erhalten Sie den aktuellen Kontext. Zu Beginn ist dies "''NATIVE_APP''", also der Kontext der nativen Elemente. Mit dem Baustein "''Get Context Handles''" bekommen Sie eine Collection aller vorhandenen Kontexte. Gibt es einen WebView-Kontext, so heißt dieser "''WEBVIEW_1''" oder "''WEBVIEW_<package>''" mit dem Paket des WebViews. Es kann auch mehrere WebView-Kontexte geben. Zu jedem WebView-Kontext gibt es im nativen Kontext ein entsprechendes WebView-Element. Mit dem Baustein "''Switch to Context''" können Sie in einen solchen Kontext wechseln und haben fortan nur Zugriff auf die Elemente in diesem Kontext.

Im GUI-Browser werden zum einen oben im Baum die vorhandenen Kontexte angezeigt, zum anderen wird der Baum eines Kontexts unterhalb des entsprechenden WebView-Elements eingefügt.

= XPath anpassen mithilfe des GUI-Browsers =
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen "''GTIN-13 (EAN-13)''" und "''Verify''", das Eingabefeld der Zahl "''4006381333986''" und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des "''GTIN-13''"-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch "''Pfad überprüfen''" (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit "''Verify Path: OK''" (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit "*" zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert "''GTIN-13 (EAN-13)''" besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer "''hierarchy''" (für iOS wäre es "''AppiumAUT''"), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix "''android.widget.''", das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend "''XCUIElementType''" am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. "''FrameLayout''" ist ein Kindelement von "''hierarchy''", "''LinearLayout''" ist ein Kind von "''FrameLayout''" usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element "''hierarchy''" beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben "''TextView''"-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ "''Button''" gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut "''resource-id''". Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut "''name''" verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem "@" eingeleitet und der Wert mit einem "=" in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter "''Test''" eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf "''Lauf''". Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu "''Eigenschaften''", wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

== Weitere Locator-Strategien ==
Appium bietet neben XPath noch weitere Strategien zur Adressierung von Elementen an. Einige davon stehen Ihnen '''ab Version 20.1''' ebenfalls mit expecco zur Verfügung. Diese sind nicht ganz so mächtig wie XPath, dafür aber häufig schneller bei der Auflösung auf dem Gerät. Insbesondere bei der Verwendung mit iPhones, wo die Hierarchie bei jeder XPath-Auflösung erst aufgebaut werden muss, bieten alternative Strategien einen Vorteil für die Laufzeit.

XPath ist weiterhin der Standard, das heißt alle Locator ohne besondere Angabe werden als XPath interpretiert. Um eine der anderen Strategien zu verwenden, schreiben Sie diese mit einem Gleichzeichen vor den gewünschten Locator. Diese Technik können Sie sowohl an den Blöcken verwenden, als auch im GUI-Browser testen.

{|
|-
| style="vertical-align:top" | AccessibilityId || style="padding-bottom:0.5em" | Verwendet den Wert des Elements, der dazu dient, die App barrierefrei zu machen. Für iOS ist das das Attribut '''Accessibility-id''', für Android das Attribut '''content-descr'''. ''Beispiel: accessibilityId=Löschen''
|-
| style="vertical-align:top" | className || style="padding-bottom:0.5em" | Verwendet den Namen der Klasse des Elements. ''Beispiel: className=android.widget.FrameLayout''
|-
| style="vertical-align:top" | id || style="padding-bottom:0.5em" | Verwendet die Kennung des Elements. Für iOS ist das das Attribut '''name''', für Android das Attribut '''resource-id'''. ''Beispiel: id=android:id/text1''
|-
| style="vertical-align:top" | iOSClassChain1 || style="padding-bottom:0.5em" | Verwendet die Hierarchie der Elemente ähnlich wie bei XPath. Eine Erklärung zum Aufbau finden Sie [https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules hier]. ''Beispiel: iOSClassChain=XCUIElementTypeWindow/XCUIElementTypeButton[`label == "Ok"`]''
|-
| style="vertical-align:top; padding-right:1em" | iOSNsPredicateString1 || style="padding-bottom:0.5em" | Verwendet einfache Kriterien, wie Attribute, die auch kombiniert werden können. ''Beispiel: iOSNsPredicateString=type == 'XCUIElementTypeButton' AND name == 'Weiter'''
|-
| style="vertical-align:top" | name1 || style="padding-bottom:0.5em" | Verwendet den Namen des Elements. ''Beispiel: name=Bestätigen''
|-
|}

:1 ''nur für iOS''

Um eine direkte Beschleunigung mit iOS zu erzielen, ohne dass Sie Ihre bisherigen Pfade anpassen müssen, wandelt expecco zudem Pfade, die nur aus einem Element mit Klasse und name-Attribut bestehen, zur Laufzeit automatisch in einen entsprechenden Locator der Strategie iOSNsPredicateString um. Wenn Sie einen Pfad explizit als XPath markieren, wird diese Anpassung nicht vorgenommen.

=Probleme und Lösungen=
== Locator sind versionsabhängig oder variabel ==
Dann sollten Sie die Locator (xPath) entweder in einer Variablen halten oder ein Locator-Mapping in einem Screenplay Anhang definieren. Es ist auch möglich, lediglich Teile des Locators (z.B. Locator-Pfad eines Elternelements oder Attributwert) in einer Variable zu halten und im Freezevalue des Locator-Pins mit "''$(varName)''" einzufügen.

==Unsichtbare UI-Elemente==
Beachten Sie, dass im [[#Recorder|Recorder]] auch Elemente berücksichtigt werden, die Sie auf dem Bildschirm nicht sehen. Schalten Sie daher das Element-Highlighting an oder nutzen Sie die Follow-Mouse-Funktion und den Elementbaum im GUI-Browser, um festzustellen, ob das richtige Element verwendet wird. Es kann vorkommen, dass unsichtbare Elemente vor anderen Elementen liegen und diese verdecken, so dass die gewünschten Elemente im Recorder nicht ausgewählt werden können. Lesen Sie dazu den Abschnitt [[#Elemente_verbergen|Elemente verbergen]].

==''org.openqa.selenium.StaleElementReferenceException''==
Der Fehler <code>org.openqa.selenium.StaleElementReferenceException</code> tritt immer dann auf, wenn ein Element verwendet wird, das nicht mehr da ist. Wenn das in Ihrem Test passiert und das Element eigentlich da sein sollte, verwenden Sie an der Stelle stattdessen den Locator (XPath), um das Element neu zu holen.

In manchen Fällen kann dieser Fehler auch dann auftreten, wenn Sie am Baustein bereits Locator angegeben haben. Das liegt daran, dass immer zuerst der Locator aufgelöst und das entsprechende Element geholt wird und dann die Aktionen mit dem Element ausgeführt wird. Wenn die App das Element genau zwischen dem Zeitpunkt des Auflösens und Holens und der Ausführung der Aktion aktualisiert und dabei ein neues Element erzeugt, kommt es zu diesem Fehler. Passiert das an einer bestimmten Stelle in Ihrem Test, bleibt nichts anderes als den Fehler abzufangen und es erneut zu versuchen.

==iOS: Kabel nicht zertifiziert==
In manchen Fällen erscheint beim Verbinden eines iOS-Geräts über USB der Hinweis, das verwendete Kabel sei nicht zertifiziert. In diesem Fall hilft es nur, das entsprechende Kabel auszutauschen.
==iOS: Alerts beim Verbindungsaufbau==
Stellen Sie sicher, dass beim Verbindungsaufbau mit einem iOS-Gerät keine Alerts geöffnet sind. Der Aufbau schlägt sonst fehl, da die App nicht in den Vordergrund kommen kann. Siehe auch [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Gerät und App vorbereiten]].

==iOS: .ipa installieren nicht möglich==
Beachten Sie, dass auf iOS-Simulatoren keine ''.ipa''-Dateien sondern nur ''.app''-Dateien installiert werden können.

==iOS: Erster Verbindungsaufbau funktioniert nicht==
Wenn auf Ihrem Mac noch kein signierter Build des WebDriverAgents liegt, muss dieser beim ersten Verbindungsaufbau erst erzeugt werden. Das kann in der Regel etwas länger als eine Minute dauern. Standardmäßig verwendet Appium aber einen Timeout von 60000 ms um zu warten bis der WebDriverAgent auf dem Gerät startet, so dass der Aufbau in diesen Fällen abgebrochen wird. Sie können den Timeout mit der Capability ''wdaLaunchTimeout'' setzen, z.B. auf ''120000''.

Außerdem müssen die Einstellungen für die Signierung passen. Am zuverlässigsten funktioniert das nach unserer Erfahrung, wenn man im Xcode-Projekt des WebDriverAgents auf automatische Signierung stellt und das Team setzt. Siehe dazu die Erklärung im Abschnitt [[#WebDriverAgent-Signierung|WebDriverAgent-Signierung]]. In diesem Fall sollten Sie die Capabilities ''xcodeConfigFile'' bzw. ''xcodeOrgId'' und ''xcodeSigningId'' '''nicht''' verwenden, da es sonst zu Konflikten kommen kann. Achtung: Wenn Sie eine Team-ID in den Mobile-Testing-Einstellungen gesetzt haben, setzt expecco diese automatisch als ''xcodeOrgId''!

Achten Sie beim ersten Verbindungsaufbau außerdem auf Ihr Gerät, da Sie dort möglicherweise der Installation per Passwort zustimmen müssen. Auf dem Mac kann die Eingabe des Passworts zur Freigabe des Schlüsselbunds für die Signierung nötig werden, häufig auch mehrmals.

==Android: Gerät nicht im Verbindungsdialog==
Wenn ein über USB angeschlossenes Android-Gerät nicht im Verbindungsdialog auftaucht, versuchen Sie, den USB-Verbindungstyp zu ändern. In der Regel sollten MTP oder PTP funktionieren. Prüfen Sie nochmal, ob "USB Debugging" in den Entwicklereinstellungen des Geräts aktiviert ist (diese Einstellungen sind bei manchen Geräten zunächst unsichtbar, und müssen durch einen Trick zugänglich gemacht werden). Siehe auch [[#Android-Ger.C3.A4t_vorbereiten|Android-Gerät vorbereiten]].

==Android: Abgeschnittene Elemente unten==
Bei Android-Geräten, die die Steuerungsleiste bzw. Softkeys automatisch ein- und ausblenden, kann es vorkommen, dass der Recorder im unteren Bereich Elemente abschneidet, die durch die Softkeys verdeckt würden, auch wenn sie zu diesem Zeitpunkt gar nicht angezeigt werden. In diesem Fall hift es, die Softkeys so einzustellen, dass sie in einer permanenten Leiste angezeigt werden.

Bei neueren Android-Versionen gibt es eine solche Einstellung in der Regel nicht. Auch wenn die Steuerelemente permanent eingeblendet sind, liegen sie auf keiner extra Leiste, sondern vor dem Inhalt der App. Es gibt dann im unteren Teil einen Bereich, der nicht bedient werden kann, weil er nicht zum aktiven Bereich der App gezählt wird, weshalb die Elemente von Appium abgeschnitten werden. Dieser Bereich kann auch größer sein als von den Steuerungselementen beansprucht. Bekannt ist dies für Samsung-Geräte mit Android 11. Da die Information über die Größe des App-Bereichs bereits auf Android-Ebene so geliefert wird, können wir hierfür keine Lösung anbieten, sondern können nur hoffen, dass das Problem vom Hersteller behoben wird. Sie können versuchen, ob Sie mit der Einstellung von Gestensteuerung bessere Ergebnisse bekommen, allerdings gibt es hier das gleiche Problem.

== Android: Test hängt beim Suchen eines Elements==
Der Baustein ''Find Element by XPath'' und alle Element-Bausteine warten bis ein Element zum angegebenen Pfad auftaucht. Den Timeout dafür kann man entweder am Baustein direkt oder in den Umgebungsvariablen ändern. Wenn das Element aber bereits da sein sollte und es dennoch sehr lange dauert, bis der Test weitergeht, kann das am UIAutomator/UIAutomator2 liegen. Dieser wartet, bis die App in den Idle-Zustand geht, bevor er überhaupt nach Elementen sucht. Dies kann länger dauern, wenn die App z.B. im Hintergrund noch Animationen abspielt oder andere Aktionen ausführt. Auch das Holen des Page-Sources z.B. beim Aktualisieren im GUI-Browser oder im Recorder kann dadurch länger dauern. Standardmäßig gibt es hierfür einen Timeout von 10 Sekunden, nach dem nicht weiter auf den Idle-Zustand gewartet wird. Dieser Timeout lässt sich durch eine Einstellung in Appium anpassen (waitForIdleTimeout). Falls Sie einen anderen Wert für diesen Timeout setzen möchten, ist dies ab expecco 21.2 möglich, indem Sie vor dem Test den Smalltalk-Code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> ausführen. Der Timeout wird in Millisekunden angegeben, das Beispiel setzt ihn also auf 2 Sekunden.

==Android: Aktualisieren des Trees oder Wechseln zum Webview-Kontext braucht zu lange==
Speziell mit älteren Geräten kann es vorkommen, dass neuere Chromedriver nicht initialisiert werden können. Das führt dann dazu, dass nicht in den Webview-Kontext gewechselt werden kann. Dies wird von Appium allerdings nur über einen Timeout festgestellt, der standardmäßig bei 4 Minuten liegt. Da expecco auch beim Aufbauen des Trees im GUI-Browser versucht in den Webview-Kontext zu wechseln, kann das zu sehr langen Ladezeiten führen. Da es in Appium keine Möglichkeit gibt, diesen Timeout herunter zu setzen, haben wir die Version, die wir im MobileTestingSupplement bereitstellen, um eine entsprechende Capability erweitert. Ab der Version 1.13.1.0 des [[#Windows|MobileTestingSupplements]] kann mit ''chromedriverStartTimeout'' der Timeout in Millisekunden gesetzt werden. Der Wechsel funktioniert dadurch zwar trotzdem nicht, aber expecco braucht dann nicht mehr so lange beim Aktualisieren des Trees und der Baustein zum Wechseln des Kontextes schlägt schneller fehl. Der Verbindungsdialog fügt diese Capability ab expecco 22.1 automatisch hinzu.

==Keine Aktion bei Klick==
Der Baustein zum Klicken auf ein Element ist erfolgreich, aber auf dem Gerät wurde keine Aktion ausgeführt.
:Dies kann vorkommen, wenn das Element von einem anderen Element verdeckt ist und ein Klick auf das Element deshalb nicht möglich ist. In diesem Fall wird von Appium kein Fehler geworfen, sondern es passiert einfach nichts. Wenn Sie dennoch einen Klick an der Position des Elements machen möchten, auch wenn es verdeckt ist, benutzen Sie stattdessen den Baustein ''Tap'' und übergeben Sie diesem die Position des Elements (''Get Location''). Wenn Sie stattdessen vor einem Klick prüfen möchten, ob das Element zu diesem Zeitpunkt verdeckt ist, versuchen Sie, ob Ihnen die Eigenschaften ''Is Displayed'' oder ''Is Enabled'' weiterhelfen.

==Kein Update nach Aktion==
Über den Recorder wurde eine Aktion ausgeführt, für die auch ein Baustein aufgezeichnet wurde, der Recorder zeigt aber immer noch das alte Bild.
:Der Recorder zeigt kein Livebild des Geräts, sondern immer nur eine Momentaufnahme. Nachdem eine Aktion ausgeführt wurde, aktualisiert sich der Recorder automatisch. Es kann aber vorkommen, dass das Bild schon aktualisiert wurde, bevor die Auswirkungen der Aktion auf dem Gerät vollständig abgeschlossen sind. In diesem Fall sollten Sie den Recorder von Hand aktualisieren über das Symbol mit den blauen Pfeilen. Ab expecco 20.2 können Sie für diesen Fall auch automatisches Aktualisieren einstellen. Siehe auch Beschreibung zum [[#Recorder|Recorder]].

=="clickable" Attribut falsch==
Ein Element hat im "''clickable''" Attribut/Property den Wert "''false''", ist aber dennoch anklickbar.
:Das "''clickable''" Attribute muss explizit vom App-Programmierer gesetzt werden, und hat tatsächlich keine Relevanz für das tatsächliche Verhalten der App. Sie sollten dieses Attribut i.A. in Ihren Tests nicht beachten. Leider existieren viele Apps, bei denen der Programmierer hier "lazy" war.

==Verbindungsaufbau schlägt fehl==
Schlägt der Verbindungsaufbau mit dem Appium-Server fehl, erhalten Sie in expecco eine Fehlermeldung ähnlicher der unten abgebildeten.

[[Datei:MobileTestingVerbindungsfehler.png]]

Hier sehen Sie die Art des aufgetretenen Fehlers. Klicken Sie auf "''Details''" um nähere Informationen zu erhalten. Mögliche Fehler sind:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:Der angegebene Server läuft nicht oder ist nicht erreichbar. Überprüfen Sie die Serveradresse.
*''org.openqa.selenium.WebDriverException''
:Lesen Sie in den Details in der ersten Zeile die Meldung hinter ''Original Error'':
:*''Unknown device or simulator UDID''
::Entweder ist das Gerät nicht richtig angeschlossen oder die udid stimmt nicht.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::Dieser Fehler kann verschiedene Ursachen haben. Entweder konnte tatsächlich der WebDriverAgent nicht gebaut werden, weil die Signierungseinstellungen falsch sind oder das passende Provisioning Profile fehlt. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]]. Es kann auch sein, dass der WebDriverAgent auf dem Gerät nicht gestartet werden kann, weil sich beispielsweise ein Alert im Vordergrund befindet oder Sie dem Entwickler nicht vertraut haben.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::Die angegebene App kann nicht auf dem iOS-Gerät installiert werden, weil es nicht im Provisioning Profile der App eingetragen ist.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.'''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die Datei unter dem angegebenen Pfad auf dem Mac befindet.
:*''packageAndLaunchActivityFromManifest failed.''
::Die angegebene ''apk''-Datei ist vermutlich kaputt.
:*''Could not find app apk at [...]''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die ''apk''-Datei am angegebenen Pfad befindet.

Falls der Fehler nicht durch eine der oben gelisteten Ursachen bedingt ist, kann es sein, dass die auf dem Gerät befindlichen Automation-Anwendungen nicht mehr richtig funktionieren. Hier hilft es, diese vom Mobilgerät zu deinstallieren. Beim nächsten Verbindungsaufbau werden sie dann automatisch neu installiert.

*Für iOS-Geräte ist das der WebDriverAgent, den Sie einfach vom Home-Screen deinstallieren können. Dies behebt in der Regel Probleme durch den Wechsel des verwendeten Macs oder der Xcode-Version.

*Für Android-Geräte ist es der UIAutomator2; hier tritt auf einigen Geräten sporadisch ein Problem auf, die Ursache dafür ist uns z.Z. noch nicht bekannt. Zur Deinstallation navigieren Sie auf dem Gerät zu "''Einstellungen''" > "''Anwendungen''"* und suchen in der Liste nach folgenden Einträgen:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Klicken Sie auf die jeweilige Anwendung und dann auf "''Deinstallieren''".
*''Der entsprechende Eintrag heißt auf manchen Geräten möglicherweise etwas anders.''

Falls dies nicht hilft, kann eventuell die Ausgabe des Appium-Servers weiterhelfen. Für einen von expecco gestarteten Server finden Sie das Log in der Liste der [[#Laufende_Appium-Server|laufenden Appium-Server]].

==Ich habe keinen Mac==
Vielleicht hilft Ihnen diese Webseite weiter: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

CompoundBlock Element

2024-07-17T12:33:01Z

Matilk: /* Editoren */ translated

== Einführung ==
Ein zusammengesetzter Aktionsblock (englisch "''Compound Action''") beschreibt das Verhalten einer [[Block_Element|Aktion]] graphisch als Aktivitätsdiagramm. Diese Diagramme sind vergleichbar mit den [[#Relation_zu_UML_Aktivit.C3.A4tsdiagrammen|Datenflussdiagrammen]] wie in UML2.0 definiert. Sie haben außerdem viele Eigenschaften gemein mit [[#Relation_zu_Petrinetzen|Petrinetzen]]. Das Diagramm besteht aus Unteraktionen, welche als [[DiagramElements-Step|''Schritte'']] bezeichnet werden.

Die Ausführung wird durch eine Kombination von Daten- und Kontrollflüssen gesteuert, die durch Verbindungen zwischen den Schritten übertragen werden:
* Als Datenfluss wird die Übergabe von Werten (Resultate, Messwerte, Objekte, Dokumente etc.) von einem Schritt zum nächsten bezeichnet. Ein Datenfluss läuft über Verbindungen vom [[DiagramElements-Pin#Output_Pin|Ausgangspin]] (Pin = "Stecker/Sockel") eines Schritts zum [[DiagramElements-Pin#Input_Pin|Eingangspin]] eines anderen.
* Kontrollflüsse sind Informationen zum Endestatus eines Schrittes, die verwendet werden können, um die Aktion eines nächsten Schritts zu starten. Sie laufen über Verbindungen vom [[DiagramElements-Pin#Enable_Output_Pin|Trigger-Ausgang]] eines Schrittes zum [[DiagramElements-Pin#Enable_Input_Pin|Trigger-Eingang]] eines anderen.
Beide können die Ausführung eines Folgeschritts auslösen.

== Diagrammelemente ==
Als "''Diagrammelemente''" werden die Bestandteile eines Aktivitätsdiagramms bezeichnet. Sie definieren das Verhalten des [[Compound Block|Zusammengesetzten Aktionsblocks]] und werden im [[Compound Network Editor|Netzwerkeditor]] bearbeitet.

== Einführendes Beispiel eines Aktivitätsdiagramms ==

Das folgende Beispiel erläutert die Hauptkomponenten eines Aktivitätsdiagramms:

[[Bild:diagram-elements.jpg|760px|Ein Aktivitätsdiagramm]]

Das Diagramm beschreibt den Test einer E-Mail-Übertragung. Zuerst erzeugt der Schritt "Create Unique ID" eine sog. UUID und stellt diese an seinem Ausgangspin zur Verfügung. Diese UUID wird später gebraucht, um den korrekten Empfang der E-Mail zu verifizieren. Die UUID wird vom Schritt "Send E-Mail [SMTP]" empfangen, welcher eine E-Mail mittels dem SMTP Protokoll verschickt, und die UUID als Subject verwendet. Als nächstes sorgt der "Time [Delay]" Schritt für eine Verzögerung von 5 Sekunden (in denen die E-Mail übermittelt wird). Am Ende prüft der Schritt "Check for incoming Mail" ob eine E-Mail mit dem angegebenen Subject angekommen ist, wozu obige UUID gebraucht wird.
Der Test wird einen Fehler melden, falls eine solche E-Mail nicht gefunden wird.

Beachten Sie bitte, dass die graphische Darstellung des Diagramms im Grunde der UML-Notation entspricht. Allerdings werden um die Lesbarkeit zu erhöhen, und um wichtige Aspekte der Ausführung hervorzuheben einige Element etwas anders bzw. zusätzlich annotiert dargestellt. Insbesondere werden die Stereotypen der Pins durch unterschiedliche Pin-Darstellungen hervorgehoben, anstatt durch textuelle "<<stereotype>>"-labels, wie in UML.


=== [[DiagramElements-Step|Schritt]] (7) ===

Als "''Schritt''" wird eine Aktion (Aktionsbaustein) bezeichnet, welcher in ein Diagramm platziert wurde. Diese Aktion kann ihrerseits entweder ein sog. [[Elementary Block|Elementablock]] sein (wie z.B. "Create Unique ID"), welche ihre Aktion durch eine textuellen Programmcode definiert, oder wieder ein [[Compound Block|zusammengesetzter Block]] (wie z.B. "Check Incoming Mail"), welcher durch ein eigenes Aktivitätsdiagramm definiert wurde. Für das Diagrammnetzwerk in welches der Aktionsblock platziert wurde ist kein Unterschied im Verhalten sichtbar: ein Diagramm, welches einen Aktionsblock beinhaltet (d.h. einen Schritt enthält) sieht kein unterschiedliches Verhalten in Abhängigkeit der effektiven Realisierung seiner Schritte. Tatsächlich gibt es auch keine Unterschiede in der graphischen Darstellung, so dass es auch für den Entwickler eines zusammengesetzten Blocks keinen Unterschied macht (er muss nicht wissen, wie die Interna einer Aktion aufgebaut sind). Alle Schritte werden gleichermaßen durch die Verfügbarkeit von Eingangsdaten gestartet, führen ihre Bearbeitung durch, und liefern ihre Resultate an den Ausgangspins. Details zum Verhalten von Schritten sind in einem [[DiagramElements-Step | separaten Document]] nachzulesen.

=== Autostart (1) ===

Ein Schritt mit der Autostart Option wird automatisch gestartet, sobald das umgebende Netzwerk ausgeführt wird. Schritte ohne Autostart-Option werden lediglich ausgeführt, sobald Daten an den Eingangspins des Schrittes erscheinen. Autostart wird insbesondere für Schritte benötigt, welche keine Eingangspins haben, oder welche nicht durch einen Kontrollfluss gestartet werden. Auch Schritte, deren Eingang lediglich konstante Parameter darstellen müssen so gestartet werden. Im obigen Diagramm trifft dies für den linken "Create Unique ID" Schritt zu.

Im Diagrammeditor werden Schritte mit Autostart mit einem speziellen Icon am linken oberen Rand dargestellt; falls Sie die Standard-UML-Notation bevorzugen, können Sie auch einen START-Block aus der Bibliothek verwenden und dessen Trigger-Ausgangspin mit dem zuerst auszuführenden Schritt verbinden.

=== [[DiagramElements-Pin|Pin]] (3, 6, 9) ===

[[DiagramElements-Pin|Pins]] dienen zur Weitergabe von Daten und Triggerinformationen zwischen Schritten. Diese Pins können entweder [[DiagramElements-Pin#Output Pin|Ausgangespins]] (3) sein, um Daten zu senden, oder [[DiagramElements-Pin#Input Pin|Eingangspins]] (9), um Daten zu empfangen. Weitere Pins dienen dazu besondere Situationen wie z.B. [[DiagramElements-Pin#Exception Output Pin|Ausnahmebehandlung]] zu melden. Im obigen Diagramm, ist der Exception-Ausgang des "Check Incoming Mail" Schritts mit dem Trigger-Eingang des "FAIL" Schrittes verbunden.
Kontrollflusspins (Trigger und Status) sind vertikal angeordnet, wohingegen Datenflüsse als horizontal Pins dargestellt werden.
Eingangspins sind immer oben oder links, Ausgangspins immer unten oder rechts angeordnet.
Pins werden entsprechend ihrem Verhalten leicht unterschiedlich dargestellt; insbesondere auf das Puffer- und Triggerverhalten wird durch ausgefüllt vs. nicht gefüllt hingewiesen, da diese wichtig sind für die Ausführung. Pins werden in einem [[DiagramElements-Pin | separaten Dokument]] detailliert beschrieben.

=== [[DiagramElements-Connection|Verbindung]] (4,8) ===

Verbindungen dienen zum Weiterleiten von Daten oder Kontrollinformationen zu einem oder mehreren Eingangspins (eines oder mehrerer Folgeschritte).
Im Sinne von UML sind alle Verbindungen in expecco immer "Objektverbindungen".

==== Datenflussverbindung (4) ====

Diese befördern Daten (-Objekte) von einem Ausgangspin zu einem Eingangspins eines Folgeschritts. Im obigen Beispiel sendet der erste Schritt die erzeugte UUID an zwei weitere Schritte.
Datenflusspins sind immer links und rechts angeordnet (horizontale Pins).

==== Kontrollflussverbindung (8) ====

Diese dienen dazu, die Ausführung unabhängig von Daten (aber abhängig von der Ausführung eines Schrittes) zu kontrollieren. Im Beispiel werden die Schritte rechts im Bild sequentiell ausgeführt, wozu der Triggerausgang eines Schrittes mit dem Triggereingang eines Folgeschrittes verbunden wurde.
Kontrollflusspins sind immer oben und unten angeordnet (vertikale Pins).

=== [[DiagramElements-Freeze Value|Freeze Value (Vorbelegungswert)]] (6) ===

Eingangswerte eines Pins können mit einem statischen Wert vorbelegt werden (Konstante).
Im Beispiel sind der Text der E-Mail, die E-Mail-Adresse, die Wartezeit und auch die Fehlermeldung auf diese Weise "eingefroren".
Ein vorbelegter Pin sollte typischerweise als nicht-triggernd und nicht-konsumierend (sogenannter "''Parameterpin''") konfiguriert werden, wofür es einen besonderen Menüeintrag gibt (außerdem werden beim "''Einfrieren''" die Pins vom Editor automatisch als solche umdefiniert). Details zum Triggerverhalten und zum Konsumieren von Eingangswerten finden sie im Dokument: [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Freeze Value|Vorbelegung aus Umgebungsvariablen]] (5) ===

Eingangswerte eines Pins können ebenfalls aus einer Variable gelesen werden. Diese Variablen werden in einer sogenannten "''Variablenumgebung''" bereit gestellt, welche im umgebenden zusammengesetzten Bausteinen oder der [[TestSuite Element|Testsuite]] definiert werden. Im obigen Beispiel werden der Name des E-Mail-Kontos sowie der E-Mail-Serverhost aus solchen Variablen gelesen (und entsprechende Einträge in der Variablenumgebung der Testsuite vorausgesetzt). Wie auch reguläre Vorbelegungen sollte der Pin als nicht-triggernd und nicht-konsumierend definiert werden (i.e. "''Parameterpin''"). Lesen Sie dazu ebenfalls das Kapitel [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Annotation|Annotation]] (2) ===

Annotationen dienen dazu, Kommentare oder Zusatzinformationen für Entwickler oder Tester im Diagramm mit abzulegen. Möglich sind sowohl textuelle Annotation, als auch importierte Grafiken (Bilder im GIF-, JPEG- oder PNG-Format). Sie können auch dazu genutzt werden, um wichtige Teile des Diagramms farblich hervorzuheben, indem Sie eine leere Textannotation mit einer Hintergrundfarbe unter Teile ihres Diagramms legen.

=== [[DiagramElements-Probe|Messfühler]] ===

Messfühler (im obigen Diagramm nicht gezeigt) dienen dazu Pin-Werte aufzuzeichnen und/oder zu validieren. Messfühler bieten einen komfortablen und lesbaren Mechanismus um Werte auf ihre Gültigkeit zu prüfen.

== Semantik ==
=== Relation zu IEC1131 ===
Expeccos Aktivitätsdiagramme ähneln stark den Funktionblöcken der IEC1131-3 FBD Sprache (siehe ua. [https://en.wikipedia.org/wiki/Function_block_diagram Wikipedia]).
Sowohl die grafische Darstellung als auch das Ausführungsverhalten sind vergleichbar. Ingenieure mit einem SPS Hintergrund werden keine Probleme haben, Expeccos Aktionsdefinitionen und zusammengesetzte Aktionen zu verstehen.

=== Relation zu Petrinetzen ===
Ein Petri-Netz [https://de.wikipedia.org/wiki/Petri-Netz (siehe Wikipedia)] ist ein Netzwerk, das aus Knoten (''Stellen'' oder auch ''Plätze'' genannt, mit möglicher Aktionsbehandlung) und Übergängen besteht. In klassischen Petri-Netzen bewegen sich anonyme Tokens entlang von Verbindungen. Übergänge kontrollieren das Auslösen (Triggern) der folgenden Aktionsschritte abhängig von der Ankunft von Tokens auf der Eingangsseite, und geben Tokens an die Ausgangsseite weiter.

Expecco kombiniert die Übergangs- und Stellenfunktionalität in einem einzelnen Schrittelement um die grafische Representation dichter zu machen (und auch um eine Ähnlichkeit mit UML-2-Aktivitätsdiagrammen und anderen flussbasierten Diagrammen zu bekommen). Semantisch verhalten sie sich jedoch gleich und jedes Diagramm könnte mit separaten Elementen umgeschrieben werden (durch sammeln der Eingaben und Weitergabe eines Tupels mit Tokens an die Stelle).

[[Datei:Beispiel.png]]

Ein expecco-Schritt mit mehreren Eingabepins entspricht einem Petri-Netz-Übergang mit mehreren Eingaben gefolgt von einer Petri-Netz-Aktion. Wie bei einem Übergang in einem Petri-Netz kann die Eingangsseite eines Schrittes so konfiguriert werden, dass entweder irgendein Eingabewert oder alle Eingabewerte vorliegen müssen. In expecco wird das als "''Aktivierungsbedingung''" des Schritts bezeichnet und ist genauer in der [[DiagramElements-Step|Dokumentation zum Schritt]] beschrieben.

"''Höhere Petri-Netze''" sind Petri-Netze, die andere Petri-Netze als Stellen enthalten, was in expecco genau den zusammengesetzten Aktionen entspricht. 
"''Farbige Petri-Netze''" sind Petri-Netze, bei denen keine einfachen anonymen Tokens weitergereicht werden, sondern Datenobjekte (oder Referenzen darauf, wie in expecco).

Deshalb sind expecco-Diagramme in Standard-Petri-Netz-Notation "''Höhere farbige Petri-Netze''".

=== Relation zu UML Aktivitätsdiagrammen ===

Zusammengesetzte Aktionen in expecco sind isomorph zu UML-Aktivitätsdiagrammen mit einer bestimmten vordefinierten Sammlung an Stereotypen für Verbindungen, Pins und Aktionsschritte. Diese Stereotypen sind in expecco fest einprogrammiert und definieren die Semantik des Auslösens von Aktionen, der Ausführungsreihenfolge von Datenverbindungen und der optionalen parallelen Ausführung von Schritten. Die grafische Representation ist leicht anders; die leicht umständlichen <<Stereotyp>>-Vermerke werden durch verschiedene Pin-Darstellungen (gefüllt/leer usw.) ersetzt. Außerdem sind alle Verbindungen in expecco Objekt-Verbindungen und alle Pins erhalten und erzeugen Objekte als Werte.

=== Relation zu Flussdiagrammen ===
Aktivitätsdiagramme können als Obermenge von Flussdiagrammen betrachtet werden. Dazu werden die Aktionen lediglich über Kontrollflussverbindungen (Trigger-in/Trigger-out) verbunden (Daten werden hierbei über Variablen ausgetauscht).

Die Wenn-Dann bedingte Verzeigung eines Flussdiagramms entspricht einem 2-Wege-If Aktionsblock (aus der Standardbibliothek). Schleifen werden durch Verbindungen der Trigger-out mit einem Trigger-in eines vorhergehenden Schrittes definiert.

== Editoren ==
Das Aktivitätsdiagramm, das das Verhalten eines zusammengesetzten Bausteins definiert, kann im [[CompoundBlock Editor-CompoundWorksheet Editor|''Netzwerkeditor'']] – auch "''Diagrammeditor''" oder "''Netzwerkdiagrammeditor''" genannt – bearbeitet werden. Dieser Editor zeigt die "Innenansicht" des Bausteins. Die Schnittstelle eines zusammengesetzten Bausteins (d.h. Anzahl und Art der Pins) kann hingegen als "Außenansicht" angesehen werden und wird im [[Scheme Editor|''Schema Editor'']] gezeigt und definiert.

== Siehe auch ==
[[Tree Elements | Tree Elements]]

[[Block Element]], [[DiagramElements-Step/en|Schritt]], [[DiagramElements-Connection|Verbindung]],
[[ElementaryBlock_Element|Elementaraktion]],

Zurück zur [[Online Documentation#Tree Elements|Online Documentation]].

[[Category: Tree Elements]]
[[Category: Incomplete]]

CompoundBlock Element

2024-07-17T12:19:57Z

Matilk: /* Relation zu UML Aktivitätsdiagrammen */

== Einführung ==
Ein zusammengesetzter Aktionsblock (englisch "''Compound Action''") beschreibt das Verhalten einer [[Block_Element|Aktion]] graphisch als Aktivitätsdiagramm. Diese Diagramme sind vergleichbar mit den [[#Relation_zu_UML_Aktivit.C3.A4tsdiagrammen|Datenflussdiagrammen]] wie in UML2.0 definiert. Sie haben außerdem viele Eigenschaften gemein mit [[#Relation_zu_Petrinetzen|Petrinetzen]]. Das Diagramm besteht aus Unteraktionen, welche als [[DiagramElements-Step|''Schritte'']] bezeichnet werden.

Die Ausführung wird durch eine Kombination von Daten- und Kontrollflüssen gesteuert, die durch Verbindungen zwischen den Schritten übertragen werden:
* Als Datenfluss wird die Übergabe von Werten (Resultate, Messwerte, Objekte, Dokumente etc.) von einem Schritt zum nächsten bezeichnet. Ein Datenfluss läuft über Verbindungen vom [[DiagramElements-Pin#Output_Pin|Ausgangspin]] (Pin = "Stecker/Sockel") eines Schritts zum [[DiagramElements-Pin#Input_Pin|Eingangspin]] eines anderen.
* Kontrollflüsse sind Informationen zum Endestatus eines Schrittes, die verwendet werden können, um die Aktion eines nächsten Schritts zu starten. Sie laufen über Verbindungen vom [[DiagramElements-Pin#Enable_Output_Pin|Trigger-Ausgang]] eines Schrittes zum [[DiagramElements-Pin#Enable_Input_Pin|Trigger-Eingang]] eines anderen.
Beide können die Ausführung eines Folgeschritts auslösen.

== Diagrammelemente ==
Als "''Diagrammelemente''" werden die Bestandteile eines Aktivitätsdiagramms bezeichnet. Sie definieren das Verhalten des [[Compound Block|Zusammengesetzten Aktionsblocks]] und werden im [[Compound Network Editor|Netzwerkeditor]] bearbeitet.

== Einführendes Beispiel eines Aktivitätsdiagramms ==

Das folgende Beispiel erläutert die Hauptkomponenten eines Aktivitätsdiagramms:

[[Bild:diagram-elements.jpg|760px|Ein Aktivitätsdiagramm]]

Das Diagramm beschreibt den Test einer E-Mail-Übertragung. Zuerst erzeugt der Schritt "Create Unique ID" eine sog. UUID und stellt diese an seinem Ausgangspin zur Verfügung. Diese UUID wird später gebraucht, um den korrekten Empfang der E-Mail zu verifizieren. Die UUID wird vom Schritt "Send E-Mail [SMTP]" empfangen, welcher eine E-Mail mittels dem SMTP Protokoll verschickt, und die UUID als Subject verwendet. Als nächstes sorgt der "Time [Delay]" Schritt für eine Verzögerung von 5 Sekunden (in denen die E-Mail übermittelt wird). Am Ende prüft der Schritt "Check for incoming Mail" ob eine E-Mail mit dem angegebenen Subject angekommen ist, wozu obige UUID gebraucht wird.
Der Test wird einen Fehler melden, falls eine solche E-Mail nicht gefunden wird.

Beachten Sie bitte, dass die graphische Darstellung des Diagramms im Grunde der UML-Notation entspricht. Allerdings werden um die Lesbarkeit zu erhöhen, und um wichtige Aspekte der Ausführung hervorzuheben einige Element etwas anders bzw. zusätzlich annotiert dargestellt. Insbesondere werden die Stereotypen der Pins durch unterschiedliche Pin-Darstellungen hervorgehoben, anstatt durch textuelle "<<stereotype>>"-labels, wie in UML.


=== [[DiagramElements-Step|Schritt]] (7) ===

Als "''Schritt''" wird eine Aktion (Aktionsbaustein) bezeichnet, welcher in ein Diagramm platziert wurde. Diese Aktion kann ihrerseits entweder ein sog. [[Elementary Block|Elementablock]] sein (wie z.B. "Create Unique ID"), welche ihre Aktion durch eine textuellen Programmcode definiert, oder wieder ein [[Compound Block|zusammengesetzter Block]] (wie z.B. "Check Incoming Mail"), welcher durch ein eigenes Aktivitätsdiagramm definiert wurde. Für das Diagrammnetzwerk in welches der Aktionsblock platziert wurde ist kein Unterschied im Verhalten sichtbar: ein Diagramm, welches einen Aktionsblock beinhaltet (d.h. einen Schritt enthält) sieht kein unterschiedliches Verhalten in Abhängigkeit der effektiven Realisierung seiner Schritte. Tatsächlich gibt es auch keine Unterschiede in der graphischen Darstellung, so dass es auch für den Entwickler eines zusammengesetzten Blocks keinen Unterschied macht (er muss nicht wissen, wie die Interna einer Aktion aufgebaut sind). Alle Schritte werden gleichermaßen durch die Verfügbarkeit von Eingangsdaten gestartet, führen ihre Bearbeitung durch, und liefern ihre Resultate an den Ausgangspins. Details zum Verhalten von Schritten sind in einem [[DiagramElements-Step | separaten Document]] nachzulesen.

=== Autostart (1) ===

Ein Schritt mit der Autostart Option wird automatisch gestartet, sobald das umgebende Netzwerk ausgeführt wird. Schritte ohne Autostart-Option werden lediglich ausgeführt, sobald Daten an den Eingangspins des Schrittes erscheinen. Autostart wird insbesondere für Schritte benötigt, welche keine Eingangspins haben, oder welche nicht durch einen Kontrollfluss gestartet werden. Auch Schritte, deren Eingang lediglich konstante Parameter darstellen müssen so gestartet werden. Im obigen Diagramm trifft dies für den linken "Create Unique ID" Schritt zu.

Im Diagrammeditor werden Schritte mit Autostart mit einem speziellen Icon am linken oberen Rand dargestellt; falls Sie die Standard-UML-Notation bevorzugen, können Sie auch einen START-Block aus der Bibliothek verwenden und dessen Trigger-Ausgangspin mit dem zuerst auszuführenden Schritt verbinden.

=== [[DiagramElements-Pin|Pin]] (3, 6, 9) ===

[[DiagramElements-Pin|Pins]] dienen zur Weitergabe von Daten und Triggerinformationen zwischen Schritten. Diese Pins können entweder [[DiagramElements-Pin#Output Pin|Ausgangespins]] (3) sein, um Daten zu senden, oder [[DiagramElements-Pin#Input Pin|Eingangspins]] (9), um Daten zu empfangen. Weitere Pins dienen dazu besondere Situationen wie z.B. [[DiagramElements-Pin#Exception Output Pin|Ausnahmebehandlung]] zu melden. Im obigen Diagramm, ist der Exception-Ausgang des "Check Incoming Mail" Schritts mit dem Trigger-Eingang des "FAIL" Schrittes verbunden.
Kontrollflusspins (Trigger und Status) sind vertikal angeordnet, wohingegen Datenflüsse als horizontal Pins dargestellt werden.
Eingangspins sind immer oben oder links, Ausgangspins immer unten oder rechts angeordnet.
Pins werden entsprechend ihrem Verhalten leicht unterschiedlich dargestellt; insbesondere auf das Puffer- und Triggerverhalten wird durch ausgefüllt vs. nicht gefüllt hingewiesen, da diese wichtig sind für die Ausführung. Pins werden in einem [[DiagramElements-Pin | separaten Dokument]] detailliert beschrieben.

=== [[DiagramElements-Connection|Verbindung]] (4,8) ===

Verbindungen dienen zum Weiterleiten von Daten oder Kontrollinformationen zu einem oder mehreren Eingangspins (eines oder mehrerer Folgeschritte).
Im Sinne von UML sind alle Verbindungen in expecco immer "Objektverbindungen".

==== Datenflussverbindung (4) ====

Diese befördern Daten (-Objekte) von einem Ausgangspin zu einem Eingangspins eines Folgeschritts. Im obigen Beispiel sendet der erste Schritt die erzeugte UUID an zwei weitere Schritte.
Datenflusspins sind immer links und rechts angeordnet (horizontale Pins).

==== Kontrollflussverbindung (8) ====

Diese dienen dazu, die Ausführung unabhängig von Daten (aber abhängig von der Ausführung eines Schrittes) zu kontrollieren. Im Beispiel werden die Schritte rechts im Bild sequentiell ausgeführt, wozu der Triggerausgang eines Schrittes mit dem Triggereingang eines Folgeschrittes verbunden wurde.
Kontrollflusspins sind immer oben und unten angeordnet (vertikale Pins).

=== [[DiagramElements-Freeze Value|Freeze Value (Vorbelegungswert)]] (6) ===

Eingangswerte eines Pins können mit einem statischen Wert vorbelegt werden (Konstante).
Im Beispiel sind der Text der E-Mail, die E-Mail-Adresse, die Wartezeit und auch die Fehlermeldung auf diese Weise "eingefroren".
Ein vorbelegter Pin sollte typischerweise als nicht-triggernd und nicht-konsumierend (sogenannter "''Parameterpin''") konfiguriert werden, wofür es einen besonderen Menüeintrag gibt (außerdem werden beim "''Einfrieren''" die Pins vom Editor automatisch als solche umdefiniert). Details zum Triggerverhalten und zum Konsumieren von Eingangswerten finden sie im Dokument: [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Freeze Value|Vorbelegung aus Umgebungsvariablen]] (5) ===

Eingangswerte eines Pins können ebenfalls aus einer Variable gelesen werden. Diese Variablen werden in einer sogenannten "''Variablenumgebung''" bereit gestellt, welche im umgebenden zusammengesetzten Bausteinen oder der [[TestSuite Element|Testsuite]] definiert werden. Im obigen Beispiel werden der Name des E-Mail-Kontos sowie der E-Mail-Serverhost aus solchen Variablen gelesen (und entsprechende Einträge in der Variablenumgebung der Testsuite vorausgesetzt). Wie auch reguläre Vorbelegungen sollte der Pin als nicht-triggernd und nicht-konsumierend definiert werden (i.e. "''Parameterpin''"). Lesen Sie dazu ebenfalls das Kapitel [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Annotation|Annotation]] (2) ===

Annotationen dienen dazu, Kommentare oder Zusatzinformationen für Entwickler oder Tester im Diagramm mit abzulegen. Möglich sind sowohl textuelle Annotation, als auch importierte Grafiken (Bilder im GIF-, JPEG- oder PNG-Format). Sie können auch dazu genutzt werden, um wichtige Teile des Diagramms farblich hervorzuheben, indem Sie eine leere Textannotation mit einer Hintergrundfarbe unter Teile ihres Diagramms legen.

=== [[DiagramElements-Probe|Messfühler]] ===

Messfühler (im obigen Diagramm nicht gezeigt) dienen dazu Pin-Werte aufzuzeichnen und/oder zu validieren. Messfühler bieten einen komfortablen und lesbaren Mechanismus um Werte auf ihre Gültigkeit zu prüfen.

== Semantik ==
=== Relation zu IEC1131 ===
Expeccos Aktivitätsdiagramme ähneln stark den Funktionblöcken der IEC1131-3 FBD Sprache (siehe ua. [https://en.wikipedia.org/wiki/Function_block_diagram Wikipedia]).
Sowohl die grafische Darstellung als auch das Ausführungsverhalten sind vergleichbar. Ingenieure mit einem SPS Hintergrund werden keine Probleme haben, Expeccos Aktionsdefinitionen und zusammengesetzte Aktionen zu verstehen.

=== Relation zu Petrinetzen ===
Ein Petri-Netz [https://de.wikipedia.org/wiki/Petri-Netz (siehe Wikipedia)] ist ein Netzwerk, das aus Knoten (''Stellen'' oder auch ''Plätze'' genannt, mit möglicher Aktionsbehandlung) und Übergängen besteht. In klassischen Petri-Netzen bewegen sich anonyme Tokens entlang von Verbindungen. Übergänge kontrollieren das Auslösen (Triggern) der folgenden Aktionsschritte abhängig von der Ankunft von Tokens auf der Eingangsseite, und geben Tokens an die Ausgangsseite weiter.

Expecco kombiniert die Übergangs- und Stellenfunktionalität in einem einzelnen Schrittelement um die grafische Representation dichter zu machen (und auch um eine Ähnlichkeit mit UML-2-Aktivitätsdiagrammen und anderen flussbasierten Diagrammen zu bekommen). Semantisch verhalten sie sich jedoch gleich und jedes Diagramm könnte mit separaten Elementen umgeschrieben werden (durch sammeln der Eingaben und Weitergabe eines Tupels mit Tokens an die Stelle).

[[Datei:Beispiel.png]]

Ein expecco-Schritt mit mehreren Eingabepins entspricht einem Petri-Netz-Übergang mit mehreren Eingaben gefolgt von einer Petri-Netz-Aktion. Wie bei einem Übergang in einem Petri-Netz kann die Eingangsseite eines Schrittes so konfiguriert werden, dass entweder irgendein Eingabewert oder alle Eingabewerte vorliegen müssen. In expecco wird das als "''Aktivierungsbedingung''" des Schritts bezeichnet und ist genauer in der [[DiagramElements-Step|Dokumentation zum Schritt]] beschrieben.

"''Höhere Petri-Netze''" sind Petri-Netze, die andere Petri-Netze als Stellen enthalten, was in expecco genau den zusammengesetzten Aktionen entspricht. 
"''Farbige Petri-Netze''" sind Petri-Netze, bei denen keine einfachen anonymen Tokens weitergereicht werden, sondern Datenobjekte (oder Referenzen darauf, wie in expecco).

Deshalb sind expecco-Diagramme in Standard-Petri-Netz-Notation "''Höhere farbige Petri-Netze''".

=== Relation zu UML Aktivitätsdiagrammen ===

Zusammengesetzte Aktionen in expecco sind isomorph zu UML-Aktivitätsdiagrammen mit einer bestimmten vordefinierten Sammlung an Stereotypen für Verbindungen, Pins und Aktionsschritte. Diese Stereotypen sind in expecco fest einprogrammiert und definieren die Semantik des Auslösens von Aktionen, der Ausführungsreihenfolge von Datenverbindungen und der optionalen parallelen Ausführung von Schritten. Die grafische Representation ist leicht anders; die leicht umständlichen <<Stereotyp>>-Vermerke werden durch verschiedene Pin-Darstellungen (gefüllt/leer usw.) ersetzt. Außerdem sind alle Verbindungen in expecco Objekt-Verbindungen und alle Pins erhalten und erzeugen Objekte als Werte.

=== Relation zu Flussdiagrammen ===
Aktivitätsdiagramme können als Obermenge von Flussdiagrammen betrachtet werden. Dazu werden die Aktionen lediglich über Kontrollflussverbindungen (Trigger-in/Trigger-out) verbunden (Daten werden hierbei über Variablen ausgetauscht).

Die Wenn-Dann bedingte Verzeigung eines Flussdiagramms entspricht einem 2-Wege-If Aktionsblock (aus der Standardbibliothek). Schleifen werden durch Verbindungen der Trigger-out mit einem Trigger-in eines vorhergehenden Schrittes definiert.

== Editoren ==
The activity diagram which defines the behavior of a compound block
is edited in the [[CompoundBlock Editor-CompoundWorksheet Editor/en|''network editor'']], also called "''diagram editor''" or "''network diagram editor''".
This editor presents the "internal view" of the block.
In contrast, the interface of an compound block (e.g. number and type of pins) can be regarded as its "external view" and is presented and defined in the [[Scheme Editor/en|''schema editor'']].

== Siehe auch ==
[[Tree Elements | Tree Elements]]

[[Block Element]], [[DiagramElements-Step/en|Schritt]], [[DiagramElements-Connection|Verbindung]],
[[ElementaryBlock_Element|Elementaraktion]],

Zurück zur [[Online Documentation#Tree Elements|Online Documentation]].

[[Category: Tree Elements]]
[[Category: Incomplete]]

CompoundBlock Element

2024-07-17T12:01:05Z

Matilk: /* Relation zu Petrinetzen */ translated

== Einführung ==
Ein zusammengesetzter Aktionsblock (englisch "''Compound Action''") beschreibt das Verhalten einer [[Block_Element|Aktion]] graphisch als Aktivitätsdiagramm. Diese Diagramme sind vergleichbar mit den [[#Relation_zu_UML_Aktivit.C3.A4tsdiagrammen|Datenflussdiagrammen]] wie in UML2.0 definiert. Sie haben außerdem viele Eigenschaften gemein mit [[#Relation_zu_Petrinetzen|Petrinetzen]]. Das Diagramm besteht aus Unteraktionen, welche als [[DiagramElements-Step|''Schritte'']] bezeichnet werden.

Die Ausführung wird durch eine Kombination von Daten- und Kontrollflüssen gesteuert, die durch Verbindungen zwischen den Schritten übertragen werden:
* Als Datenfluss wird die Übergabe von Werten (Resultate, Messwerte, Objekte, Dokumente etc.) von einem Schritt zum nächsten bezeichnet. Ein Datenfluss läuft über Verbindungen vom [[DiagramElements-Pin#Output_Pin|Ausgangspin]] (Pin = "Stecker/Sockel") eines Schritts zum [[DiagramElements-Pin#Input_Pin|Eingangspin]] eines anderen.
* Kontrollflüsse sind Informationen zum Endestatus eines Schrittes, die verwendet werden können, um die Aktion eines nächsten Schritts zu starten. Sie laufen über Verbindungen vom [[DiagramElements-Pin#Enable_Output_Pin|Trigger-Ausgang]] eines Schrittes zum [[DiagramElements-Pin#Enable_Input_Pin|Trigger-Eingang]] eines anderen.
Beide können die Ausführung eines Folgeschritts auslösen.

== Diagrammelemente ==
Als "''Diagrammelemente''" werden die Bestandteile eines Aktivitätsdiagramms bezeichnet. Sie definieren das Verhalten des [[Compound Block|Zusammengesetzten Aktionsblocks]] und werden im [[Compound Network Editor|Netzwerkeditor]] bearbeitet.

== Einführendes Beispiel eines Aktivitätsdiagramms ==

Das folgende Beispiel erläutert die Hauptkomponenten eines Aktivitätsdiagramms:

[[Bild:diagram-elements.jpg|760px|Ein Aktivitätsdiagramm]]

Das Diagramm beschreibt den Test einer E-Mail-Übertragung. Zuerst erzeugt der Schritt "Create Unique ID" eine sog. UUID und stellt diese an seinem Ausgangspin zur Verfügung. Diese UUID wird später gebraucht, um den korrekten Empfang der E-Mail zu verifizieren. Die UUID wird vom Schritt "Send E-Mail [SMTP]" empfangen, welcher eine E-Mail mittels dem SMTP Protokoll verschickt, und die UUID als Subject verwendet. Als nächstes sorgt der "Time [Delay]" Schritt für eine Verzögerung von 5 Sekunden (in denen die E-Mail übermittelt wird). Am Ende prüft der Schritt "Check for incoming Mail" ob eine E-Mail mit dem angegebenen Subject angekommen ist, wozu obige UUID gebraucht wird.
Der Test wird einen Fehler melden, falls eine solche E-Mail nicht gefunden wird.

Beachten Sie bitte, dass die graphische Darstellung des Diagramms im Grunde der UML-Notation entspricht. Allerdings werden um die Lesbarkeit zu erhöhen, und um wichtige Aspekte der Ausführung hervorzuheben einige Element etwas anders bzw. zusätzlich annotiert dargestellt. Insbesondere werden die Stereotypen der Pins durch unterschiedliche Pin-Darstellungen hervorgehoben, anstatt durch textuelle "<<stereotype>>"-labels, wie in UML.


=== [[DiagramElements-Step|Schritt]] (7) ===

Als "''Schritt''" wird eine Aktion (Aktionsbaustein) bezeichnet, welcher in ein Diagramm platziert wurde. Diese Aktion kann ihrerseits entweder ein sog. [[Elementary Block|Elementablock]] sein (wie z.B. "Create Unique ID"), welche ihre Aktion durch eine textuellen Programmcode definiert, oder wieder ein [[Compound Block|zusammengesetzter Block]] (wie z.B. "Check Incoming Mail"), welcher durch ein eigenes Aktivitätsdiagramm definiert wurde. Für das Diagrammnetzwerk in welches der Aktionsblock platziert wurde ist kein Unterschied im Verhalten sichtbar: ein Diagramm, welches einen Aktionsblock beinhaltet (d.h. einen Schritt enthält) sieht kein unterschiedliches Verhalten in Abhängigkeit der effektiven Realisierung seiner Schritte. Tatsächlich gibt es auch keine Unterschiede in der graphischen Darstellung, so dass es auch für den Entwickler eines zusammengesetzten Blocks keinen Unterschied macht (er muss nicht wissen, wie die Interna einer Aktion aufgebaut sind). Alle Schritte werden gleichermaßen durch die Verfügbarkeit von Eingangsdaten gestartet, führen ihre Bearbeitung durch, und liefern ihre Resultate an den Ausgangspins. Details zum Verhalten von Schritten sind in einem [[DiagramElements-Step | separaten Document]] nachzulesen.

=== Autostart (1) ===

Ein Schritt mit der Autostart Option wird automatisch gestartet, sobald das umgebende Netzwerk ausgeführt wird. Schritte ohne Autostart-Option werden lediglich ausgeführt, sobald Daten an den Eingangspins des Schrittes erscheinen. Autostart wird insbesondere für Schritte benötigt, welche keine Eingangspins haben, oder welche nicht durch einen Kontrollfluss gestartet werden. Auch Schritte, deren Eingang lediglich konstante Parameter darstellen müssen so gestartet werden. Im obigen Diagramm trifft dies für den linken "Create Unique ID" Schritt zu.

Im Diagrammeditor werden Schritte mit Autostart mit einem speziellen Icon am linken oberen Rand dargestellt; falls Sie die Standard-UML-Notation bevorzugen, können Sie auch einen START-Block aus der Bibliothek verwenden und dessen Trigger-Ausgangspin mit dem zuerst auszuführenden Schritt verbinden.

=== [[DiagramElements-Pin|Pin]] (3, 6, 9) ===

[[DiagramElements-Pin|Pins]] dienen zur Weitergabe von Daten und Triggerinformationen zwischen Schritten. Diese Pins können entweder [[DiagramElements-Pin#Output Pin|Ausgangespins]] (3) sein, um Daten zu senden, oder [[DiagramElements-Pin#Input Pin|Eingangspins]] (9), um Daten zu empfangen. Weitere Pins dienen dazu besondere Situationen wie z.B. [[DiagramElements-Pin#Exception Output Pin|Ausnahmebehandlung]] zu melden. Im obigen Diagramm, ist der Exception-Ausgang des "Check Incoming Mail" Schritts mit dem Trigger-Eingang des "FAIL" Schrittes verbunden.
Kontrollflusspins (Trigger und Status) sind vertikal angeordnet, wohingegen Datenflüsse als horizontal Pins dargestellt werden.
Eingangspins sind immer oben oder links, Ausgangspins immer unten oder rechts angeordnet.
Pins werden entsprechend ihrem Verhalten leicht unterschiedlich dargestellt; insbesondere auf das Puffer- und Triggerverhalten wird durch ausgefüllt vs. nicht gefüllt hingewiesen, da diese wichtig sind für die Ausführung. Pins werden in einem [[DiagramElements-Pin | separaten Dokument]] detailliert beschrieben.

=== [[DiagramElements-Connection|Verbindung]] (4,8) ===

Verbindungen dienen zum Weiterleiten von Daten oder Kontrollinformationen zu einem oder mehreren Eingangspins (eines oder mehrerer Folgeschritte).
Im Sinne von UML sind alle Verbindungen in expecco immer "Objektverbindungen".

==== Datenflussverbindung (4) ====

Diese befördern Daten (-Objekte) von einem Ausgangspin zu einem Eingangspins eines Folgeschritts. Im obigen Beispiel sendet der erste Schritt die erzeugte UUID an zwei weitere Schritte.
Datenflusspins sind immer links und rechts angeordnet (horizontale Pins).

==== Kontrollflussverbindung (8) ====

Diese dienen dazu, die Ausführung unabhängig von Daten (aber abhängig von der Ausführung eines Schrittes) zu kontrollieren. Im Beispiel werden die Schritte rechts im Bild sequentiell ausgeführt, wozu der Triggerausgang eines Schrittes mit dem Triggereingang eines Folgeschrittes verbunden wurde.
Kontrollflusspins sind immer oben und unten angeordnet (vertikale Pins).

=== [[DiagramElements-Freeze Value|Freeze Value (Vorbelegungswert)]] (6) ===

Eingangswerte eines Pins können mit einem statischen Wert vorbelegt werden (Konstante).
Im Beispiel sind der Text der E-Mail, die E-Mail-Adresse, die Wartezeit und auch die Fehlermeldung auf diese Weise "eingefroren".
Ein vorbelegter Pin sollte typischerweise als nicht-triggernd und nicht-konsumierend (sogenannter "''Parameterpin''") konfiguriert werden, wofür es einen besonderen Menüeintrag gibt (außerdem werden beim "''Einfrieren''" die Pins vom Editor automatisch als solche umdefiniert). Details zum Triggerverhalten und zum Konsumieren von Eingangswerten finden sie im Dokument: [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Freeze Value|Vorbelegung aus Umgebungsvariablen]] (5) ===

Eingangswerte eines Pins können ebenfalls aus einer Variable gelesen werden. Diese Variablen werden in einer sogenannten "''Variablenumgebung''" bereit gestellt, welche im umgebenden zusammengesetzten Bausteinen oder der [[TestSuite Element|Testsuite]] definiert werden. Im obigen Beispiel werden der Name des E-Mail-Kontos sowie der E-Mail-Serverhost aus solchen Variablen gelesen (und entsprechende Einträge in der Variablenumgebung der Testsuite vorausgesetzt). Wie auch reguläre Vorbelegungen sollte der Pin als nicht-triggernd und nicht-konsumierend definiert werden (i.e. "''Parameterpin''"). Lesen Sie dazu ebenfalls das Kapitel [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Annotation|Annotation]] (2) ===

Annotationen dienen dazu, Kommentare oder Zusatzinformationen für Entwickler oder Tester im Diagramm mit abzulegen. Möglich sind sowohl textuelle Annotation, als auch importierte Grafiken (Bilder im GIF-, JPEG- oder PNG-Format). Sie können auch dazu genutzt werden, um wichtige Teile des Diagramms farblich hervorzuheben, indem Sie eine leere Textannotation mit einer Hintergrundfarbe unter Teile ihres Diagramms legen.

=== [[DiagramElements-Probe|Messfühler]] ===

Messfühler (im obigen Diagramm nicht gezeigt) dienen dazu Pin-Werte aufzuzeichnen und/oder zu validieren. Messfühler bieten einen komfortablen und lesbaren Mechanismus um Werte auf ihre Gültigkeit zu prüfen.

== Semantik ==
=== Relation zu IEC1131 ===
Expeccos Aktivitätsdiagramme ähneln stark den Funktionblöcken der IEC1131-3 FBD Sprache (siehe ua. [https://en.wikipedia.org/wiki/Function_block_diagram Wikipedia]).
Sowohl die grafische Darstellung als auch das Ausführungsverhalten sind vergleichbar. Ingenieure mit einem SPS Hintergrund werden keine Probleme haben, Expeccos Aktionsdefinitionen und zusammengesetzte Aktionen zu verstehen.

=== Relation zu Petrinetzen ===
Ein Petri-Netz [https://de.wikipedia.org/wiki/Petri-Netz (siehe Wikipedia)] ist ein Netzwerk, das aus Knoten (''Stellen'' oder auch ''Plätze'' genannt, mit möglicher Aktionsbehandlung) und Übergängen besteht. In klassischen Petri-Netzen bewegen sich anonyme Tokens entlang von Verbindungen. Übergänge kontrollieren das Auslösen (Triggern) der folgenden Aktionsschritte abhängig von der Ankunft von Tokens auf der Eingangsseite, und geben Tokens an die Ausgangsseite weiter.

Expecco kombiniert die Übergangs- und Stellenfunktionalität in einem einzelnen Schrittelement um die grafische Representation dichter zu machen (und auch um eine Ähnlichkeit mit UML-2-Aktivitätsdiagrammen und anderen flussbasierten Diagrammen zu bekommen). Semantisch verhalten sie sich jedoch gleich und jedes Diagramm könnte mit separaten Elementen umgeschrieben werden (durch sammeln der Eingaben und Weitergabe eines Tupels mit Tokens an die Stelle).

[[Datei:Beispiel.png]]

Ein expecco-Schritt mit mehreren Eingabepins entspricht einem Petri-Netz-Übergang mit mehreren Eingaben gefolgt von einer Petri-Netz-Aktion. Wie bei einem Übergang in einem Petri-Netz kann die Eingangsseite eines Schrittes so konfiguriert werden, dass entweder irgendein Eingabewert oder alle Eingabewerte vorliegen müssen. In expecco wird das als "''Aktivierungsbedingung''" des Schritts bezeichnet und ist genauer in der [[DiagramElements-Step|Dokumentation zum Schritt]] beschrieben.

"''Höhere Petri-Netze''" sind Petri-Netze, die andere Petri-Netze als Stellen enthalten, was in expecco genau den zusammengesetzten Aktionen entspricht. 
"''Farbige Petri-Netze''" sind Petri-Netze, bei denen keine einfachen anonymen Tokens weitergereicht werden, sondern Datenobjekte (oder Referenzen darauf, wie in expecco).

Deshalb sind expecco-Diagramme in Standard-Petri-Netz-Notation "''Höhere farbige Petri-Netze''".

=== Relation zu UML Aktivitätsdiagrammen ===
--- to be written

=== Relation zu Flussdiagrammen ===
Aktivitätsdiagramme können als Obermenge von Flussdiagrammen betrachtet werden. Dazu werden die Aktionen lediglich über Kontrollflussverbindungen (Trigger-in/Trigger-out) verbunden (Daten werden hierbei über Variablen ausgetauscht).

Die Wenn-Dann bedingte Verzeigung eines Flussdiagramms entspricht einem 2-Wege-If Aktionsblock (aus der Standardbibliothek). Schleifen werden durch Verbindungen der Trigger-out mit einem Trigger-in eines vorhergehenden Schrittes definiert.

== Editoren ==
The activity diagram which defines the behavior of a compound block
is edited in the [[CompoundBlock Editor-CompoundWorksheet Editor/en|''network editor'']], also called "''diagram editor''" or "''network diagram editor''".
This editor presents the "internal view" of the block.
In contrast, the interface of an compound block (e.g. number and type of pins) can be regarded as its "external view" and is presented and defined in the [[Scheme Editor/en|''schema editor'']].

== Siehe auch ==
[[Tree Elements | Tree Elements]]

[[Block Element]], [[DiagramElements-Step/en|Schritt]], [[DiagramElements-Connection|Verbindung]],
[[ElementaryBlock_Element|Elementaraktion]],

Zurück zur [[Online Documentation#Tree Elements|Online Documentation]].

[[Category: Tree Elements]]
[[Category: Incomplete]]

CompoundBlock Element

2024-07-17T10:28:20Z

Matilk: restructuring

== Einführung ==
Ein zusammengesetzter Aktionsblock (englisch "''Compound Action''") beschreibt das Verhalten einer [[Block_Element|Aktion]] graphisch als Aktivitätsdiagramm. Diese Diagramme sind vergleichbar mit den [[#Relation_zu_UML_Aktivit.C3.A4tsdiagrammen|Datenflussdiagrammen]] wie in UML2.0 definiert. Sie haben außerdem viele Eigenschaften gemein mit [[#Relation_zu_Petrinetzen|Petrinetzen]]. Das Diagramm besteht aus Unteraktionen, welche als [[DiagramElements-Step|''Schritte'']] bezeichnet werden.

Die Ausführung wird durch eine Kombination von Daten- und Kontrollflüssen gesteuert, die durch Verbindungen zwischen den Schritten übertragen werden:
* Als Datenfluss wird die Übergabe von Werten (Resultate, Messwerte, Objekte, Dokumente etc.) von einem Schritt zum nächsten bezeichnet. Ein Datenfluss läuft über Verbindungen vom [[DiagramElements-Pin#Output_Pin|Ausgangspin]] (Pin = "Stecker/Sockel") eines Schritts zum [[DiagramElements-Pin#Input_Pin|Eingangspin]] eines anderen.
* Kontrollflüsse sind Informationen zum Endestatus eines Schrittes, die verwendet werden können, um die Aktion eines nächsten Schritts zu starten. Sie laufen über Verbindungen vom [[DiagramElements-Pin#Enable_Output_Pin|Trigger-Ausgang]] eines Schrittes zum [[DiagramElements-Pin#Enable_Input_Pin|Trigger-Eingang]] eines anderen.
Beide können die Ausführung eines Folgeschritts auslösen.

== Diagrammelemente ==
Als "''Diagrammelemente''" werden die Bestandteile eines Aktivitätsdiagramms bezeichnet. Sie definieren das Verhalten des [[Compound Block|Zusammengesetzten Aktionsblocks]] und werden im [[Compound Network Editor|Netzwerkeditor]] bearbeitet.

== Einführendes Beispiel eines Aktivitätsdiagramms ==

Das folgende Beispiel erläutert die Hauptkomponenten eines Aktivitätsdiagramms:

[[Bild:diagram-elements.jpg|760px|Ein Aktivitätsdiagramm]]

Das Diagramm beschreibt den Test einer E-Mail-Übertragung. Zuerst erzeugt der Schritt "Create Unique ID" eine sog. UUID und stellt diese an seinem Ausgangspin zur Verfügung. Diese UUID wird später gebraucht, um den korrekten Empfang der E-Mail zu verifizieren. Die UUID wird vom Schritt "Send E-Mail [SMTP]" empfangen, welcher eine E-Mail mittels dem SMTP Protokoll verschickt, und die UUID als Subject verwendet. Als nächstes sorgt der "Time [Delay]" Schritt für eine Verzögerung von 5 Sekunden (in denen die E-Mail übermittelt wird). Am Ende prüft der Schritt "Check for incoming Mail" ob eine E-Mail mit dem angegebenen Subject angekommen ist, wozu obige UUID gebraucht wird.
Der Test wird einen Fehler melden, falls eine solche E-Mail nicht gefunden wird.

Beachten Sie bitte, dass die graphische Darstellung des Diagramms im Grunde der UML-Notation entspricht. Allerdings werden um die Lesbarkeit zu erhöhen, und um wichtige Aspekte der Ausführung hervorzuheben einige Element etwas anders bzw. zusätzlich annotiert dargestellt. Insbesondere werden die Stereotypen der Pins durch unterschiedliche Pin-Darstellungen hervorgehoben, anstatt durch textuelle "<<stereotype>>"-labels, wie in UML.


=== [[DiagramElements-Step|Schritt]] (7) ===

Als "''Schritt''" wird eine Aktion (Aktionsbaustein) bezeichnet, welcher in ein Diagramm platziert wurde. Diese Aktion kann ihrerseits entweder ein sog. [[Elementary Block|Elementablock]] sein (wie z.B. "Create Unique ID"), welche ihre Aktion durch eine textuellen Programmcode definiert, oder wieder ein [[Compound Block|zusammengesetzter Block]] (wie z.B. "Check Incoming Mail"), welcher durch ein eigenes Aktivitätsdiagramm definiert wurde. Für das Diagrammnetzwerk in welches der Aktionsblock platziert wurde ist kein Unterschied im Verhalten sichtbar: ein Diagramm, welches einen Aktionsblock beinhaltet (d.h. einen Schritt enthält) sieht kein unterschiedliches Verhalten in Abhängigkeit der effektiven Realisierung seiner Schritte. Tatsächlich gibt es auch keine Unterschiede in der graphischen Darstellung, so dass es auch für den Entwickler eines zusammengesetzten Blocks keinen Unterschied macht (er muss nicht wissen, wie die Interna einer Aktion aufgebaut sind). Alle Schritte werden gleichermaßen durch die Verfügbarkeit von Eingangsdaten gestartet, führen ihre Bearbeitung durch, und liefern ihre Resultate an den Ausgangspins. Details zum Verhalten von Schritten sind in einem [[DiagramElements-Step | separaten Document]] nachzulesen.

=== Autostart (1) ===

Ein Schritt mit der Autostart Option wird automatisch gestartet, sobald das umgebende Netzwerk ausgeführt wird. Schritte ohne Autostart-Option werden lediglich ausgeführt, sobald Daten an den Eingangspins des Schrittes erscheinen. Autostart wird insbesondere für Schritte benötigt, welche keine Eingangspins haben, oder welche nicht durch einen Kontrollfluss gestartet werden. Auch Schritte, deren Eingang lediglich konstante Parameter darstellen müssen so gestartet werden. Im obigen Diagramm trifft dies für den linken "Create Unique ID" Schritt zu.

Im Diagrammeditor werden Schritte mit Autostart mit einem speziellen Icon am linken oberen Rand dargestellt; falls Sie die Standard-UML-Notation bevorzugen, können Sie auch einen START-Block aus der Bibliothek verwenden und dessen Trigger-Ausgangspin mit dem zuerst auszuführenden Schritt verbinden.

=== [[DiagramElements-Pin|Pin]] (3, 6, 9) ===

[[DiagramElements-Pin|Pins]] dienen zur Weitergabe von Daten und Triggerinformationen zwischen Schritten. Diese Pins können entweder [[DiagramElements-Pin#Output Pin|Ausgangespins]] (3) sein, um Daten zu senden, oder [[DiagramElements-Pin#Input Pin|Eingangspins]] (9), um Daten zu empfangen. Weitere Pins dienen dazu besondere Situationen wie z.B. [[DiagramElements-Pin#Exception Output Pin|Ausnahmebehandlung]] zu melden. Im obigen Diagramm, ist der Exception-Ausgang des "Check Incoming Mail" Schritts mit dem Trigger-Eingang des "FAIL" Schrittes verbunden.
Kontrollflusspins (Trigger und Status) sind vertikal angeordnet, wohingegen Datenflüsse als horizontal Pins dargestellt werden.
Eingangspins sind immer oben oder links, Ausgangspins immer unten oder rechts angeordnet.
Pins werden entsprechend ihrem Verhalten leicht unterschiedlich dargestellt; insbesondere auf das Puffer- und Triggerverhalten wird durch ausgefüllt vs. nicht gefüllt hingewiesen, da diese wichtig sind für die Ausführung. Pins werden in einem [[DiagramElements-Pin | separaten Dokument]] detailliert beschrieben.

=== [[DiagramElements-Connection|Verbindung]] (4,8) ===

Verbindungen dienen zum Weiterleiten von Daten oder Kontrollinformationen zu einem oder mehreren Eingangspins (eines oder mehrerer Folgeschritte).
Im Sinne von UML sind alle Verbindungen in expecco immer "Objektverbindungen".

==== Datenflussverbindung (4) ====

Diese befördern Daten (-Objekte) von einem Ausgangspin zu einem Eingangspins eines Folgeschritts. Im obigen Beispiel sendet der erste Schritt die erzeugte UUID an zwei weitere Schritte.
Datenflusspins sind immer links und rechts angeordnet (horizontale Pins).

==== Kontrollflussverbindung (8) ====

Diese dienen dazu, die Ausführung unabhängig von Daten (aber abhängig von der Ausführung eines Schrittes) zu kontrollieren. Im Beispiel werden die Schritte rechts im Bild sequentiell ausgeführt, wozu der Triggerausgang eines Schrittes mit dem Triggereingang eines Folgeschrittes verbunden wurde.
Kontrollflusspins sind immer oben und unten angeordnet (vertikale Pins).

=== [[DiagramElements-Freeze Value|Freeze Value (Vorbelegungswert)]] (6) ===

Eingangswerte eines Pins können mit einem statischen Wert vorbelegt werden (Konstante).
Im Beispiel sind der Text der E-Mail, die E-Mail-Adresse, die Wartezeit und auch die Fehlermeldung auf diese Weise "eingefroren".
Ein vorbelegter Pin sollte typischerweise als nicht-triggernd und nicht-konsumierend (sogenannter "''Parameterpin''") konfiguriert werden, wofür es einen besonderen Menüeintrag gibt (außerdem werden beim "''Einfrieren''" die Pins vom Editor automatisch als solche umdefiniert). Details zum Triggerverhalten und zum Konsumieren von Eingangswerten finden sie im Dokument: [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Freeze Value|Vorbelegung aus Umgebungsvariablen]] (5) ===

Eingangswerte eines Pins können ebenfalls aus einer Variable gelesen werden. Diese Variablen werden in einer sogenannten "''Variablenumgebung''" bereit gestellt, welche im umgebenden zusammengesetzten Bausteinen oder der [[TestSuite Element|Testsuite]] definiert werden. Im obigen Beispiel werden der Name des E-Mail-Kontos sowie der E-Mail-Serverhost aus solchen Variablen gelesen (und entsprechende Einträge in der Variablenumgebung der Testsuite vorausgesetzt). Wie auch reguläre Vorbelegungen sollte der Pin als nicht-triggernd und nicht-konsumierend definiert werden (i.e. "''Parameterpin''"). Lesen Sie dazu ebenfalls das Kapitel [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Annotation|Annotation]] (2) ===

Annotationen dienen dazu, Kommentare oder Zusatzinformationen für Entwickler oder Tester im Diagramm mit abzulegen. Möglich sind sowohl textuelle Annotation, als auch importierte Grafiken (Bilder im GIF-, JPEG- oder PNG-Format). Sie können auch dazu genutzt werden, um wichtige Teile des Diagramms farblich hervorzuheben, indem Sie eine leere Textannotation mit einer Hintergrundfarbe unter Teile ihres Diagramms legen.

=== [[DiagramElements-Probe|Messfühler]] ===

Messfühler (im obigen Diagramm nicht gezeigt) dienen dazu Pin-Werte aufzuzeichnen und/oder zu validieren. Messfühler bieten einen komfortablen und lesbaren Mechanismus um Werte auf ihre Gültigkeit zu prüfen.

== Semantik ==
=== Relation zu IEC1131 ===
Expeccos Aktivitätsdiagramme ähneln stark den Funktionblöcken der IEC1131-3 FBD Sprache (siehe ua. [https://en.wikipedia.org/wiki/Function_block_diagram Wikipedia]).
Sowohl die grafische Darstellung als auch das Ausführungsverhalten sind vergleichbar. Ingenieure mit einem SPS Hintergrund werden keine Probleme haben, Expeccos Aktionsdefinitionen und zusammengesetzte Aktionen zu verstehen.

=== Relation zu Petrinetzen ===
A Petri Net [http://en.wikipedia.org/wiki/Petri_net| ->Wikipedia] is a network consisting of places (with possible action processing) and transitions. In a classical petri net, anonymous tokens travel along connections and transitions control the firing (triggering) of following action steps depending on the arrival of tokens at their input side, and passing tokens to their output side. Expecco has combined the transition and place functionality into a single step item, in order to make the graphical representation more dense (and also for its similarity with UML-2 activity diagrams and other flow based diagrams). However, semantically, they behave the same, and any diagram could be rewritten by using separate items (collecting inputs and passing a tuple of tokens on to the place).

[[Datei:Beispiel.png]]

An expecco step with multiple input pins corresponds to a Petri Net transition with multiple inputs followed by a Petri Net action. Similar to transitions in a Petri Net, the input side of a step can be configured to require either any input or all input values to be present. In expecco, this is called the step's "''trigger condition''" and described in detail in the [[DiagramElements-Step|step documentation]].

"''Higher order Petri Nets''" are Petri Nets containing other Petri Nets as places, which is exactly what a compound block is in expecco.
"''Coloured Petri Nets''" are Petri Nets where not simple anonymous tokens are passed around, but data objects (or references to them, as in expecco).

Thus, in standard Petri Net notation, expecco's diagrams are therefore "''higher ordered colored Petri Nets''".

=== Relation zu UML Aktivitätsdiagrammen ===
--- to be written

=== Relation zu Flussdiagrammen ===
Aktivitätsdiagramme können als Obermenge von Flussdiagrammen betrachtet werden. Dazu werden die Aktionen lediglich über Kontrollflussverbindungen (Trigger-in/Trigger-out) verbunden (Daten werden hierbei über Variablen ausgetauscht).

Die Wenn-Dann bedingte Verzeigung eines Flussdiagramms entspricht einem 2-Wege-If Aktionsblock (aus der Standardbibliothek). Schleifen werden durch Verbindungen der Trigger-out mit einem Trigger-in eines vorhergehenden Schrittes definiert.

== Editoren ==
The activity diagram which defines the behavior of a compound block
is edited in the [[CompoundBlock Editor-CompoundWorksheet Editor/en|''network editor'']], also called "''diagram editor''" or "''network diagram editor''".
This editor presents the "internal view" of the block.
In contrast, the interface of an compound block (e.g. number and type of pins) can be regarded as its "external view" and is presented and defined in the [[Scheme Editor/en|''schema editor'']].

== Siehe auch ==
[[Tree Elements | Tree Elements]]

[[Block Element]], [[DiagramElements-Step/en|Schritt]], [[DiagramElements-Connection|Verbindung]],
[[ElementaryBlock_Element|Elementaraktion]],

Zurück zur [[Online Documentation#Tree Elements|Online Documentation]].

[[Category: Tree Elements]]
[[Category: Incomplete]]

CompoundBlock Element/en

2024-07-16T11:51:10Z

Matilk: /* Diagram Elements */

== Introduction ==
A "''Compound Action Block''" describes an [[Block_Element/en|action]]'s behavior with an activity diagram. The diagram is similar to [[#Relationship_to_UML_Activity_Diagrams|data flow diagrams]] as used in UML2.0 and also has many features in common with [[#Relationship_to_Petri_Nets|Petri Nets]]. The diagram consists of sub actions called [[DiagramElements-Step|''steps'']].

The execution is controlled via a combination of data and control flows which are passed via inter-step connections:

* Data flows are defined as values (results, measurement values, objects, documents etc.) being passed from one step to another. These flows are defined by interconnections from a step's [[DiagramElements-Pin#Output Pin|output pin]] to another step's [[DiagramElements-Pin#Input Pin|input pin]].

* Control flows are defined as "''action finished''" information being used to trigger another step's action. These flows are defined by interconnections from a step's [[DiagramElements-Pin#Enable_Output_Pin|''Trigger Output Pin'']] to another step's [[DiagramElements-Pin#Enable_Input_Pin|''Trigger Input Pin'']]. (these are also occasionally called "''Enable Output Pin''" and "''Enable Input Pin''" in this documentation).

Both can trigger the execution of a subsequent step.

== Diagram Elements ==
Diagram elements are the elements in an activity diagram. They define the behavior of the [[Compound Block|compound action block]] and are manipulated in the [[Compound_Network_Editor/en|network editor]].

== Introductory Activity Diagram Example ==

The following example shows the major components of an activity diagram.

[[Bild:diagram-elements.jpg|760px|An activity diagram]]

The diagram models a test of an e-mail transmission:
* First, the step "Create Unique ID" creates a so-called [[Glossary/en#UUID_.28Universal_Unique_Identifier.29 |UUID]] (Universal Unique Identifier) at its output pin, which is used later to check whether the correct e-mail has arrived.
* The UUID is delivered to the step "Send E-Mail [SMTP]", which sends an e-mail via SMTP ([https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol "Simple Mail Transfer Protocol"]) using the UUID as subject.
* Next, the "Time [Delay]" step waits for 5 seconds.
* Finally, "Check for incoming Mail" checks whether an e-mail has arrived with the given UUID as subject. If there is no such e-mail the test will fail.

Notice that the definition of activity diagrams in expecco corresponds largely with the UML notation. However, to emphasize important aspects and to make the diagram easier to read, some elements differ slightly from the standard UML notation. Especially, pin stereotypes are rendered directly as different pin style instead of adding extra "<<stereotype>>" labels.


=== [[DiagramElements-Step|Step]] (7) ===

A "''step''" is a action block which is placed into an activity diagram. These blocks can be either [[Elementary Block|elementary blocks]] (such as "Create Unique ID") which are defined by a piece of source code or [[Compound Block|compound blocks]] (such as "Check Incoming Mail") which are defined by their own activity diagram. To the network where a block is placed, there is no difference in the behavior. The network which uses an action (i.e. places a step) does not need to know how the internals of the action are implemented. Actually, there is not even a visual difference in the diagram. All are triggered by the availability of input data, perform an operation, and generate results on their output(s).

Steps are described in detail in a [[DiagramElements-Step | separate document]].

=== Autostart (1) ===

A step with autostart option will be triggered automatically, whenever the containing activity diagram network is executed. Without the autostart option, steps are only started when input data arrives at the step's input pin(s). Autostart is required for steps which have no input and are not triggered by a control flow connection. In the above diagram, this is the case for the leftmost "Create Unique ID" step.

The diagram editor renders auto started blocks with a special icon at its top-left corner; if you prefer the standard UML notation, you can place a separate START block and connect its trigger pins.

=== [[DiagramElements-Pin|Pin]] (3, 6, 9) ===

[[DiagramElements-Pin|Pins]] are used to exchange data and trigger information between steps.
These pins can be [[DiagramElements-Pin#Output Pin|output pins]] (3) to send data or [[DiagramElements-Pin#Input Pin|input pins]] (9) to receive data.
Other pins are used for special tasks like [[DiagramElements-Pin#Exception Output Pin|exception handling]];
in the above diagram, the vertical exception output of the "Check Incoming Mail" step is connected to the trigger input of the "FAIL" notifying step.

Control-flow pins (trigger and status) are oriented vertically, whereas data-flow pins are oriented horizontally.
Input pins are always located at the top or left, whereas output pins are located at the right or bottom.

Pins are rendered according to their behavior during execution;
especially consuming vs. non-consuming input behaviour
and buffered vs. non-buffered output behavior
is drawn (filled vs. unfilled) to highlight these important facts.

Pins are described in detail in a [[DiagramElements-Pin | separate document]].

=== [[DiagramElements-Connection|Connection]] (4,8) ===

Connections are used to interconnect steps to pass data or control information from an output pin to one or more input pins.
In the UML sense, all connections are object connections.

==== Data Flow Connection (4) ====

These connections deliver data from a step's output pin to another step's input pin. In the example, the first step sends the generated UUID to two other steps.
Data flow pins are always located at the left and right of a step (horizontal pins), and the left pins are always inputs, whereas the right pins are always outputs.

==== Control Flow Connection (8) ====

These connections are used to control the execution order in an activity diagram. In the example the steps on the right are executed sequential.
Control flow pins are always located at the top and bottom of a step (vertical pins), and pins at the top are always inputs, whereas pins at the bottom are always outputs.

=== [[DiagramElements-Freeze Value|Freeze Value]] (6) ===

The data which is read by a pin can be ''frozen'' to a static value (constant). In the above example, the "message text", the "e-mail address", the "waiting time" and also the "failure message" are ''frozen''.
A frozen pin should typically be configured to be non-triggering and non-consuming (so called "''parameter pin''"). For details on triggering and consumption of values, please read the chapter on [[DiagramElements-Pin#Input_Pin_Trigger_Attributes |"''Input Pin Trigger Behavior''"]] in the [[DiagramElements-Pin | "''pin documentation''"]].

=== [[DiagramElements-Freeze Value|Environment Freeze Value]] (5) ===

The data for a pin can also read from a variable. These can be defined in the environment of the compound block or the [[Testsuite Element|testsuite]]. In the example, the user name and the server are fetched from such variables. A frozen pin should typically be configured to be non-triggering and non-consuming (so called "''parameter pin''"). For details on triggering and consumption of values, please read the chapter on [[DiagramElements-Pin#Input Pin| "''Input Pin Trigger Behavior''"]] in the [[DiagramElements-Pin | "''pin documentation''"]].

=== [[DiagramElements-Annotation|Annotation]] (2) ===

In order to comment a diagram, or to place additional notes for developers and testers, annotations can be used. Annotations can be either text fields or imported graphics (GIF, JPEG or PNG images). You can highlight important parts of the diagram by using an empty text annotation with a non-white background color.

=== [[DiagramElements-Probe|Probes]] ===

Probes (not shown in the above diagram) allow for pin-values to be recorded and/or checked for being valid. Probes provide an easy to use and concise mechanism for value checking.

== Semantics ==

=== Relationship to IEC1131 Function Block Diagrams ===
Expecco's compound action block execution model has many similarities with [https://en.wikipedia.org/wiki/IEC_61131 IEC-61131-3] (also IEC-1131-3 or EN 61131-3) [https://en.wikipedia.org/wiki/Function_block_diagram Function Block Diagrams]
which is a wellknown standard in programmable logic controller programming.

Input values are read initially, the step execution is controlled by data flow, and output values are written
at the end of the action's execution. However, differences exist in the data types, which are more polymorphic in expecco, and additional pin attributes (such as eg. mailbox pins).

=== Relationship to Petri Nets ===
A Petri Net [http://en.wikipedia.org/wiki/Petri%20net (see Wikipedia)] is a network consisting of places (with possible action processing) and transitions. In a classical petri net, anonymous tokens travel along connections and transitions control the firing (triggering) of following action steps depending on the arrival of tokens at their input side, and passing tokens to their output side.

Expecco has combined the transition and place functionality into a single step item, in order to make the graphical representation more dense (and also for its similarity with UML-2 activity diagrams and other flow based diagrams). However, semantically, they behave the same, and any diagram could be rewritten by using separate items (collecting inputs and passing a tuple of tokens on to the place).

[[Datei:Beispiel.png]]

An expecco step with multiple input pins corresponds to a Petri Net transition with multiple inputs followed by a Petri Net action. Similar to transitions in a Petri Net, the input side of a step can be configured to require either any input or all input values to be present. In expecco, this is called the step's "''trigger condition''" and described in detail in the [[DiagramElements-Step|step documentation]].

"''Higher order Petri Nets''" are Petri Nets containing other Petri Nets as places, which is exactly what a compound block is in expecco. 
"''Coloured Petri Nets''" are Petri Nets where not simple anonymous tokens are passed around, but data objects (or references to them, as in expecco).

Thus, in standard Petri Net notation, expecco's diagrams are therefore "''Higher Order Colored Petri Nets''".

=== Relationship to UML Activity Diagrams ===
Compound actions in expecco are isomorph to UML activity diagrams with a particular predefined set of stereotypes for connections, pins and action steps. These stereotypes are hardcoded in expecco, and define the semantics of action triggering, queueing behaviour of data connections, and the optional parallel execution of steps. The graphical representation is slightly different, to replace the somewhat clumsy <<stereotype>> annotations by different pin images (filled/unfilled etc.). Also, all connections in expecco are object-connections, and all pins receive and generate objects as values.

=== Relationship to Flow Chart Diagrams ===
Activity diagrams can also be seen as a superset of flow chart diagrams. Flow charts can be translated into an activity diagram in which only control flow connections are used. Vice versa: an activity diagram which uses only control flow connections and uses no parallelism can be translated back into a flow chart diagram.

The if-then-else conditional branches of a traditional flow chart diagram correspond to the 2-way if action blocks of the expecco standard library. Loops are implemented by connecting a trigger output pin to a previous step's trigger input pin.

== Editors ==
The activity diagram which defines the behavior of a compound block
is edited in the "[[CompoundBlock Editor-CompoundWorksheet Editor/en|''Network editor'']]", also called "''Diagram Editor''" or "''Network Diagram Editor''".
This editor presents the "''internal view''" of the block.
In contrast, the interface of a compound block (e.g. number and type of pins) can be regarded as its "''external view''" and is presented and defined in the "[[Scheme Editor/en|''Schema Editor'']]".

== See Also ==
[[Tree Elements | Tree Elements]]

[[Block Element]], [[DiagramElements-Step/en|Step]], [[DiagramElements-Connection|Connection]],
[[ElementaryBlock_Element|Elementary Action]],

Back to [[Online Documentation#Tree Elements|Online Documentation]].

[[Category: Tree Elements]]
[[Category: Incomplete]]

CompoundBlock Element

2024-07-16T11:50:33Z

Matilk: /* Diagrammelemente */

== Einführung ==
Ein zusammengesetzter Aktionsblock (englisch "''Compound Action''") beschreibt das Verhalten einer [[Block_Element|Aktion]] graphisch als Aktivitätsdiagramm. Diese Diagramme sind vergleichbar mit den [[#Relation_zu_UML_Aktivit.C3.A4tsdiagrammen|Datenflussdiagrammen]] wie in UML2.0 definiert. Sie haben außerdem viele Eigenschaften gemein mit [[#Relation_zu_Petrinetzen|Petrinetzen]]. Das Diagramm besteht aus Unteraktionen, welche als [[DiagramElements-Step|''Schritte'']] bezeichnet werden.

Die Ausführung wird durch eine Kombination von Daten- und Kontrollflüssen gesteuert, die durch Verbindungen zwischen den Schritten übertragen werden:
* Als Datenfluss wird die Übergabe von Werten (Resultate, Messwerte, Objekte, Dokumente etc.) von einem Schritt zum nächsten bezeichnet. Ein Datenfluss läuft über Verbindungen vom [[DiagramElements-Pin#Output_Pin|Ausgangspin]] (Pin = "Stecker/Sockel") eines Schritts zum [[DiagramElements-Pin#Input_Pin|Eingangspin]] eines anderen.
* Kontrollflüsse sind Informationen zum Endestatus eines Schrittes, die verwendet werden können, um die Aktion eines nächsten Schritts zu starten. Sie laufen über Verbindungen vom [[DiagramElements-Pin#Enable_Output_Pin|Trigger-Ausgang]] eines Schrittes zum [[DiagramElements-Pin#Enable_Input_Pin|Trigger-Eingang]] eines anderen.
Beide können die Ausführung eines Folgeschritts auslösen.

== Diagrammelemente ==
Als "''Diagrammelemente''" werden die Bestandteile eines Aktivitätsdiagramms bezeichnet. Sie definieren das Verhalten des [[Compound Block|Zusammengesetzten Aktionsblocks]] und werden im [[Compound Network Editor|Netzwerkeditor]] bearbeitet.

== Einführendes Beispiel eines Aktivitätsdiagramms ==

Das folgende Beispiel erläutert die Hauptkomponenten eines Aktivitätsdiagramms:

[[Bild:diagram-elements.jpg|760px|Ein Aktivitätsdiagramm]]

Das Diagramm beschreibt den Test einer E-Mail-Übertragung. Zuerst erzeugt der Schritt "Create Unique ID" eine sog. UUID und stellt diese an seinem Ausgangspin zur Verfügung. Diese UUID wird später gebraucht, um den korrekten Empfang der E-Mail zu verifizieren. Die UUID wird vom Schritt "Send E-Mail [SMTP]" empfangen, welcher eine E-Mail mittels dem SMTP Protokoll verschickt, und die UUID als Subject verwendet. Als nächstes sorgt der "Time [Delay]" Schritt für eine Verzögerung von 5 Sekunden (in denen die E-Mail übermittelt wird). Am Ende prüft der Schritt "Check for incoming Mail" ob eine E-Mail mit dem angegebenen Subject angekommen ist, wozu obige UUID gebraucht wird.
Der Test wird einen Fehler melden, falls eine solche E-Mail nicht gefunden wird.

Beachten Sie bitte, dass die graphische Darstellung des Diagramms im Grunde der UML-Notation entspricht. Allerdings werden um die Lesbarkeit zu erhöhen, und um wichtige Aspekte der Ausführung hervorzuheben einige Element etwas anders bzw. zusätzlich annotiert dargestellt. Insbesondere werden die Stereotypen der Pins durch unterschiedliche Pin-Darstellungen hervorgehoben, anstatt durch textuelle "<<stereotype>>"-labels, wie in UML.


=== [[DiagramElements-Step|Schritt]] (7) ===

Als "''Schritt''" wird eine Aktion (Aktionsbaustein) bezeichnet, welcher in ein Diagramm platziert wurde. Diese Aktion kann ihrerseits entweder ein sog. [[Elementary Block|Elementablock]] sein (wie z.B. "Create Unique ID"), welche ihre Aktion durch eine textuellen Programmcode definiert, oder wieder ein [[Compound Block|zusammengesetzter Block]] (wie z.B. "Check Incoming Mail"), welcher durch ein eigenes Aktivitätsdiagramm definiert wurde. Für das Diagrammnetzwerk in welches der Aktionsblock platziert wurde ist kein Unterschied im Verhalten sichtbar: ein Diagramm, welches einen Aktionsblock beinhaltet (d.h. einen Schritt enthält) sieht kein unterschiedliches Verhalten in Abhängigkeit der effektiven Realisierung seiner Schritte. Tatsächlich gibt es auch keine Unterschiede in der graphischen Darstellung, so dass es auch für den Entwickler eines zusammengesetzten Blocks keinen Unterschied macht (er muss nicht wissen, wie die Interna einer Aktion aufgebaut sind). Alle Schritte werden gleichermaßen durch die Verfügbarkeit von Eingangsdaten gestartet, führen ihre Bearbeitung durch, und liefern ihre Resultate an den Ausgangspins. Details zum Verhalten von Schritten sind in einem [[DiagramElements-Step | separaten Document]] nachzulesen.

=== Autostart (1) ===

Ein Schritt mit der Autostart Option wird automatisch gestartet, sobald das umgebende Netzwerk ausgeführt wird. Schritte ohne Autostart-Option werden lediglich ausgeführt, sobald Daten an den Eingangspins des Schrittes erscheinen. Autostart wird insbesondere für Schritte benötigt, welche keine Eingangspins haben, oder welche nicht durch einen Kontrollfluss gestartet werden. Auch Schritte, deren Eingang lediglich konstante Parameter darstellen müssen so gestartet werden. Im obigen Diagramm trifft dies für den linken "Create Unique ID" Schritt zu.

Im Diagrammeditor werden Schritte mit Autostart mit einem speziellen Icon am linken oberen Rand dargestellt; falls Sie die Standard-UML-Notation bevorzugen, können Sie auch einen START-Block aus der Bibliothek verwenden und dessen Trigger-Ausgangspin mit dem zuerst auszuführenden Schritt verbinden.

=== [[DiagramElements-Pin|Pin]] (3, 6, 9) ===

[[DiagramElements-Pin|Pins]] dienen zur Weitergabe von Daten und Triggerinformationen zwischen Schritten. Diese Pins können entweder [[DiagramElements-Pin#Output Pin|Ausgangespins]] (3) sein, um Daten zu senden, oder [[DiagramElements-Pin#Input Pin|Eingangspins]] (9), um Daten zu empfangen. Weitere Pins dienen dazu besondere Situationen wie z.B. [[DiagramElements-Pin#Exception Output Pin|Ausnahmebehandlung]] zu melden. Im obigen Diagramm, ist der Exception-Ausgang des "Check Incoming Mail" Schritts mit dem Trigger-Eingang des "FAIL" Schrittes verbunden.
Kontrollflusspins (Trigger und Status) sind vertikal angeordnet, wohingegen Datenflüsse als horizontal Pins dargestellt werden.
Eingangspins sind immer oben oder links, Ausgangspins immer unten oder rechts angeordnet.
Pins werden entsprechend ihrem Verhalten leicht unterschiedlich dargestellt; insbesondere auf das Puffer- und Triggerverhalten wird durch ausgefüllt vs. nicht gefüllt hingewiesen, da diese wichtig sind für die Ausführung. Pins werden in einem [[DiagramElements-Pin | separaten Dokument]] detailliert beschrieben.

=== [[DiagramElements-Connection|Verbindung]] (4,8) ===

Verbindungen dienen zum Weiterleiten von Daten oder Kontrollinformationen zu einem oder mehreren Eingangspins (eines oder mehrerer Folgeschritte).
Im Sinne von UML sind alle Verbindungen in expecco immer "Objektverbindungen".

==== Datenflussverbindung (4) ====

Diese befördern Daten (-Objekte) von einem Ausgangspin zu einem Eingangspins eines Folgeschritts. Im obigen Beispiel sendet der erste Schritt die erzeugte UUID an zwei weitere Schritte.
Datenflusspins sind immer links und rechts angeordnet (horizontale Pins).

==== Kontrollflussverbindung (8) ====

Diese dienen dazu, die Ausführung unabhängig von Daten (aber abhängig von der Ausführung eines Schrittes) zu kontrollieren. Im Beispiel werden die Schritte rechts im Bild sequentiell ausgeführt, wozu der Triggerausgang eines Schrittes mit dem Triggereingang eines Folgeschrittes verbunden wurde.
Kontrollflusspins sind immer oben und unten angeordnet (vertikale Pins).

=== [[DiagramElements-Freeze Value|Freeze Value (Vorbelegungswert)]] (6) ===

Eingangswerte eines Pins können mit einem statischen Wert vorbelegt werden (Konstante).
Im Beispiel sind der Text der E-Mail, die E-Mail-Adresse, die Wartezeit und auch die Fehlermeldung auf diese Weise "eingefroren".
Ein vorbelegter Pin sollte typischerweise als nicht-triggernd und nicht-konsumierend (sogenannter "''Parameterpin''") konfiguriert werden, wofür es einen besonderen Menüeintrag gibt (außerdem werden beim "''Einfrieren''" die Pins vom Editor automatisch als solche umdefiniert). Details zum Triggerverhalten und zum Konsumieren von Eingangswerten finden sie im Dokument: [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Freeze Value|Vorbelegung aus Umgebungsvariablen]] (5) ===

Eingangswerte eines Pins können ebenfalls aus einer Variable gelesen werden. Diese Variablen werden in einer sogenannten "''Variablenumgebung''" bereit gestellt, welche im umgebenden zusammengesetzten Bausteinen oder der [[TestSuite Element|Testsuite]] definiert werden. Im obigen Beispiel werden der Name des E-Mail-Kontos sowie der E-Mail-Serverhost aus solchen Variablen gelesen (und entsprechende Einträge in der Variablenumgebung der Testsuite vorausgesetzt). Wie auch reguläre Vorbelegungen sollte der Pin als nicht-triggernd und nicht-konsumierend definiert werden (i.e. "''Parameterpin''"). Lesen Sie dazu ebenfalls das Kapitel [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Annotation|Annotation]] (2) ===

Annotationen dienen dazu, Kommentare oder Zusatzinformationen für Entwickler oder Tester im Diagramm mit abzulegen. Möglich sind sowohl textuelle Annotation, als auch importierte Grafiken (Bilder im GIF-, JPEG- oder PNG-Format). Sie können auch dazu genutzt werden, um wichtige Teile des Diagramms farblich hervorzuheben, indem Sie eine leere Textannotation mit einer Hintergrundfarbe unter Teile ihres Diagramms legen.

=== [[DiagramElements-Probe|Messfühler]] ===

Messfühler (im obigen Diagramm nicht gezeigt) dienen dazu Pin-Werte aufzuzeichnen und/oder zu validieren. Messfühler bieten einen komfortablen und lesbaren Mechanismus um Werte auf ihre Gültigkeit zu prüfen.

== Relation zu IEC1131 ==
Expeccos Aktivitätsdiagramme ähneln stark den Funktionblöcken der IEC1131-3 FBD Sprache (siehe ua. [https://en.wikipedia.org/wiki/Function_block_diagram Wikipedia]).
Sowohl die grafische Darstellung als auch das Ausführungsverhalten sind vergleichbar. Ingenieure mit einem SPS Hintergrund werden keine Probleme haben, Expeccos Aktionsdefinitionen und zusammengesetzte Aktionen zu verstehen.

== Relation zu Petrinetzen ==
A Petri Net [http://en.wikipedia.org/wiki/Petri_net| ->Wikipedia] is a network consisting of places (with possible action processing) and transitions. In a classical petri net, anonymous tokens travel along connections and transitions control the firing (triggering) of following action steps depending on the arrival of tokens at their input side, and passing tokens to their output side. Expecco has combined the transition and place functionality into a single step item, in order to make the graphical representation more dense (and also for its similarity with UML-2 activity diagrams and other flow based diagrams). However, semantically, they behave the same, and any diagram could be rewritten by using separate items (collecting inputs and passing a tuple of tokens on to the place).

[[Datei:Beispiel.png]]

An expecco step with multiple input pins corresponds to a Petri Net transition with multiple inputs followed by a Petri Net action. Similar to transitions in a Petri Net, the input side of a step can be configured to require either any input or all input values to be present. In expecco, this is called the step's "''trigger condition''" and described in detail in the [[DiagramElements-Step|step documentation]].

"''Higher order Petri Nets''" are Petri Nets containing other Petri Nets as places, which is exactly what a compound block is in expecco.
"''Coloured Petri Nets''" are Petri Nets where not simple anonymous tokens are passed around, but data objects (or references to them, as in expecco).

Thus, in standard Petri Net notation, expecco's diagrams are therefore "''higher ordered colored Petri Nets''".

== Relation zu UML Aktivitätsdiagrammen ==
--- to be written

== Relation zu Flussdiagrammen ==
Aktivitätsdiagramme können als Obermenge von Flussdiagrammen betrachtet werden. Dazu werden die Aktionen lediglich über Kontrollflussverbindungen (Trigger-in/Trigger-out) verbunden (Daten werden hierbei über Variablen ausgetauscht).

Die Wenn-Dann bedingte Verzeigung eines Flussdiagramms entspricht einem 2-Wege-If Aktionsblock (aus der Standardbibliothek). Schleifen werden durch Verbindungen der Trigger-out mit einem Trigger-in eines vorhergehenden Schrittes definiert.

== Editoren ==
The activity diagram which defines the behavior of a compound block
is edited in the [[CompoundBlock Editor-CompoundWorksheet Editor/en|''network editor'']], also called "''diagram editor''" or "''network diagram editor''".
This editor presents the "internal view" of the block.
In contrast, the interface of an compound block (e.g. number and type of pins) can be regarded as its "external view" and is presented and defined in the [[Scheme Editor/en|''schema editor'']].

[[Category: Tree Elements]]
[[Category: Incomplete]]

CompoundBlock Element/en

2024-07-16T10:56:23Z

Matilk: /* Introduction */

== Introduction ==
A "''Compound Action Block''" describes an [[Block_Element/en|action]]'s behavior with an activity diagram. The diagram is similar to [[#Relationship_to_UML_Activity_Diagrams|data flow diagrams]] as used in UML2.0 and also has many features in common with [[#Relationship_to_Petri_Nets|Petri Nets]]. The diagram consists of sub actions called [[DiagramElements-Step|''steps'']].

The execution is controlled via a combination of data and control flows which are passed via inter-step connections:

* Data flows are defined as values (results, measurement values, objects, documents etc.) being passed from one step to another. These flows are defined by interconnections from a step's [[DiagramElements-Pin#Output Pin|output pin]] to another step's [[DiagramElements-Pin#Input Pin|input pin]].

* Control flows are defined as "''action finished''" information being used to trigger another step's action. These flows are defined by interconnections from a step's [[DiagramElements-Pin#Enable_Output_Pin|''Trigger Output Pin'']] to another step's [[DiagramElements-Pin#Enable_Input_Pin|''Trigger Input Pin'']]. (these are also occasionally called "''Enable Output Pin''" and "''Enable Input Pin''" in this documentation).

Both can trigger the execution of a subsequent step.

== Diagram Elements ==
Diagram elements are the elements in an activity diagram. They define the behavior of the [[Compound Block|compound action block]] and are manipulated in the [[Network Editor/en|network editor]].

== Introductory Activity Diagram Example ==

The following example shows the major components of an activity diagram.

[[Bild:diagram-elements.jpg|760px|An activity diagram]]

The diagram models a test of an e-mail transmission:
* First, the step "Create Unique ID" creates a so-called [[Glossary/en#UUID_.28Universal_Unique_Identifier.29 |UUID]] (Universal Unique Identifier) at its output pin, which is used later to check whether the correct e-mail has arrived.
* The UUID is delivered to the step "Send E-Mail [SMTP]", which sends an e-mail via SMTP ([https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol "Simple Mail Transfer Protocol"]) using the UUID as subject.
* Next, the "Time [Delay]" step waits for 5 seconds.
* Finally, "Check for incoming Mail" checks whether an e-mail has arrived with the given UUID as subject. If there is no such e-mail the test will fail.

Notice that the definition of activity diagrams in expecco corresponds largely with the UML notation. However, to emphasize important aspects and to make the diagram easier to read, some elements differ slightly from the standard UML notation. Especially, pin stereotypes are rendered directly as different pin style instead of adding extra "<<stereotype>>" labels.


=== [[DiagramElements-Step|Step]] (7) ===

A "''step''" is a action block which is placed into an activity diagram. These blocks can be either [[Elementary Block|elementary blocks]] (such as "Create Unique ID") which are defined by a piece of source code or [[Compound Block|compound blocks]] (such as "Check Incoming Mail") which are defined by their own activity diagram. To the network where a block is placed, there is no difference in the behavior. The network which uses an action (i.e. places a step) does not need to know how the internals of the action are implemented. Actually, there is not even a visual difference in the diagram. All are triggered by the availability of input data, perform an operation, and generate results on their output(s).

Steps are described in detail in a [[DiagramElements-Step | separate document]].

=== Autostart (1) ===

A step with autostart option will be triggered automatically, whenever the containing activity diagram network is executed. Without the autostart option, steps are only started when input data arrives at the step's input pin(s). Autostart is required for steps which have no input and are not triggered by a control flow connection. In the above diagram, this is the case for the leftmost "Create Unique ID" step.

The diagram editor renders auto started blocks with a special icon at its top-left corner; if you prefer the standard UML notation, you can place a separate START block and connect its trigger pins.

=== [[DiagramElements-Pin|Pin]] (3, 6, 9) ===

[[DiagramElements-Pin|Pins]] are used to exchange data and trigger information between steps.
These pins can be [[DiagramElements-Pin#Output Pin|output pins]] (3) to send data or [[DiagramElements-Pin#Input Pin|input pins]] (9) to receive data.
Other pins are used for special tasks like [[DiagramElements-Pin#Exception Output Pin|exception handling]];
in the above diagram, the vertical exception output of the "Check Incoming Mail" step is connected to the trigger input of the "FAIL" notifying step.

Control-flow pins (trigger and status) are oriented vertically, whereas data-flow pins are oriented horizontally.
Input pins are always located at the top or left, whereas output pins are located at the right or bottom.

Pins are rendered according to their behavior during execution;
especially consuming vs. non-consuming input behaviour
and buffered vs. non-buffered output behavior
is drawn (filled vs. unfilled) to highlight these important facts.

Pins are described in detail in a [[DiagramElements-Pin | separate document]].

=== [[DiagramElements-Connection|Connection]] (4,8) ===

Connections are used to interconnect steps to pass data or control information from an output pin to one or more input pins.
In the UML sense, all connections are object connections.

==== Data Flow Connection (4) ====

These connections deliver data from a step's output pin to another step's input pin. In the example, the first step sends the generated UUID to two other steps.
Data flow pins are always located at the left and right of a step (horizontal pins), and the left pins are always inputs, whereas the right pins are always outputs.

==== Control Flow Connection (8) ====

These connections are used to control the execution order in an activity diagram. In the example the steps on the right are executed sequential.
Control flow pins are always located at the top and bottom of a step (vertical pins), and pins at the top are always inputs, whereas pins at the bottom are always outputs.

=== [[DiagramElements-Freeze Value|Freeze Value]] (6) ===

The data which is read by a pin can be ''frozen'' to a static value (constant). In the above example, the "message text", the "e-mail address", the "waiting time" and also the "failure message" are ''frozen''.
A frozen pin should typically be configured to be non-triggering and non-consuming (so called "''parameter pin''"). For details on triggering and consumption of values, please read the chapter on [[DiagramElements-Pin#Input_Pin_Trigger_Attributes |"''Input Pin Trigger Behavior''"]] in the [[DiagramElements-Pin | "''pin documentation''"]].

=== [[DiagramElements-Freeze Value|Environment Freeze Value]] (5) ===

The data for a pin can also read from a variable. These can be defined in the environment of the compound block or the [[Testsuite Element|testsuite]]. In the example, the user name and the server are fetched from such variables. A frozen pin should typically be configured to be non-triggering and non-consuming (so called "''parameter pin''"). For details on triggering and consumption of values, please read the chapter on [[DiagramElements-Pin#Input Pin| "''Input Pin Trigger Behavior''"]] in the [[DiagramElements-Pin | "''pin documentation''"]].

=== [[DiagramElements-Annotation|Annotation]] (2) ===

In order to comment a diagram, or to place additional notes for developers and testers, annotations can be used. Annotations can be either text fields or imported graphics (GIF, JPEG or PNG images). You can highlight important parts of the diagram by using an empty text annotation with a non-white background color.

=== [[DiagramElements-Probe|Probes]] ===

Probes (not shown in the above diagram) allow for pin-values to be recorded and/or checked for being valid. Probes provide an easy to use and concise mechanism for value checking.

== Semantics ==

=== Relationship to IEC1131 Function Block Diagrams ===
Expecco's compound action block execution model has many similarities with [https://en.wikipedia.org/wiki/IEC_61131 IEC-61131-3] (also IEC-1131-3 or EN 61131-3) [https://en.wikipedia.org/wiki/Function_block_diagram Function Block Diagrams]
which is a wellknown standard in programmable logic controller programming.

Input values are read initially, the step execution is controlled by data flow, and output values are written
at the end of the action's execution. However, differences exist in the data types, which are more polymorphic in expecco, and additional pin attributes (such as eg. mailbox pins).

=== Relationship to Petri Nets ===
A Petri Net [http://en.wikipedia.org/wiki/Petri%20net (see Wikipedia)] is a network consisting of places (with possible action processing) and transitions. In a classical petri net, anonymous tokens travel along connections and transitions control the firing (triggering) of following action steps depending on the arrival of tokens at their input side, and passing tokens to their output side.

Expecco has combined the transition and place functionality into a single step item, in order to make the graphical representation more dense (and also for its similarity with UML-2 activity diagrams and other flow based diagrams). However, semantically, they behave the same, and any diagram could be rewritten by using separate items (collecting inputs and passing a tuple of tokens on to the place).

[[Datei:Beispiel.png]]

An expecco step with multiple input pins corresponds to a Petri Net transition with multiple inputs followed by a Petri Net action. Similar to transitions in a Petri Net, the input side of a step can be configured to require either any input or all input values to be present. In expecco, this is called the step's "''trigger condition''" and described in detail in the [[DiagramElements-Step|step documentation]].

"''Higher order Petri Nets''" are Petri Nets containing other Petri Nets as places, which is exactly what a compound block is in expecco. 
"''Coloured Petri Nets''" are Petri Nets where not simple anonymous tokens are passed around, but data objects (or references to them, as in expecco).

Thus, in standard Petri Net notation, expecco's diagrams are therefore "''Higher Order Colored Petri Nets''".

=== Relationship to UML Activity Diagrams ===
Compound actions in expecco are isomorph to UML activity diagrams with a particular predefined set of stereotypes for connections, pins and action steps. These stereotypes are hardcoded in expecco, and define the semantics of action triggering, queueing behaviour of data connections, and the optional parallel execution of steps. The graphical representation is slightly different, to replace the somewhat clumsy <<stereotype>> annotations by different pin images (filled/unfilled etc.). Also, all connections in expecco are object-connections, and all pins receive and generate objects as values.

=== Relationship to Flow Chart Diagrams ===
Activity diagrams can also be seen as a superset of flow chart diagrams. Flow charts can be translated into an activity diagram in which only control flow connections are used. Vice versa: an activity diagram which uses only control flow connections and uses no parallelism can be translated back into a flow chart diagram.

The if-then-else conditional branches of a traditional flow chart diagram correspond to the 2-way if action blocks of the expecco standard library. Loops are implemented by connecting a trigger output pin to a previous step's trigger input pin.

== Editors ==
The activity diagram which defines the behavior of a compound block
is edited in the "[[CompoundBlock Editor-CompoundWorksheet Editor/en|''Network editor'']]", also called "''Diagram Editor''" or "''Network Diagram Editor''".
This editor presents the "''internal view''" of the block.
In contrast, the interface of a compound block (e.g. number and type of pins) can be regarded as its "''external view''" and is presented and defined in the "[[Scheme Editor/en|''Schema Editor'']]".

== See Also ==
[[Tree Elements | Tree Elements]]

[[Block Element]], [[DiagramElements-Step/en|Step]], [[DiagramElements-Connection|Connection]],
[[ElementaryBlock_Element|Elementary Action]],

Back to [[Online Documentation#Tree Elements|Online Documentation]].

[[Category: Tree Elements]]
[[Category: Incomplete]]

CompoundBlock Element

2024-07-16T10:54:17Z

Matilk: /* Einführung */

== Einführung ==
Ein zusammengesetzter Aktionsblock (englisch "''Compound Action''") beschreibt das Verhalten einer [[Block_Element|Aktion]] graphisch als Aktivitätsdiagramm. Diese Diagramme sind vergleichbar mit den [[#Relation_zu_UML_Aktivit.C3.A4tsdiagrammen|Datenflussdiagrammen]] wie in UML2.0 definiert. Sie haben außerdem viele Eigenschaften gemein mit [[#Relation_zu_Petrinetzen|Petrinetzen]]. Das Diagramm besteht aus Unteraktionen, welche als [[DiagramElements-Step|''Schritte'']] bezeichnet werden.

Die Ausführung wird durch eine Kombination von Daten- und Kontrollflüssen gesteuert, die durch Verbindungen zwischen den Schritten übertragen werden:
* Als Datenfluss wird die Übergabe von Werten (Resultate, Messwerte, Objekte, Dokumente etc.) von einem Schritt zum nächsten bezeichnet. Ein Datenfluss läuft über Verbindungen vom [[DiagramElements-Pin#Output_Pin|Ausgangspin]] (Pin = "Stecker/Sockel") eines Schritts zum [[DiagramElements-Pin#Input_Pin|Eingangspin]] eines anderen.
* Kontrollflüsse sind Informationen zum Endestatus eines Schrittes, die verwendet werden können, um die Aktion eines nächsten Schritts zu starten. Sie laufen über Verbindungen vom [[DiagramElements-Pin#Enable_Output_Pin|Trigger-Ausgang]] eines Schrittes zum [[DiagramElements-Pin#Enable_Input_Pin|Trigger-Eingang]] eines anderen.
Beide können die Ausführung eines Folgeschritts auslösen.

== Diagrammelemente ==
Als "''Diagrammelemente''" werden die Bestandteile eines Aktivitätsdiagramms bezeichnet. Sie definieren das Verhalten des [[Compound Block|Zusammengesetzten Aktionsblocks]] und werden im [[Network Editor|Netzwerkeditor]] bearbeitet.

== Einführendes Beispiel eines Aktivitätsdiagramms ==

Das folgende Beispiel erläutert die Hauptkomponenten eines Aktivitätsdiagramms:

[[Bild:diagram-elements.jpg|760px|Ein Aktivitätsdiagramm]]

Das Diagramm beschreibt den Test einer E-Mail-Übertragung. Zuerst erzeugt der Schritt "Create Unique ID" eine sog. UUID und stellt diese an seinem Ausgangspin zur Verfügung. Diese UUID wird später gebraucht, um den korrekten Empfang der E-Mail zu verifizieren. Die UUID wird vom Schritt "Send E-Mail [SMTP]" empfangen, welcher eine E-Mail mittels dem SMTP Protokoll verschickt, und die UUID als Subject verwendet. Als nächstes sorgt der "Time [Delay]" Schritt für eine Verzögerung von 5 Sekunden (in denen die E-Mail übermittelt wird). Am Ende prüft der Schritt "Check for incoming Mail" ob eine E-Mail mit dem angegebenen Subject angekommen ist, wozu obige UUID gebraucht wird.
Der Test wird einen Fehler melden, falls eine solche E-Mail nicht gefunden wird.

Beachten Sie bitte, dass die graphische Darstellung des Diagramms im Grunde der UML-Notation entspricht. Allerdings werden um die Lesbarkeit zu erhöhen, und um wichtige Aspekte der Ausführung hervorzuheben einige Element etwas anders bzw. zusätzlich annotiert dargestellt. Insbesondere werden die Stereotypen der Pins durch unterschiedliche Pin-Darstellungen hervorgehoben, anstatt durch textuelle "<<stereotype>>"-labels, wie in UML.


=== [[DiagramElements-Step|Schritt]] (7) ===

Als "''Schritt''" wird eine Aktion (Aktionsbaustein) bezeichnet, welcher in ein Diagramm platziert wurde. Diese Aktion kann ihrerseits entweder ein sog. [[Elementary Block|Elementablock]] sein (wie z.B. "Create Unique ID"), welche ihre Aktion durch eine textuellen Programmcode definiert, oder wieder ein [[Compound Block|zusammengesetzter Block]] (wie z.B. "Check Incoming Mail"), welcher durch ein eigenes Aktivitätsdiagramm definiert wurde. Für das Diagrammnetzwerk in welches der Aktionsblock platziert wurde ist kein Unterschied im Verhalten sichtbar: ein Diagramm, welches einen Aktionsblock beinhaltet (d.h. einen Schritt enthält) sieht kein unterschiedliches Verhalten in Abhängigkeit der effektiven Realisierung seiner Schritte. Tatsächlich gibt es auch keine Unterschiede in der graphischen Darstellung, so dass es auch für den Entwickler eines zusammengesetzten Blocks keinen Unterschied macht (er muss nicht wissen, wie die Interna einer Aktion aufgebaut sind). Alle Schritte werden gleichermaßen durch die Verfügbarkeit von Eingangsdaten gestartet, führen ihre Bearbeitung durch, und liefern ihre Resultate an den Ausgangspins. Details zum Verhalten von Schritten sind in einem [[DiagramElements-Step | separaten Document]] nachzulesen.

=== Autostart (1) ===

Ein Schritt mit der Autostart Option wird automatisch gestartet, sobald das umgebende Netzwerk ausgeführt wird. Schritte ohne Autostart-Option werden lediglich ausgeführt, sobald Daten an den Eingangspins des Schrittes erscheinen. Autostart wird insbesondere für Schritte benötigt, welche keine Eingangspins haben, oder welche nicht durch einen Kontrollfluss gestartet werden. Auch Schritte, deren Eingang lediglich konstante Parameter darstellen müssen so gestartet werden. Im obigen Diagramm trifft dies für den linken "Create Unique ID" Schritt zu.

Im Diagrammeditor werden Schritte mit Autostart mit einem speziellen Icon am linken oberen Rand dargestellt; falls Sie die Standard-UML-Notation bevorzugen, können Sie auch einen START-Block aus der Bibliothek verwenden und dessen Trigger-Ausgangspin mit dem zuerst auszuführenden Schritt verbinden.

=== [[DiagramElements-Pin|Pin]] (3, 6, 9) ===

[[DiagramElements-Pin|Pins]] dienen zur Weitergabe von Daten und Triggerinformationen zwischen Schritten. Diese Pins können entweder [[DiagramElements-Pin#Output Pin|Ausgangespins]] (3) sein, um Daten zu senden, oder [[DiagramElements-Pin#Input Pin|Eingangspins]] (9), um Daten zu empfangen. Weitere Pins dienen dazu besondere Situationen wie z.B. [[DiagramElements-Pin#Exception Output Pin|Ausnahmebehandlung]] zu melden. Im obigen Diagramm, ist der Exception-Ausgang des "Check Incoming Mail" Schritts mit dem Trigger-Eingang des "FAIL" Schrittes verbunden.
Kontrollflusspins (Trigger und Status) sind vertikal angeordnet, wohingegen Datenflüsse als horizontal Pins dargestellt werden.
Eingangspins sind immer oben oder links, Ausgangspins immer unten oder rechts angeordnet.
Pins werden entsprechend ihrem Verhalten leicht unterschiedlich dargestellt; insbesondere auf das Puffer- und Triggerverhalten wird durch ausgefüllt vs. nicht gefüllt hingewiesen, da diese wichtig sind für die Ausführung. Pins werden in einem [[DiagramElements-Pin | separaten Dokument]] detailliert beschrieben.

=== [[DiagramElements-Connection|Verbindung]] (4,8) ===

Verbindungen dienen zum Weiterleiten von Daten oder Kontrollinformationen zu einem oder mehreren Eingangspins (eines oder mehrerer Folgeschritte).
Im Sinne von UML sind alle Verbindungen in expecco immer "Objektverbindungen".

==== Datenflussverbindung (4) ====

Diese befördern Daten (-Objekte) von einem Ausgangspin zu einem Eingangspins eines Folgeschritts. Im obigen Beispiel sendet der erste Schritt die erzeugte UUID an zwei weitere Schritte.
Datenflusspins sind immer links und rechts angeordnet (horizontale Pins).

==== Kontrollflussverbindung (8) ====

Diese dienen dazu, die Ausführung unabhängig von Daten (aber abhängig von der Ausführung eines Schrittes) zu kontrollieren. Im Beispiel werden die Schritte rechts im Bild sequentiell ausgeführt, wozu der Triggerausgang eines Schrittes mit dem Triggereingang eines Folgeschrittes verbunden wurde.
Kontrollflusspins sind immer oben und unten angeordnet (vertikale Pins).

=== [[DiagramElements-Freeze Value|Freeze Value (Vorbelegungswert)]] (6) ===

Eingangswerte eines Pins können mit einem statischen Wert vorbelegt werden (Konstante).
Im Beispiel sind der Text der E-Mail, die E-Mail-Adresse, die Wartezeit und auch die Fehlermeldung auf diese Weise "eingefroren".
Ein vorbelegter Pin sollte typischerweise als nicht-triggernd und nicht-konsumierend (sogenannter "''Parameterpin''") konfiguriert werden, wofür es einen besonderen Menüeintrag gibt (außerdem werden beim "''Einfrieren''" die Pins vom Editor automatisch als solche umdefiniert). Details zum Triggerverhalten und zum Konsumieren von Eingangswerten finden sie im Dokument: [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Freeze Value|Vorbelegung aus Umgebungsvariablen]] (5) ===

Eingangswerte eines Pins können ebenfalls aus einer Variable gelesen werden. Diese Variablen werden in einer sogenannten "''Variablenumgebung''" bereit gestellt, welche im umgebenden zusammengesetzten Bausteinen oder der [[TestSuite Element|Testsuite]] definiert werden. Im obigen Beispiel werden der Name des E-Mail-Kontos sowie der E-Mail-Serverhost aus solchen Variablen gelesen (und entsprechende Einträge in der Variablenumgebung der Testsuite vorausgesetzt). Wie auch reguläre Vorbelegungen sollte der Pin als nicht-triggernd und nicht-konsumierend definiert werden (i.e. "''Parameterpin''"). Lesen Sie dazu ebenfalls das Kapitel [[DiagramElements-Pin#Input Pin|"''Verhalten von Eingangspins''"]].

=== [[DiagramElements-Annotation|Annotation]] (2) ===

Annotationen dienen dazu, Kommentare oder Zusatzinformationen für Entwickler oder Tester im Diagramm mit abzulegen. Möglich sind sowohl textuelle Annotation, als auch importierte Grafiken (Bilder im GIF-, JPEG- oder PNG-Format). Sie können auch dazu genutzt werden, um wichtige Teile des Diagramms farblich hervorzuheben, indem Sie eine leere Textannotation mit einer Hintergrundfarbe unter Teile ihres Diagramms legen.

=== [[DiagramElements-Probe|Messfühler]] ===

Messfühler (im obigen Diagramm nicht gezeigt) dienen dazu Pin-Werte aufzuzeichnen und/oder zu validieren. Messfühler bieten einen komfortablen und lesbaren Mechanismus um Werte auf ihre Gültigkeit zu prüfen.

== Relation zu IEC1131 ==
Expeccos Aktivitätsdiagramme ähneln stark den Funktionblöcken der IEC1131-3 FBD Sprache (siehe ua. [https://en.wikipedia.org/wiki/Function_block_diagram Wikipedia]).
Sowohl die grafische Darstellung als auch das Ausführungsverhalten sind vergleichbar. Ingenieure mit einem SPS Hintergrund werden keine Probleme haben, Expeccos Aktionsdefinitionen und zusammengesetzte Aktionen zu verstehen.

== Relation zu Petrinetzen ==
A Petri Net [http://en.wikipedia.org/wiki/Petri_net| ->Wikipedia] is a network consisting of places (with possible action processing) and transitions. In a classical petri net, anonymous tokens travel along connections and transitions control the firing (triggering) of following action steps depending on the arrival of tokens at their input side, and passing tokens to their output side. Expecco has combined the transition and place functionality into a single step item, in order to make the graphical representation more dense (and also for its similarity with UML-2 activity diagrams and other flow based diagrams). However, semantically, they behave the same, and any diagram could be rewritten by using separate items (collecting inputs and passing a tuple of tokens on to the place).

[[Datei:Beispiel.png]]

An expecco step with multiple input pins corresponds to a Petri Net transition with multiple inputs followed by a Petri Net action. Similar to transitions in a Petri Net, the input side of a step can be configured to require either any input or all input values to be present. In expecco, this is called the step's "''trigger condition''" and described in detail in the [[DiagramElements-Step|step documentation]].

"''Higher order Petri Nets''" are Petri Nets containing other Petri Nets as places, which is exactly what a compound block is in expecco.
"''Coloured Petri Nets''" are Petri Nets where not simple anonymous tokens are passed around, but data objects (or references to them, as in expecco).

Thus, in standard Petri Net notation, expecco's diagrams are therefore "''higher ordered colored Petri Nets''".

== Relation zu UML Aktivitätsdiagrammen ==
--- to be written

== Relation zu Flussdiagrammen ==
Aktivitätsdiagramme können als Obermenge von Flussdiagrammen betrachtet werden. Dazu werden die Aktionen lediglich über Kontrollflussverbindungen (Trigger-in/Trigger-out) verbunden (Daten werden hierbei über Variablen ausgetauscht).

Die Wenn-Dann bedingte Verzeigung eines Flussdiagramms entspricht einem 2-Wege-If Aktionsblock (aus der Standardbibliothek). Schleifen werden durch Verbindungen der Trigger-out mit einem Trigger-in eines vorhergehenden Schrittes definiert.

== Editoren ==
The activity diagram which defines the behavior of a compound block
is edited in the [[CompoundBlock Editor-CompoundWorksheet Editor/en|''network editor'']], also called "''diagram editor''" or "''network diagram editor''".
This editor presents the "internal view" of the block.
In contrast, the interface of an compound block (e.g. number and type of pins) can be regarded as its "external view" and is presented and defined in the [[Scheme Editor/en|''schema editor'']].

[[Category: Tree Elements]]
[[Category: Incomplete]]

Mobile Testing Plugin/en

2024-07-11T09:37:37Z

Matilk: /* Windows */ new supplement

[[Mobile_Testing_Plugin|Deutsche Version]] | '''English Version'''

= Introduction =
The ''Mobile Testing Plugin'' adds mechanisms to test and automate Android and iOS devices. This includes both real and emulated devices - it does not matter whether real mobile devices or emulated devices are used. The plugin can (and usually is) used in conjunction with the [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]], which supports the creation of tests. It can also be used to record test procedures.

[http://appium.io/ Appium] is used to connect to the devices. Appium is a free open source framework for testing and automating mobile applications.

We recommend to go through the [[Mobile_Testing_Tutorial/en|Tutorial]] to familiarize yourself with the Mobile Plugin. This tutorial leads step by step through the creation of a test case using an example and explains the necessary basics.

= Installation and Setup =
To use the ''Mobile Testing Plugin'', you must have installed expecco together with the corresponding plugin, and you need the appropriate licenses. expecco communicates with the mobile devices via an Appium server, which either runs on the same computer as expecco, or on a second computer. This must be accessible for expecco.

== Installation Overview ==
'''Computer running expecco:'''
* Java JDK version 8, 9, 10 or 11
'''Computer connected to Android devices :'''
* Appium Server, you can install it via the Mobile Testing Supplement (see below), of which we regularly provide a new version
* Android SDK, you can also get it with the Mobile Testing Supplement
* Java JDK version 8, 9, 10 or 11
'''Computer connected to iOS devices*:'''
* Appium Server, you can install it via the Mobile Testing Supplement for MacOS (see below), of which we regularly provide a new version
* Xcode in a version that supports the iOS version used, available from the Apple App Store
* Java JDK version 8, 9, 10 or 11
* Apple Developer Certificate incl. matching private key (to sign the WebDriverAgent)
* Provisioning Profile for the mobile devices to be used

* Please note that due to the requirements (no connection to non-Apple devices available) iOS devices can only be controlled from a Mac.

Depending on the setup, the above-mentioned computers can also be the same device. expecco can either connect to a remote Appium Server and mobile devices connected to it via the network, or start an Appium Server locally itself and use it with local mobile devices. However, some of expecco's functions that make it easier to create test cases are only available if the mobile devices are connected to the same computer on which expecco is running. A possible setup may therefore look like the following figure:

[[Datei:MobileTestingAufbau.png | 400px]]

The following explains how to install Appium and other necessary applications for Windows and Mac OS.

== Windows ==
The easiest way is to install everything from our Mobile Testing Supplement. However, newer versions do not contain a JDK anymore due to a change in Oracle's license terms, so you have to install it additionally. Of course, you are free to install Appium directly to use the version you want. However, to then be able to start an Appium server with expecco, a suitable batch file must be available and specified in the [[Mobile_Testing_Plugin/en#Plugin_Configuration|settings]]. However, connections can also be established to other running Appium servers.
*'''expecco 24.1''': [https://download.exept.de/transfer/h-expecco-24.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.3]
:Same versions as in the predecessor, but with updated chromedriver versions
*expecco 23.2: [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Same versions as in the predecessor, but with updated chromedriver versions
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Same versions as in the predecessor, but the installer now allows to add Appium to the Autostart.
*expecco 22.2 and 22.1: [https://download.exept.de/transfer/h-expecco-22.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 from platform-tools 33.0.2
:''* We added the capability'' startChromedriverTimeout ''to Appium, to get a timeout earlier, if Chromedriver cannot be initialized. (see [[#startChromedriverTimeout|Problems and Solutions]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Contains Appium version 1.22.0, Node still is version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Only minor changes compared to the previous version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Compared to the previous version, Appium was updated to version 1.16.0-rc.1 and node 12 is used.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:This installs Appium in the version 1.12.0 and now additionally contains build-tools in the version 28.0.3 in the android-sdk. Apart from this, it is the same as the previous version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:This installs Appium in the version 1.8.1. In addition, an installation of ''Android Debug Bridge'' and ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) is offered. This covers drivers for a broad range of Android devices, and you won't have to install an individual driver for each device. A '''JDK is not contained anymore (due to a change in Oracle's license terms)''', you have to download it on your own, e.g. from [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: same procedure as for expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:This installs a Java JDK Version 8, android-sdk and Appium Version 1.6.4. The supplement also offers a universal adb driver ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]). This driver supports a wide range of Android Devise, and avoids the need to search for individual device-specific drivers.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:It installs a Java JDK version 8, android-sdk and Appium version 1.4.16. During the installation the graphical user interface of Appium is started, you can close this window immediately. The supplement also offers a universal adb driver (ClockworkMod). This combines drivers for a wide range of Android devices so that you do not have to search for and install a separate driver for each device.

If expecco has to use mobile devices that are connected to another computer, you have to start an Appium server there. You can do this by using the file <code>appium_standalone.cmd</code>. The server is then started on default port 4723. If you want to use a different port number, start the server with

appium_standalone.cmd -p <portnummer>

The server is ready, as soon as the line
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
is displayed, where you can read the used port number at the end.

If your Android device is connected to a remote machine,
you may want to see the live screen locally using a tool like
[https://github.com/Genymobile/scrcpy scrcpy].

When Appium is started for the first time – either standalone or by expecco – it may happen that the Windows firewall blocks access to the node server. Allow the access or Appium cannot be started.

== Mac OS ==
Note: the following can be ignored if you do not plan to test iOS (iPhone) devices. The Mac setup is not needed for Android devices.

=== Xcode ===
Automation with iOS devices needs [https://developer.apple.com/xcode/ Xcode]. You can install it from the App Store. Please make sure that the version matches the tested iOS versions.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
This table is only a simplified overview, better see [https://xcodereleases.com/ Xcode releases] or [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode versions] for the exact versions. For new iOS minor versions, there is usually also a new release of Xcode, e.g. for iOS 10.2 you need at least Xcode 8.2, for iOS 10.3 at least Xcode 8.3, etc. So if you are upgrading to a newer iOS version, you will usually need a newer Xcode version as well. Newer versions of Xcode may not run on older operating systems, which in turn may require an operating system upgrade. If you also want to test older iOS versions, it can be useful to install the corresponding Xcode versions in parallel.

=== Appium ===
You can install Appium either as command-line tool or use it with [https://github.com/appium/appium-desktop Appium Desktop], which provides a GUI to start the server. Meanwhile there is also Appium 2.0, which is not tested with expecco yet and therefore not recommended to use.

==== Appium Desktop ====
Download the newest version of [https://github.com/appium/appium-desktop/releases/ Appium Desktop]. For the Mac, it is best to take the dmg file and install it to the applications. When starting ''Appium Server GUI'' you will probably get the error message, that it is not possible for security reasons. In this case, open the context menu of the app file (right click or Ctrl + click) and choose ''Open'' there. Then confirm that you really want to open the application. From now on you can open the application normally.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Since Xcode 14 there are problems with signing the WebDriverAgent, which Appium loads on the device for the automation. This means that no connection is possible with version 1.22.3-4 of Appium Desktop. In newer versions of WebDriverAgent, this problem is solved, but currently there is no version of Appium Desktop using such a new version (as of November 2022). However, you can manually download a new version (e.g. 4.10.2) and replace the files in Appium. To do this, download one of the two archive files (zip or tar.gz) containing the source code from the [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent download page]. Then open and extract this file. Copy the contents of the folder ''WebDriverAgent-4.10.2' to

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

If you navigate there by Finder, make a context click (right click or Ctrl + click) on the application and choose ''Show Package Contents'' from the menu. Replace all files that are already present with the same name.

==== Install Appium using npm ====
You can install Appium using npm (Node Package Manager) as well. To do this, you have to install node/npm first. This can be done using [https://github.com/nvm-sh/nvm nvm] (Node Version Manager), which you can get on Github. If the following installation instructions should not work for you, you will find detailed information in the [https://github.com/nvm-sh/nvm#readme Readme] there.

Open a Terminal window. Then clone the Github repository of nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
and load it
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Then execute
command -v nvm
to see if it works. It should print ''nvm''. If there is no response, execute
touch ~/.zshrc
and try again.

Now you can install node with the following command.
nvm install 16.15.1
As there are problems installing Appium using the newest version of node, we recommend this version.

After node is installed, you can use it to install Appium:
npm install -g appium

The Appium server now simply can be started with the command
appium
The output will then be written directly to the terminal.

This version also has problems with signing the WebDriverAgent, like explained in [[#Appium_Desktop | Appium Desktop]]. Therefore download a newer version of WebDriverAgent in this case as well and replace the old files. You will find them at
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
We provide older versions of Appium via the Mobile Testing Supplement for Mac OS, with which you can easily install it:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.2)]
:Contains Appium version 1.18.3 and uses node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.0)]
:Only a few changes compared to the previous version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.98)]
:Appium is updated to version 1.16.0-rc.1 and node 12 is used.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.96)]
:This version contains Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.94)]
:This version contains Appium 1.8.0.

* expecco 2.11:[http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.0.94)]
:This version contains Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement for Mac OS]
:Diese Version entält Appium 1.4.16.

After you have downloaded the supplement, you can move it to a directory of your choice (e.g. your home directory) and unpack it there. A suitable command in a shell could look like this, adjust the version number accordingly:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

If your default Xcode installation is the one you want to use, you can start Appium directly from the file in the ''bin'' directory with the appropriate version number:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

If you want to use another Xcode than the one configured as default, you have to tell Appium the corresponding path by using the environment variable ''DEVELOPER_DIR''. For example, if you have installed Xcode in ''/Applications/Xcode-11.3.app'', you can start Appium this way:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

To find out what is set as the default Xcode installation on your system, use this command:

xcode-select -p

If Appium cannot find your Xcode installation, a message like this appears:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
In such a case, restart Appium by specifying a valid ''DEVELOPER_DIR''.

==== Signing WebDriverAgent ====
For automation, Appium installs an App called WebDriverAgent on the device and therefore has to be able to sign it. You need an Apple account and a respective certificate for this. For evaluation you can use a free account. This has the disadvantage that created profiles are only valid for one week and must be recreated afterwards. Also be careful when sharing the account, as certificates may be revoked or invalidated by automatic generation. As a result, apps that have already been signed can no longer be used.

If you already have a respective certificate and its associated private key in your keychain on the Mac, you can have the WebDriverAgent automatically signed. If not, it is recommended to set and manage the signing using Xcode.

First, connect the device you want to use to your Mac via USB. Make sure both the Mac and the device are in the same network or there will be problems when connection with Appium. Start Xcode and open ''Preferences''. Go to the Accounts page and create an entry with your account. You can then click on ''Manage Certificates...'' to see the certificates that belong to that account. To run tests, you need an iOS Development Certificate and the associated private key. If you do not already have one, create one. If you already have one, but it is not in your keychain (indicated by "Not in Keychain"), you can import it. You can do that by the [https://support.apple.com/en-us/guide/keychain-access/welcome/mac keychain access] on your Mac, if you have exported it previously from the keychain, where it is stored. The certificate with the associated key should be in the keychain ''Login''. It can be exported from there as PKCS#12 file (typical ending .p12). To import a certificate into your keychain, select the option ''Import objects'' from the ''File'' menu. If you don't know where the certificate is stored, you can also revoke it in Xcode and recreate it in your keychain. However, only do this if you know that the old certificate is no longer in use because it can no longer be used afterwards. Now the keychain should contain an iOS development certificate.


Now open the WebDriverAgent project in Xcode. If you have installed the Mobile Testing Supplement, you will find it in this directory at
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
If you have installed Appium Desktop, you will find it at
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''

You can use the Finder to navigate to the Xcode project file and open it by double clicking. Note, that you have to perform a context click (right click or Ctrl + click) on the Appium Server GUI app and select ''Show Package Contents'' in the menu, to get to its subdirectory.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Select ''WebDriverAgentLib'' and the page ''Signing & Capabilities''. In the section ''Signing'' set the option ''Automatically manage signing'' and then select a team. Now switch to ''WebDriverAgentRunner'' and do the same there.

By setting the team, the errors showing up for WebDriverAgentRunner should disappear. If Xcode should not be able to create a Provisioning Profile matching the Bundle ID ''com.facebook.WebDriverAgentRunner'', you can edit the latter so that it fits your certificate. After that you can quit Xcode or you can, like explained further below, directly start the build in Xcode, so the project will be already built when Appium wants to use it.

If you now connect to your device from expecco, the WebDriverAgent will be installed and started on it and then switch to the app to be tested. You may still have to trust the execution of the WebDriverAgent on the device. It maybe a sign that you have to do this, if the app WebDriverAgent first appears on the device and tries to start, but then is uninstalled again. To trust the execution, open the settings during the connection setup on the device and then the entry ''Device management'' under ''General''. This entry is only visible if a developer app is installed on the device. You may therefore have to wait until the WebDriverAgent is installed before the entry appears. Select the entry of your Apple account and trust it. Since the WebDriverAgent will be uninstalled again if the start did not work, you have to do this during the connection setup. If this is too hectic for you, you can also execute the following code:

xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

or
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

This installs the WebDriverAgent on the device without deleting it again.

If there are problems while installing the WebDriverAgent, you can also try and start the build in Xcode. Make sure the right target ''WebDriverAgent'' is selected. Error messages in Xcode might indicate easier what the problem is about. Sometimes it even helps to try for a second time, if it took too long for the first time and got aborted. It may occur, that you are asked several times during the build to enter the password for the keychain.

[[Datei:WebDriverAgentCodesign.png]]

Read also the documentation of Appium on [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Setting up tests with iOS devices]. Refer to the [https://support.apple.com/en-us/HT204460 Apple documentation] for details on installing and trusting of apps.

Once the WebDriverAgent is installed on the device, it will be reused for later connections und connecting should work faster. The signed version is then already on your Mac as well and doesn't have to be built again. This should speed up the connect with other devices as well. If you know, that the connect has to build and sign the WebDriverAgent first, it is advisable to set the capability ''wdaLaunchTimeout''. This timeout specifies how long Appium waits for the WebDriverAgents to start up on the device and is per default set to 60000 ms. Building often takes a little longer than one minute, so the connect attempt will be canceled. A value of 120000 will be more reliable here.

== Plugin Configuration ==
Before you start, please check the settings of the Mobile Testing Plugin and adjust them if necessary. Select the menu item "''Extras''" → "''Settings''" → "''Extensions''" → "''Mobile Testing''" (see fig.). By default, these paths are found automatically (1). To adjust a path manually, deactivate the corresponding check mark at the right. You'll see a drop-down list with some paths to choose from. If an entered path is wrong or cannot be found, the field is marked red and a message appears. Make sure that all paths are specified correctly.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Plugin Configuration]]

*'''appium''': Enter the path to the executable file with which Appium can be started in the command line. Under Windows this file will usually be called "<code>appium.cmd</code>". This path is used when expecco starts an Appium server.
*'''node''': Enter the path to the executable that starts Node (also called (also called "Node.js"). This path is passed to Appium when a server is started so that Appium can find it independently of the PATH variable. Under Windows this file is usually called "<code>node.exe</code>".
*'''JAVA_HOME''': Enter the path to a JDK (Java Development Kit)here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable. To specify which Java should be used by expecco, set this path in the Java Bridge settings.
*'''ANDROID_HOME''': Enter the path to an Android SDK here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable.
*'''adb''': The path to the adb command. Under Windows the file is called "<code>adb.exe</code>". This file is used by expecco, for example, to get the list of connected devices. This path should be selected automatically, if the command is found in the ANDROID_HOME directory. This is also used by Appium. If expecco and Appium use different versions of adb, conflicts may occur.
*'''android.bat''': This file is only needed to start the AVD and the SDK Manager, which deal with phone emulators. The file in the ANDROID_HOME directory will be selected automatically, if present there.
*'''aapt''': The path to the "aapt" command here. Under Windows this file is called "<code>aapt.exe</code>". expecco uses "aapt" only in the connection editor to read the package and activities of an "apk" file. The file in the ANDROID_HOME directory will be selected automatically, if present there.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | JDK Configuration]]

Starting with expecco 2.11, there is an additional field called ''Team ID''. If you run iOS tests, enter the Team ID of your certificate here. This is used for every iOS connection, unless you change the value in the connection settings in individual cases. For information on how to obtain the team ID, please refer to the section on [[#Signing| signing]] for installations on Mac OS. With expecco 2.10 and older, you can only enter the Team ID as capability for each connection setting separately. However, you must use the [[#Extended_View|extended view]] to do this. Enter the capability ''xcodeOrgId'' here and set the Team ID of the certificate as value.

The server address setting at the bottom of the page refers to the behavior of the connection editor. It checks at the end whether the server address ends in ''/wd/hub'' as this is the usual form. If not, a dialog asks how to react. The defined behavior can be viewed and changed here.

Also switch to the entry ''Java Bridge'' (see figure). Here you have to specify the path to your Java installation, which is used by expecco. Enter a JDK here. If you want to use the one from the Mobile Testing Supplement under Windows, the path is
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
You can also use the system settings.

== Prepare Android Device ==
If you connect an Android device under Windows, you may still need an adb driver for the device. You can usually find a suitable driver on the manufacturer's website. If you have installed the universal driver from the Mobile Testing Supplement, everything should already work for most devices. In some cases, Windows will automatically try to install a driver when you connect the device for the first time. 
'''Attention''': Before you can control a mobile device with the Appium plugin, you have to allow this debugging!

For Android devices, you can find this option in the settings under ''[https://developer.android.com/studio/debug/dev-options Developer Options]'' called ''USB-Debugging''. If the developer options are not displayed, you can unlock them by tapping Build Number seven times in About the Phone.

Also enable the ''Stay awake'' feature to prevent the device from turning off the screen during test creation or execution.

For security reasons, USB debugging must be allowed for each computer individually. When connecting the device to the PC via USB, you must agree to the connection on the device. If you haven't done this for your computer yet, but no corresponding dialog appears on the device, it may help to unplug and reconnect the device. This can happen especially if you have installed the ADB driver while the device was already connected via USB. If this doesn't help either, open the notifications by dragging them from the top of the screen. There you will find the USB connection and you can open the options. Select another type of connection; usually MTP or PTP should work.

You can also test on an emulator. It does not need to be prepared separately, as it is already designed for USB debugging. It is even possible to start an emulator at the beginning of the test.

To check if a device you have connected to your computer can be used, open the [[#Connection_Editor|connection editor]]. The device should be displayed there.

=== Connection via WLAN ===
It is possible to connect to Android devices via Wireless LAN. For devices using Android 11 or newer, this can be done wirelessly, else you have to connect initially via USB. Since expecco 22.1, WiFi connections can be established using the [[Mobile_Testing_Plugin/en#Connection_Editor|Connection Editor]]. It is also possible to do this using a command window.
==== Wireless Connect (Android 11) ====
In the developer options of your device, enable wireless debugging and open its options. You initially have to pair your machine with the device. To do this, choose "''Pair device with pairing code''" to get a pairing code and an IP address with port. Then open a command window (terminal window) on your machine and enter:
<nowiki>adb pair <Device IP Address>:<Pairing Port></nowiki>
where <tt><Device IP Address>:<Pairing Port></tt> is the IP address and port as shown on the device. After that, you will be asked for the pairing code. If everything went right, the popup on the device should have closed and your machine is added to the list of paired devices. Then enter at the command window:
<nowiki>adb connect <Device IP Address>:<Debugging Port></nowiki>
The IP address is the same as for pairing, but the port is different. Both are shown as IP address & Port on the device. The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted. Restarting the device often disables wireless debugging and the used port is changed. The pairing, however, is permanent and has not to be done again the next time you connect.
==== Start via USB ====
First, connect your device via USB. Then open a command window (terminal window) and enter:
<nowiki>adb tcpip 5555</nowiki>
The device listens for a TCP/IP connection on port 5555. If you have several devices connected or emulators running, you have to specify which device you mean. Enter in this case:
<nowiki>adb devices -l</nowiki>
to get a list of all devices, where the first column gives the device's ID.
Then, enter:
<nowiki>adb -s <deviceID> tcpip 5555</nowiki>
with the device identification of the desired device. You can now disconnect the USB connection. Now you have to find out the IP address of your device. You can usually find it somewhere in the device's settings, for example in the Status or WLAN settings of the phone. Then type in:
<nowiki>adb connect <IP address of device></nowiki>
The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> again or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted.

== Preparing an iOS-Device and App ==
Control of iOS devices is only possible via a Mac. Please also read the section [[#Mac_OS|Installation under Mac OS]].

Before you can control a mobile device with the Mobile Testing Plugin, you must allow debugging for iOS devices with iOS 8 or higher. Activate the option "''Enable UI Automation''" under the "''Developer''" menu in the device settings. If you cannot find the "''Developer''" entry in the settings, proceed as follows: Connect the device to the Mac via USB. If necessary, you must still agree to the connection on the device. Start Xcode and then select "''Devices''" from the menu bar at the top of the screen in the "''Window''" menu. A window opens in which a list of the connected devices is displayed. Select your device there. Then the entry "''Developer''" should appear in the settings on the device. You may have to exit the settings and restart.

[[Datei:Alert.png | thumb | 270px | Alert unter iOS]]
It is not possible to establish a connection to the device as long as it shows certain alerts. Such an alert may appear if FaceTime is activated (by displaying a message about SMS charges as shown in the screenshot). Be sure to configure the device so that it does not show such alerts when idle.

=== expecco 2.11 and later ===
You can test any app which is executable or already installed on the device used. If the app is available as a development build, the UDID of the device must be stored in the app. In any case, the WebDriverAgent must be signed for the device. Please read the section about [[#Signing|signing]] under Mac OS.

If you want to use the Home button in a test, you must activate "AssistiveTouch" on the device. You will find this option in the settings under "''General''" > "''Operating Help''" > "''AssistiveTouch''". Then place the menu in the middle of the upper edge of the screen. You can then record pressing the Home button with the corresponding menu entry in the recorder or use the "''Press Home Button''" block directly.

=== expecco 2.10 ===
The app you want to use must be available as a development build. The UDID of the device must also be stored in the app.

=== Sign the development build ===
A development build of an app is only allowed for a limited number of devices and cannot be started on other devices. However, it is possible to exchange the certificate and the usable devices in a development build.

* Evaluation with demo app of eXept:
:We will be happy to provide you with a demo app which is available as a development build and which we can sign for your device. Please send the UDID of your device to your eXept contact person. How to determine the UDID of your device is described in the following section.

* Using your own app for your test device:
:If you receive a development build (IPA file) from the app developers that is approved for your test device, you can use it directly. To do this, you must tell the developers the UDID of your device so they can enter it. '''You can use Xcode to read the UDID of a device'''. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window opens in which a list of the connected devices is displayed. Select your device and search for the ''Identifier'' entry in Properties. The UDID is a 40-digit hexadecimal number.

* Externally developed app for your test device:
:You can also re-sign apps to make them run on other devices. However, this process is complicated and requires access to an Apple Developer account. A documentation on the procedure is currently in preparation.

:For the evaluation we will gladly support you with the re-signing of your app..


For more information about using iOS devices, see also the
[http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Appium documentation].

=== Native iOS-Apps ===
You can also use apps that are already natively present on the device. To do this, you must know their bundle ID and then enter it in the connection settings. Here is a small selection of common apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

You can find further Bundle-IDs [https://github.com/joeblau/apple-bundle-identifiers here].

= Examples =
In the demo test suites for expecco you will also find examples for tests with the Mobile Testing Plugin. To do this, select the option "''Example from File''" on the start screen and open the folder named "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
The test suite contains two simple test plans: "''Simple CalculatorTest''" and "''Complex Calculator and Messaging Test''". Both tests use an Android emulator, which you must start before starting. The apps used in the test are part of the basic equipment of the emulator and therefore no longer need to be installed. Since the apps may differ under every Android version, it is important that your emulator runs under Android 6.0. In addition, the language must be set to English.

; Simple CalculatorTest
: This test connects to the calculator and enters the formula ''2+3''. The result of the calculator is compared with the expected value ''5''.

; Complex Calculator and Messaging Test
: This test connects to the calculator and then opens the message service. There it waits for an incoming message from the number ''15555215556'', in which a formula to be calculated is sent. The message is generated before via a socket at the emulator. When the message arrives, it is opened by the test and its contents are read. Then the calculator is opened again, the received formula is entered and the result is read. The test then switches back to the message service and sends the result as an answer.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
These are part of the tutorial for the Mobile Testing Plugin. The included test case is incomplete and will be added during the tutorial. Please read the section [[#Tutorial|Tutorial]].

= Tutorial =
There is a tutorial describing the basic procedure for creating tests with the Mobile Testing Plugin. It is based on a supplied example consisting of a simple app and an expecco test suite.

You find it on the page [[Mobile_Testing_Tutorial/en|Mobile Testing Tutorial]] in two versions for Android and iOS devices.
*  [[Mobile_Testing_Tutorial/en#First_steps_with_Android|First steps with Android]]
*  [[Mobile_Testing_Tutorial/en#First_steps_with_iOS|First steps with iOS]]

= Dialogs of the Mobile Testing Plugin =
== Connection Editor ==
You can use the Connection Editor to quickly define, change, or establish connections. Depending on the task, the dialog has small differences and is opened differently:
*If you want to establish a connection, access the dialog in the GUI browser by clicking on ''Connect'' and then selecting ''Mobile Testing''.
*To change or copy an existing connection in the GUI browser, select it, right-click and select ''Edit Connection'' or ''Copy Connection'' from the context menu.
*If you do not want to create connection settings for the GUI browser but for use in a test, choose ''Create Connection Settings'' from the Mobile Testing Plugin menu.... This only allows you to create the settings for a connection without creating a connection in the GUI browser.

The Connection Editor menu has several buttons, some of which are only visible when creating connection settings:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#''Delete Settings'': Resets all entries. (Only visible when creating settings.)
#''Load settings from file'': Allows to open a saved settings file (*.csf). Its settings are transferred to the dialog. Entries already made without conflict are retained.
#''Load settings from attachment'': Allows you to open an attachment with connection settings from an open project. These settings are applied to the dialog. Entries already made without conflict are retained.
#''Save settings to file'' and
#''Save settings to attachment'': Here you can save the entered settings to a file (*.csf) or create them as an attachment in an open project. Both options have a delayed menu in which you can choose to save only a certain part of the settings. (Only visible when creating settings.)
#''Advanced View'': Allows you to switch to the advanced view to make additional settings. Read more about this at the end of this chapter. (Only visible when creating settings.)
#''Help'': A help text for the respective step is shown or hidden on the right side.

The dialog is divided into three steps. In the first step you select the device you want to use, in the second step you select which App should be used and in the last step the settings for the Appium server are made.

===Step 1: Select Device ===
In the upper part you will see a list of all connected Appium devices that are detected. With the checkbox below you can hide devices that are detected but not ready. If you want to enter a device that is not connected, you can create it with the corresponding button ''Enter Android device'' or ''Enter iOS device''. However, you need to know the required properties of your device. The device is then created in a second device list and can be selected there. If no list with connected elements can be displayed, various messages are displayed instead:
*No devices found
*:expecco could not find any Android devices.
*:To automatically configure a connection to a device, make sure
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*No available devices found
*:expecco could not find any available Android devices. But not available ones were found, e.g. with the status "unauthorized".
*:To configure a connection to a device automatically, make sure that
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*:To view unavailable devices, enable this option below.
*Connection lost
*:expecco has lost the connection to the adb server. Try to re-establish the connection by clicking on the button.
*Connection failed
*:expecco could not connect to the adb server. Possibly it is not running or the specified path is not correct.
*:Check the adb configuration in the settings and try to start the adb server and establish a connection by clicking on the button.
*Connect ...
*:expecco connects to the adb server. This may take a few seconds.
*Start adb-Server ...
*:expecco starts the adb-Server. This may take a few seconds.

With ''Next'' you get to the next step. If you enter settings for the GUI browser, this is only possible once a device has been selected.

Note on unlocking: In newer Android versions the developer options are no longer offered in the settings at first. If your Android device does not show an entry for "''Developer options''" in the settings, first select the entry "''Phone info''", then "''SoftwareVersionsInfo''" and click on the entry "''BuildVersion''" several times.

==== Manage Chromedrivers ====
If the App you want to automate uses WebViews with Chrome, Appium needs to have access to an appropriate Chromedriver. If you have selected a device in the list, you can use "''Manage Chromedrivers''" to see, which Chrome versions are installed on the device and which Chromedriver versions are provided by expecco. With this dialog you can also download required Chromedriver versions. Beware that there may be several Chrome versions on the device. An App doesn't have to use the version of the installed Chrome browser for its WebViews. The Chromedriver you use should fit your app for everything to work properly. You can also change the path to the Chromedriver in the capabilities generated at the end of the connection editor.

==== Connect WiFi Android Device ====

You can connect to Android devices using WiFi as well. In this case, the device has to be connected to ADB first, see [[Mobile_Testing_Plugin/en#Connection_via_WLAN|Connection via WLAN]]. Since expecco 22.1, the connection editor provides a dialog helping to set this up, which can be used instead of the command window. For devices using Android 11 or newer, you can pair the device with your machine here by specifying the appropriate parameters and then establish the connection by specifying the IP address and port. You can also use this to establish a wireless connection for devices that are connected via USB. When you select the corresponding device in the list, the required information is read out automatically.

Note that establishing a wireless connection is not part of the connection settings. If you want to establish a new connection with the generated settings, you must make sure that the device is connected to ADB with the specified IP address and port so that it can be found. The ADB connection will be lost if the ADB server or the device are restarted. The permission for wireless debugging is also often reset when the device is restarted and the debug port can then change. Therefore, a wireless connection must always be established manually.

===Step 2: Select App===
Here you can enter information about the app to be tested. You can decide if you want to use an app that is already installed on the device or if you want to install an app for the test. Select the appropriate tab above. Depending on whether you selected an Android or an iOS device in the previous step, the required input will change.

*'''Android'''
**''App on Device''
**:If you have selected a connected device in the first step, the packages of all installed apps are automatically retrieved and you can select from the drop-down lists. The installed apps are divided into third-party packages and system packages; select the appropriate package list. This selection does not belong to the settings, but only provides the corresponding package list. You can use the filter to further narrow down the list and then select the desired package. The activities of the selected package are also automatically retrieved and made available as a drop-down list. Select the activity you want to start. As a rule, an activity is automatically entered from the list. If you are not using a connected device, you must enter the package and the activity manually.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. If you are using a local Appium server, you can use the right button to navigate to the App installation file and enter this path. If possible, the corresponding package and the activity are also entered in the fields below. However, this entry is not necessary.

*'''iOS'''
**''App on Device''
**:Specify the bundle ID of an installed app. You can find out the IDs of the installed apps using Xcode, for example. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window will open displaying a list of connected devices. If you select your device, you will see a list of the apps you have installed in the overview.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. For the requirements of apps for real devices, please read the section [[#iOS-Ger.C3.A4t_and_App_Preparing|Preparing an iOS-Device and App]].

In the lower part you can specify whether the app should be reset or uninstalled when the connection is terminated, and whether it should be reset initially. Again, the corresponding capability is not set if you select ''(Default)''. With ''Next'' you get to the next step.

===Step 3: Server Settings===
In the last step, a list of all the capabilities that result from your entries in the previous steps is first displayed in the upper part. If you are familiar with Appium and want to set additional capabilities that are not covered by the connection editor, you can click on ''Edit'' to open the extended view. See the section below for more information.

If you enter settings for the GUI browser, you can enter the ''Connection name'' with which the connection is displayed. This is also the name under which devices can use this connection when it is established. If you leave the field blank, a name will be generated. If the box "''Managed by expecco''" is checked, expecco will start a local Appium server on a free port, or use a free server that has already been started. To use your own server, turn this feature off and enter the appropriate address. You will get the local default address and already used addresses to choose from.

In older expecco versions the box is labeled "''Start on demand''". In this case, you must also enter an address if you want expecco to start the server. expecco then tries to start an Appium server at the given address when connecting, if none is running there yet. This server will then also be shut down when the connection is terminated. This only works for local addresses. Make sure that you only use port numbers that are free. It is best to only use odd port numbers from the standard port 4723. The following port number is also used when establishing a connection, which could otherwise lead to conflicts.

Depending on how you opened the dialog, there are now different buttons to close it. In any case you have the option to save. This opens a dialog where you can either select an open project to save the settings there as an attachment, or choose to save it to a file that you can then specify. Saving does not close the dialog, allowing you to select another option.

If you have opened the editor for establishing a connection, you can finally click on ''Connect'' or ''Start and connect server'', depending on whether the check mark for server start is set. For changing or copying a connection in the GUI Browser, this option is called ''Apply'', since in this case only the connection entry is changed or created, but the connection setup is not started. If necessary, you can do this afterwards via the context menu. If you have changed capabilities of an existing connection, a dialog then prompts you to decide whether these changes should be applied directly by closing the connection and establishing the new connection or not. In this case, the changes only take effect after you reestablish the connection.

To use the connection editor, also read the corresponding section in the respective tutorial in step 1. (Android: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo|Run Demo]], iOS: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo_2|Run Demo]]).

===Extended View===
The extended view of the connection editor can be obtained either by clicking on ''Edit'' in the third step or at any time via the corresponding menu item if you have started the editor via the plugin menu. This view displays a list of all configured Appium Capabilities. You can add, change or remove further entries to this list. To add a capability, select it from the drop-down list of the input field. In this list all known capabilities are sorted into the categories ''Common'', ''Android'' and ''iOS''. If you have selected a capability, a short information text is displayed. You can also enter a capability manually in the field. Then click on ''Add'' to add the capability to the list. There you can set the value in the right column. To delete an entry, select it and click on ''Remove''. With ''Back'' you leave the extended view.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Running Appium Servers ==
In the menu of the Mobile Testing Plugin you will find the entry ''Appium-Server...''. This opens a window with an overview of all Appium servers started by expecco and on which port they are running. By clicking on the icon in the column ''Show Log'' you can view the logfile of the corresponding server. This is deleted when the server is shut down. With the icons in the column ''Exit'' the corresponding server can be terminated. However, this is prevented if expecco still has an open connection via this server. The rightmost column shows for which connection the server is in use. If it reads ''<idle>'', the server is currently not used by expecco.

[[Datei:MobileTestingAppiumServer.png]]

When opening the editor to start an Appium connection, an Appium server is started immediately to speed up the connection process. For this purpose, expecco always keeps one idle running Appium server. Additional running servers however, which are not in use anymore, will be terminated automatically after a while.

In the menu of the Mobile Testing Plugin you will also find the entry ''Close all Connections and Servers''. This is intended for cases where connections or servers cannot be terminated in any other way. If possible, always terminate connections in the GUI browser or by executing a corresponding block. Servers that you have started in the server overview should be terminated there; servers that were started with a connection are automatically terminated with this connection.

Note that only servers started and managed by expecco are listed in the overview. Possible other Appium servers that were started in a different way are not recognized.

== Recorder ==
If the GUI browser is connected to a device, the integrated recorder can be used to record a test section with that device. To start the recorder, select the appropriate connection in the GUI browser and click the Record button. A new window opens for the recorder. The recorded actions are created in the GUI browser work area. It is therefore possible to edit the recorded data in parallel.

[[Datei:MobileTestingRecorder.png|caption|]]

====Components of the Recorder Window====
#'''Continue/Pause Recording''': You can pause the recording by clicking the right icon. You will then see a large pause sign in the view. All actions that you perform now in the recorder are executed, but no blocks are recorded. You can switch back to normal recording mode by clicking the left icon.
#'''Stop Recording''': Stops the recording and closes the recorder window.
#'''Update''': Gets the current image and element tree from the device. This is necessary if the device takes longer to execute an action or if something changes without being triggered by the recorder. Since expecco 21.2, there is an additional submenu here that can be used to enable automatic update by checking for changes in the background (see also ''Automatic Update'' further below).
#'''Follow Mouse''': Select the element under the mouse pointer in the GUI browser.
#'''Element Highlighting''': The element under the mouse is outlined in red.
#'''Show Elements''': Show the borders of all elements in the view.
#'''Tools''': Selection, which tool is used for recording. The selected action is triggered with each click on the view. The following actions are available:
#*Element Actions:
#**Click: Short click on the element under cursor. To determine more precisely which element is used, use the Follow Mouse or Element Highlighting function.
#**Tap with Duration (Element): Similar to click, except that the duration of the click will be recorded as well. This allows the recording of long clicks.
#**Tap with Position (Element): Similar to click, but additionally records the position inside the element. The position can be recorded relative to the element size or, when pressing Ctrl while clicking, as absolute position from the upper left corner of the element.
#**Set Text: Allows to set the text of an input field.
#**Clear Text: Clears the text of an input field.
#*Device Actions:
#**Tap (Screen): Triggers a click at the screen position.
#**Tap with Duration (Screen): Triggers a click at the screen position, which also considers the duration.
#**Swipe: Swipe in a straight line from the point where you press the mouse button until you release it. The duration is also recorded.
#:Please note for this actions that the result may differ on different devices, e.g. with different screen resolutions.
#*Test Flow Blocks
#**Check Attribute: Compares the value of a specified attribute of the element with a predefined value. The result triggers the corresponding output.
#**Assert Attribut: Compares the value of a specified attribute of the element with a predefined value. If the values are not equal, the test fails.
#**Get Attribute: Gets the current value of a specified attribute of the element.
#*Auto
#:If the Auto tool is selected, you can use all actions by specific input methods: ''Click'', ''Tap Element'' and ''Swipe'' still work by clicking, but are distinguished by the duration and movement of the cursor. To trigger a ''Tap'', hold down Ctrl while clicking. The remaining actions are available in a context menu by right-clicking on the element.
#'''Context Actions''': Here you can record actions concerning contexts:
#*Switch to Context: Shows a list of all currently available contexts and you can select to which one you want to switch.
#*Get Current Context: Gets the handle of the current context.
#*Get Context Handles: Gets a list of all currently available contexts.
#'''Softkeys''': Only for Android. Simulates pressing the buttons Back, Home, Menu and Power.
#'''Home Button''': Only for iOS since expecco 2.11. Allows pressing the Home button.Prior to expecco 19.2, it only works if AssistiveTouch is activated and the menu is located in the middle of the upper screen border. From expecco 19.2 on, the function no longer uses AssistiveTouch.
#'''Help''': Opens this online documentation on the general page about [[GuiBrowser_Recorder/en|GUI Browser recorders]].
#'''View''': Shows a screenshot of the device. Actions are triggerd by mouse depending on the selected tool. If a new action can be recorded, the window has a green frame, else it is red.
#'''Resize Window to Image''': Resizes the recorder window so that the screenshot can be displayed completely.
#'''Resize Image to Window''': Scales the screenshot to a size that makes use of the full size of the window.
#'''Adjust Display''': Opens a dialog to adjust the displayed image, if expecco does not show it right. You can correct the scaling or rotate the image by 90°.
#'''Correct Orientation''': Corrects the image if it is upside down. Using the arrow to the right, the image can also be rotated by 90°, if this should ever be necessary. Since expecco 19.1 you find this functionality under ''Adjust Display''. The orientation of the image is irrelevant for the functionality of the recorder, it only works on the elements it receives.
#'''Scaling''': Changes the scaling of the screenshots.
#'''Messages''': Shows the path of the current selected element or other messages. It has a context menu to show a list of previous messages.

====Usage====
Each click in the window triggers an action and is recorded in the workspace of the GUI browser. There you can run, edit, or create a new block from what you have recorded. You find the actions to trigger softkeys directly in the menu bar (see above). To record actions on elements, either change the selection of the tool in the menu bar (see above) and then click on the element or select the corresponding action from the context menu by right-clicking on the corresponding element. For text input it is also possible to place the cursor over the element and enter the text. This opens the input dialog for this action. On how to use the recorder, see also step 2 in the tutorial ([[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_Block_with_the_Recorder|Android]] resp. [[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_block_with_the_Recorder_2|iOS]]).

====Hide elements====
Since expecco 21.2 it is also possible to hide the selected element in the recorder from the context menu. This means that this element cannot be selected from now on. This function is useful for ignoring elements that are in the foreground to be able to access elements below them. To undo this state, you have to find the corresponding element in the tree of the GUI browser, which also has such an entry in the context menu.

====Automatic Update====
The recorder doesn't show a live image of the device, but only a snapshot. Therefore an update is needed after changes to match what is displayed on the device. The recorder updates automatically after executing an action. Since expecco 20.2 there are further automatic updates possible. You can enable the, in the menu "View".

One option is, to check after an action has been executed, if there are further changes after the first update. If so, a second update is triggered. This shall fix the problem, that the recorder is not up to date after an action, because the update has been done too early.

The second option is to enable a periodical update. After a set interval the recorder is automatically updated if there are changes. Thereby the recorder view is mostly up to date, but this causes an overhead regarding the communication to the device.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid Apps and WebViews =
'''!!! IMPORTANT NOTICE - If you have problems switching to the webview, please set the "Default Application - Browser App" in Android Settings to "Chrome" !!!'''

Hybrid apps contain platform native elements as well as other elements that are integrated in a WebView. These elements can also be used, but you first have to switch to the corresponding context. With the block ''Get Current Context'' you get the current context. Initially this is ''NATIVE_APP'', i.e. the context of the native elements. With the block ''Get Context Handles'' you get a collection of all existing contexts. If there is a WebView context, it is called ''WEBVIEW_1'' or ''WEBVIEW_<package>'' with the package of the WebView. Several WebView contexts are also possible. For each WebView context, there is a corresponding WebView element in the native context. You can use the ''Switch to Context'' block to switch to such a context and from now on only have access to the elements in this context.

In the GUI browser, the existing contexts are displayed at the top of the tree as well as the tree of a context is inserted below the corresponding WebView element.

=Customizing XPath using the GUI Browser=
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen ''GTIN-13 (EAN-13)'' und ''Verify'', das Eingabefeld der Zahl ''4006381333986'' und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des GTIN-13-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch ''Pfad überprüfen'' (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit ''Verify Path: OK'' (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit * zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert ''GTIN-13 (EAN-13)'' besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer ''hierarchy'' (für iOS wäre es ''AppiumAUT''), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix ''android.widget.'', das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend ''XCUIElementType'' am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. ''FrameLayout'' ist ein Kindelement von ''hierarchy'', ''LinearLayout'' ist ein Kind von ''FrameLayout'' usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element ''hierarchy'' beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben ''TextView''-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ ''Button'' gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut ''resource-id''. Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut ''name'' verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem @ eingeleitet und der Wert mit einem = in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter ''Test'' eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf ''Lauf''. Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu ''Eigenschaften'', wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

=Problems and Solutions=
== Locators depend on the version or are variable ==
In this case consider to either store the locators (xPath) in a variable or to define a locator mapping inside a screenplay attachment. It is also possible to store just parts of an locator (e.g. locator path of a parent or attribute value) in a variable and add them in the freeze value of the locator pin by "''$(varName)''".

== Invisible UI Elements ==
Note that the [[#Recorder|Recorder]] also considers items that you cannot see on the screen. Therefore, turn on element highlighting or use the follow mouse function and the element tree in the GUI browser to determine if the correct element is used. It can happen, that invisible elements are in front of other elements and cover them, so that the desired element cannot be selected in the recorder. See section [[#Hide_elements|Hide elements]] for a solution to this.

== iOS: Cable not certified ==
In some cases, when connecting an iOS device via USB, a message appears indicating that the cable used is not certified. In this case, replacing the respective cable is the only solution.

== iOS: Alerts when connecting ==
Make sure that no alerts are open when connecting to an iOS device. Otherwise the connection will fail because the app cannot be brought to the foreground. See also [[#Preparing_an_iOS-Device_and_App|Preparing an iOS-Device and App]].

== iOS: .ipa cannot be installed ==
Note that on iOS simulators no ''.ipa'' files can be installed but only ''.app'' files.

==iOS: First Connect is not working==
If there is not already a signed build of the WebDriverAgent on your Mac, it has to be created during the first connect. Usually, this can take a little longer than one minute. Per default Appium uses a timeout of 60000 ms to wait for the WebDriverAgent to start on the device, so the connect will be canceled in that case. You can set this timeout with the capability ''wdaLaunchTimeout'', e.g. to ''120000''.

Moreover, the signing settings have to be correct. In our experience, the most reliable solution is to set automatic signing in the WebDriverAgent Xcode project an selecting the team there. See the explanation in section [[#Signing_WebDriverAgent|Signing WebDriverAgent]] for that. In this case you should '''not''' use the capabilities ''xcodeConfigFile'' resp. ''xcodeOrgId'' and ''xcodeSigningId'', as they could cause a conflict. Caution: If you have set a Team ID in the Mobile Testing settings, expecco will automatically set this as ''xcodeOrgId''!

Pay attention to your device during the first connect. You might have to agree to the installation by entering your password. On the Mac you might need to enter the password to allow access to the key chain for signing, often several times.

== Android: Device not visible in the connect editor ==
If an Android device connected via USB does not appear in the connection editor, try changing the USB connection type. Usually MTP or PTP should work. Check again, if "USB Debugging" is enabled in the developer options on the device (these options are disabled on some devices and have to be enabled first using a trick.) See also [[#Prepare_Android_Device|Prepare Android Device]].

== Android: Truncated Elements at Bottom ==
For Android devices that automatically show and hide the navigation bar/softkeys, the recorder may cut off elements in the lower area that would be hidden by the softkeys, even if they are not displayed at this time. In this case it is advisable to set the softkeys so that they are permanently displayed.

For newer Android versions there usually is no such option. Even if the controls are visible all the time, they don't have their own space, but are on top of the content of the app. Therefore, there is an area on the lower part of the screen, which cannot be automated, because it is not counted to the active area of the app. Appium will then truncate the elements there. This area can even be larger then the needed by the controls. This is a known issue for Samsung devices with Android 11. Since the information about the size of the app area is already provided on Android level, we cannot offer a solution for this, but can only hope that the problem will be fixed by the manufacturer. You may try to get better results by setting the control to gestures, but this bears the same issue.

== Android: Test Hangs While Finding an Element==
The block ''Find Element by XPath'' and all element blocks wait until an element is present for the given path. The timeout for this can be set either directly at the block or in the environment variables. However, if the element should already be present, but the test doesn't continue anyway, the reason could be in the UIAutomator/UIAutomator2. It waits for the app to go to the idle state before it even starts to search for the element. This may take longer, if the app e.g. runs an animation in the background or executes other kinds of actions. Fetching the page source, e.g. when updating in the GUI browser or in the recorder, can also take longer for this reason. There is a default timeout of 10 seconds after which it no longer waits for the idle state. This timeout can be set in Appium (waitForIdleTimeout). If you want to change the value of this timeout, you can do this since expecco 21.2 by executing the Smalltalk code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> before the test. The timeout is given in milliseconds, so the example sets it to 2 seconds.

==Android: Updating the Tree or Switching to Webview Context takes too long==
Especially with older devices it can happen that newer Chromedriver cannot be initialized. This makes it impossible to switch to the webview context. However, this is only detected over a timeout by Appium, which is 4 minutes by default. Since expecco also tries to switch to the webview context when building the tree in the GUI browser, this can lead to very long loading times. Since there is no way to decrease this timeout in Appium, we have added a corresponding capability to the version we provide in the MobileTestingSupplement. Starting with version 1.13.1.0 of the [[#Windows|MobileTestingSupplement]], ''chromedriverStartTimeout'' can be used to set the timeout in milliseconds. The switch still doesn't work then, but expecco doesn't take as long to update the tree and the context switch module fails faster. The connection dialog adds this capability automatically starting with expecco 22.1.

== No Action on Click ==
The block to click on an element is successful, but no action was performed on the device.
:This can happen if the element is hidden by another element and therefore clicking on the element is not possible. In this case, Appium does not throw an error, but simply nothing happens. If you would like to make a click at the position of the element anyways, even if it is hidden, use the block ''Tap'' instead and pass the location of the element to it (''Get Location''). If instead you want to check before a click whether the element is hidden at this moment, try whether the properties ''Is Displayed'' or ''Is Enabled'' might help you.

== No Update After Action ==
An action was triggered on the recorder and a block has been recorded, but the recorder still shows the old image.
:The recorder doesn't show a live image of the device, but only a snapshot. After an action has been executed, the recorder will update automatically. However, it can happen, that the image has already been updated before the effects of the action are fully completed on the device. In this case you should update the recorder by hand using the icon with the blue arrows. Since expecco 20.2 you can also enable automatic updates for this case. See also the description for the [[#Recorder|recorder]].

== Attribute "clickable" is wrong ==
An element has for the attribute/property "''clickable''" the value "''false''", but is actually clickable.
:The attribute "''clickable''" has to be set explicitly by the app developer and does not affect the behavior of the app. You should generally disregard this attribute in your tests. Unfortunately, many apps exist where the programmer was "lazy" about this.

==Connecting Fails==
If the connection to the Appium server fails, you will receive an error message in expecco similar to the one shown below.

[[File:MobileTestingVerbindungsfehler.png]]

Here you can see the type of error that has occurred. Click on "''Details''" to get more information. Possible errors are:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:The specified server is not running or is not reachable. Check the server address.
*''org.openqa.selenium.WebDriverException''
:Read the message after ''Original Error'' in the first line of the details:
:*''Unknown device or simulator UDID''
::Either the device is not connected properly or the udid is not correct.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::This error can have various causes. Either the WebDriverAgent could actually not be built because the signing settings are wrong or the appropriate provisioning profile is missing. Please read the section about [[#Signing|Signing]]. It is also possible that the WebDriverAgent cannot be started on the device, for example because an alert is in the foreground or you did not trust the developer.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::The specified app cannot be installed on the iOS device because it is not entered in the app's Provisioning Profile.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.''
::The path to the app is wrong. Make sure that the file is located in the specified path on your Mac.
:*''packageAndLaunchActivityFromManifest failed.''
::The specified ''apk'' file is probably broken.
:*''Could not find app apk at [...]''
::The path to the app is wrong. Make sure that the ''apk'' file is located in the specified path.

If the error is not due to one of the causes listed above, the automation applications on the device may no longer function properly. In this case it helps to uninstall them from the mobile device. They are then automatically reinstalled the next time a connection is established.

*For iOS devices, this is the WebDriverAgent, which you can simply uninstall from the home screen. This usually solves problems caused by changing the used Mac or the Xcode version.

*For Android devices, it is the UIAutomator2; here, a problem occurs sporadically on some devices, the cause is currently unknown to us. To uninstall, on the device, navigate to "''Settings''" > "''Applications''"* and search the list for the following entries:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Click on the respective application and then on "''Uninstall''".
*''The corresponding entry may have a slightly different name on some devices.''

If this doesn't help, check the output of the Appium server. For a server started by expecco, you can find the log in the list of [[#Running_Appium_Servers|Running Appium Servers]].

==I do not have a Mac==
Maybe this site will help you: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin

2024-07-11T09:36:15Z

Matilk: /* Windows */ new supplement

'''Deutsche Version''' | [[Mobile_Testing_Plugin/en|English Version]]

= Einleitung =
Mit dem ''Mobile Testing Plugin'' können Anwendungen auf Android- und iOS-Geräten getestet werden. Dabei ist es egal, ob reale mobile Endgeräte oder emulierte Geräte verwendet werden. Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests unterstützt. Zudem ist damit das Aufzeichnen von Testabläufen möglich.

Zur Verbindung mit den Geräten wird [http://appium.io/ Appium] verwendet. Appium ist ein freies Open-Source-Framework zum Testen und Automatisieren von mobilen Anwendungen.

Zur Einarbeitung in das Mobile Plugin empfehlen wir das [[Mobile_Testing_Tutorial|Tutorial]] zu bearbeiten. Dieses führt anhand eines Beispiels Schritt für Schritt durch die Erstellung eines Testfalls und erklärt die nötigen Grundlagen.

= Installation und Aufbau =
Zur Verwendung des Mobile Testing Plugins müssen Sie expecco inkl. des Plugins Mobile Testing installiert haben und Sie benötigen die entsprechenden Lizenzen. expecco kommuniziert mit den Mobilgeräten über einen Appium-Server, der entweder auf demselben Rechner wie expecco läuft, oder auf einem zweiten Rechner. Dieser muss für expecco erreichbar sein.

==Installationsübersicht==

'''Rechner, auf dem expecco läuft:'''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem Android-Geräte angeschlossen sind:'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Android SDK'', dieses erhalten Sie ebenfalls mit dem Mobile Testing Supplement''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem iOS-Geräte angeschlossen sind2):'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement für Mac OS installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Xcode ''in einer Version, die die verwendete iOS-Version unterstützt, erhältlich über den Apple App Store''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
* Apple-Entwickler-Zertifikat mit zugehörigem privaten Schlüssel ''(zum Signieren des WebDriverAgents)''
* Provisioning Profile mit den verwendeten Mobilgeräten

Je nach Aufbau können die oben genannten Rechner auch das selbe Gerät sein. expecco kann sich sowohl über das Netzwerk mit einem entfernten Appium-Server und dort angeschlossenen Mobilgeräten verbinden, als auch lokal selbst einen Appium-Server starten und diesen mit lokalen Mobilgeräten verwenden. Einige Funktionen von expecco, die die Erstellung von Testfällen erleichtern, sind jedoch nur verfügbar, wenn die Mobilgeräte am selben Rechner angeschlossen sind, auf dem auch expecco läuft. Ein möglicher Aufbau kann daher wie in folgender Abbildung aussehen:

[[Datei:MobileTestingAufbau.png | 400px]]

Im Folgenden wird die Installation von Appium und anderer nötiger Programme für Windows und Mac OS erklärt.

1): Zum Zeitpunkt der Erstellung dieses Dokuments wurden Versionen bis 11 auf Funktion verifiziert. Neuere Versionen sollten - sofern nicht grundlegende Änderungen von Oracle vorgenommen wurden, ebenfalls funktionieren.

2): Beachten Sie, dass aufgrund der Voraussetzungen (keine Anbindung an nicht-Apple Geräte verfügbar) iOS-Geräte nur von einem Mac aus angesteuert werden können. Sie benötigen also einen Mac als "Vermittler" (siehe auch unten: [[#Ich habe keinen Mac | "Ich habe keinen Mac"]])

== Windows ==
Am einfachsten installieren Sie alles mit unserem Mobile Testing Supplement1. In neueren Versionen ist allerdings aufgrund geänderter Lizenzbedingungen seitens Oracle kein JDK mehr enthalten, sodass sie dieses zusätzlich installieren müssen. Sie können natürlich Appium auch direkt installieren, um die Version zu verwenden, die Sie möchten. Um dann einen Appium-Server mit expecco starten zu können, muss allerdings eine entsprechende Batchdatei vorhanden sein und in den [[Mobile_Testing_Plugin#Konfiguration_des_Plugins|Einstellungen]] angegeben werden. Verbindungen können aber auch zu anderen laufenden Appium-Servern aufgebaut werden.
*'''expecco 24.1''': [https://download.exept.de/transfer/h-expecco-24.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.3]
:Im Vergleich zum Vorgänger aktualisierte Chromedriver Versionen.
*expecco 23.2: [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Im Vergleich zum Vorgänger aktualisierte Chromedriver Versionen.
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Gleiche Versionen wie der Vorgänger, aber der Installer erlaubt nun, Appium zum Autostart hinzuzufügen.
*expecco 22.2 und 22.1: [https://download.exept.de/transfer/h-expecco-22.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 aus platform-tools 33.0.2
:''* Wir haben Appium um die Capability'' startChromedriverTimeout ''erweitert, um schneller einen Timeout zu bekommen, wenn der Chromedriver nicht gestartet werden kann. (siehe [[#startChromedriverTimeout|Probleme und Lösungen]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Enthält die Appium-Version 1.22.0, Node ist weiterhin in der Version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Nur kleine Änderungen im Vergleich zur vorigen Version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und node 12 verwendet.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:Dieses installiert Appium in der Version 1.12.0 und enthält nun zusätzlich build-tools der Version 28.0.3 im android-sdk. Ansonsten ist es gleich wie die vorige Version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:Dieses installiert Appium in der Version 1.8.1. Außerdem bietet das Supplement auch an, ''Android Debug Bridge'' und ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) zu installieren. Damit sind Treiber für ein breites Spektrum an Android-Geräten abgedeckt, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen. Ein '''JDK ist (aufgrund geänderter Lizenzbedingungen seitens Oracle) nicht mehr enthalten''', dieses müssen Sie selbst herunterladen, z.B. von [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: wie expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.6.4. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.4.16. Während der Installation wird die grafische Oberfläche von Appium gestartet, dieses Fenster können Sie sofort wieder schließen. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.

Wenn expecco Mobilgeräte verwenden soll, die an einem anderen Rechner angeschlossen sind, müssen Sie dort einen Appium-Server starten. Dies können Sie mit der Datei <code>appium_standalone.cmd</code> tun. Der Server wird dann mit dem Standard-Port 4723 gestartet. Falls Sie eine andere Portnummer verwenden wollen, starten Sie den Server mit

appium_standalone.cmd -p <portnummer>

Der Server ist bereit, sobald die Zeile
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
angezeigt wird, wobei Sie am Ende die verwendete Portnummer ablesen können.

Beim ersten Starten von Appium – sowohl im Standalone als auch gestartet von expecco – kann es vorkommen, dass die Windows-Firewall den Node-Server blockiert. Lassen Sie den Zugriff zu, sonst kann Appium nicht gestartet werden.

1) Sie können natürlich auch die Command Line Tools (adb, sdkmanager, avdmanager etc.) einer vorhandenen Android Studio Version verwenden, sowie Appium separat installieren.
Da sich diese Tools regelmäßig ändern, und es in der Vergangenheit zu Inkompatibilitäten und Fehlern nach Releasewechseln kam, empfehlen wir zu Beginn, das mitgelieferte Paket zu verwenden. Dies ist möglicherweise nicht das aktuellste, wurde aber auf Lauffähigkeit getestet.

Falls das Android Mobilgerät an einem entfernen Rechner angeschlossen ist,
können Sie den aktuellen Bildschirminhalt z.B. mit dem [https://github.com/Genymobile/scrcpy scrcpy] tool live mitverfolgen.

== Mac OS (nicht erforderlich für Android-Tests)==
Hinweis: Wenn Sie nicht vorhaben, iOS-Geräte (iPhone, iPad, etc.) zu testen, können Sie das Folgende ignorieren. '''Der Apple-Rechner sowie das Mac-Setup werden für Android-Geräte nicht benötigt'''.

=== Xcode ===
Zur Automatisierung mit iOS-Geräten wird [https://developer.apple.com/xcode/ Xcode] benötigt. Sie erhalten dieses über den App Store. Dabei ist darauf zu achten, dass die Version zu den getesteten iOS-Versionen passt.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
Diese Tabelle gibt nur eine vereinfachte Übersicht, lesen Sie besser unter [https://xcodereleases.com/ Xcode Releases] oder [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode-Versionen] welche Version Sie brauchen. Für neue iOS Minor-Versionen gibt es in der Regel auch ein Update für Xcode, z.B. brauchen Sie für iOS 10.2 mindestens Xcode 8.2, für iOS 10.3 mindestens Xcode 8.3 usw.
Wenn Sie also auf eine neuere iOS-Version wechseln, benötigen Sie in der Regel auch eine neuere Xcode-Version. Neuere Versionen von Xcode laufen möglicherweise nicht auf älteren Betriebssystemen, was wiederum eine Aktualisierung des Betriebssystems erforderlich machen kann. Falls Sie auch ältere iOS-Versionen testen wollen kann es sinnvoll sein, die entsprechenden Xcode-Versionen parallel zu installieren.

=== Appium ===
Der Appium-Server kann entweder als Kommandozeilen-Anwendung installiert werden oder über [https://github.com/appium/appium-desktop Appium Desktop] verwendet werden, welcher den Server über ein GUI zur Verfügung stellt. Mittlerweile gibt es auch Appium 2.0, was wir aber bisher noch nicht mit expecco getestet haben und daher nicht empfehlen.

==== Appium Desktop ====
Laden Sie die neueste Version von [https://github.com/appium/appium-desktop/releases/ Appium Desktop] herunter. Für den Mac nehmen Sie am besten die dmg-Datei und installieren sie in den Anwendungen. Beim Starten der Anwendung ''Appium Server GUI'' erhalten Sie wahrscheinlich eine Fehlermeldung, dass es aus Sicherheitsgründen nicht möglich ist. Öffnen Sie dann das Kontextmenü auf der Anwendungsdatei (Rechtsklick bzw. Strg + Klick) und wählen Sie dort ''Öffnen'' aus. Bestätigen Sie dann, dass Sie die Anwendung wirklich öffnen wollen. Fortan können Sie die Anwendung normal öffnen.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Ab Xcode 14 gibt es Probleme beim Signieren des WebDriverAgents, den Appium zur Automatisierung auf das Gerät spielt. Dadurch ist mit der Version 1.22.3-4 von Appium Desktop kein Verbindungsaufbau möglich. Das Problem ist in neueren Versionen des WebDriverAgents behoben, es gibt aber aktuell noch keine Version von Appium Desktop, die eine solche Version enthält (Stand November 2022). Sie können aber manuell eine neue Version herunterladen (z.B. 4.10.2) und die Dateien in Appium ersetzen. Laden Sie dazu von der [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent Download-Seite] eine der beiden Archivdateien (zip oder tar.gz) mit dem Source Code herunter. Öffnen und entpacken Sie dann diese Datei. Den Inhalt des Ordners WebDriverAgent-4.10.2 müssen Sie nun nach

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

kopieren. Wenn Sie über den Finder dorthin navigieren, machen Sie auf die Anwendung ''Appium Server GUI'' einen Kontextklick (Rechtsklick bzw. Strg + Klick) und wählen Sie im Menü ''Paketinhalt anzeigen''. Ersetzen Sie alle Dateien, die bereits mit gleichem Namen enthalten sind.

==== Appium über npm installieren ====
Sie können Appium auch über npm (Node Package Manager) installieren. Dazu müsen Sie erst node/npm installieren. Das geht mit [https://github.com/nvm-sh/nvm nvm] (Node Version Manager) was Sie von Github bekommen. Falls die folgende Installationsanleitung bei Ihnen nicht funktionieren sollte, finden Sie dort ausführlichere Informationen im [https://github.com/nvm-sh/nvm#readme Readme].

Öffnen Sie ein Terminal-Fenster. Klonen Sie dann das Github-Repository von nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
und laden Sie es
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Führen Sie danach
command -v nvm
aus, um zu testen, ob es funktioniert hat. Es sollte ''nvm'' ausgegeben werden. Kommt keine Antwort, führen Sie
touch ~/.zshrc
aus, und versuchen Sie es erneut.

Nun können Sie node mit dem folgenden Befehl installieren.
nvm install 16.15.1
Da es mit der aktuellen Version von node Probleme beim Installieren von Appium gibt, empfehlen wir diese Version.

Nachdem node installiert ist, können Sie Appium darüber installieren:
npm install -g appium

Den Appium-Server können Sie nun einfach über den Befehl
appium
starten. Die Ausgabe erfolgt dann direkt im Terminal.

Auch bei dieser Version gibt es das Problem bei der Signierung des WebDriverAgents, wie bei [[#Appium_Desktop | Appium Desktop]] beschrieben. Laden Sie also auch in diesem Fall eine neuere Version des WebDriverAgents herunter und ersetzen Sie die alten Dateien. Diese finden Sie unter
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
Ältere Appium-Versionen stellen wir Ihnen über das Mobile Testing Supplement für Mac OS zur Verfügung, mit dem Sie es einfach installieren können:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.2)]
:Enthält Appium Version 1.18.3 und verwendet node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.0)]
:Nur wenige Änderungen im Vergleich zur vorigen Version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.98)]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und es wird node 12 verwendet.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.96)]
:Diese Version enthält Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.94)]
:Diese Version enthält Appium 1.8.0.

* expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.0.94)]
:Diese Version enthält Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement für Mac OS]
:Diese Version entält Appium 1.4.16.

Nachdem Herunterladen des Supplements, können Sie es in ein Verzeichnis Ihrer Wahl (z. B. Ihr Home-Verzeichnis) verschieben und dort entpacken. Ein geeigneter Befehl in einer Shell könnte wie folgt aussehen, passen Sie dabei die Versionsnummer entsprechend an:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

Wenn Sie Ihre Standard-Xcode-Installation verwenden wollen, können Sie Appium direkt über die Datei im ''bin''-Verzeichnis mit der entsprechenden Versionsnummer starten:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Falls Sie ein anderes Xcode als das als Standard konfigurierte verwenden wollen, müssen Sie Appium den entsprechenden Pfad über die Umgebungsvariable ''DEVELOPER_DIR'' angeben.
Wenn Sie Xcode z. B. in ''/Applications/Xcode-11.3.app'' installiert haben, müssten Sie Appium so starten:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Was als Standard-Xcode-Installation gesetzt ist, zeigt der Befehl:

xcode-select -p

Wenn Appium Ihre Xcode-Installation nicht findet, erscheint beim Verbinden eine Fehlermeldung in der Art:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
Starten Sie in diesem Fall Appium erneut, unter Angabe eines gültigen ''DEVELOPER_DIR''.

==== WebDriverAgent-Signierung ====
Zur Automatisierung lädt Appium eine App namens WebDriverAgent auf das Gerät und muss sie dafür signieren können. Dazu brauchen Sie einen Apple-Account und ein entsprechendes Zertifikat. Zur Evaluierung können Sie einen kostenlosen Account verwenden. Dieser hat den Nachteil, dass erstellte Profile nur eine Woche gültig sind und danach neu erstellt werden müssen. Seien Sie auch vorsichtig, wenn Sie sich den Account teilen, da es vorkommen kann, dass Zertifikate widerrufen werden oder durch automatische Generierung ungültig werden. Als Folge können bereits signierte Apps nicht mehr verwendet werden.

Wenn Sie bereits ein entsprechendes Zertifikat mit dem zugehörigen privaten Schlüssel in Ihrer [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac haben, können Sie den WebDriverAgent automatisch signieren lassen. Ansonsten empfiehlt es sich, die Signierung über Xcode einzustellen und zu verwalten.

Schließen Sie zuerst das Gerät, das Sie verwenden möchten, über USB an den Mac an. Stellen Sie sicher, dass sich der Mac und das Gerät im selben Netzwerk befinden, ansonsten kann es beim Verbindungsaufbau mit Appium zu Problemen kommen. Starten Sie Xcode und öffnen Sie ''Preferences''. Wechseln Sie zur Seite der Accounts und legen Sie einen Eintrag mit Ihrem Account an. Anschließend können Sie auf ''Manage Certificates...'' klicken, um die Zertifikate zu sehen, die zu diesem Account gehören. Zum Ausführen von Tests benötigen Sie ein iOS-Development-Zertifikat und den dazugehörigen privaten Schlüssel. Wenn Sie noch keines besitzen, erstellen Sie eines. Wenn Sie bereits eines haben, aber es nicht in Ihrem Schlüsselbund vorhanden ist (erkennbar an dem Hinweis "Not in Keychain"), können Sie es importieren. Das können Sie über die [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac machen, wenn Sie es zuvor aus dem Schlüsselbund exportiert haben, in dem es sich befindet. Das Zertifikat mit dem zugehörigen Schlüssel sollte sich im Schlüsselbund ''Anmeldung'' befinden. Dort kann es als PKCS#12-Datei (Endung typischerweise .p12) exportiert werden. Um ein Zertifikat in Ihren Schlüsselbund zu importieren, wählen Sie im Menü ''Ablage'' die Option ''Objekte importieren''. Falls Sie nicht wissen, wo das Zertifikat gespeichert ist, können Sie es in Xcode auch widerrufen und in Ihrem Schlüsselbund neu anlegen. Machen Sie das jedoch nur, wenn Sie wissen, dass das alte Zertifikat nicht mehr in Verwendung ist, da es danach nicht mehr benutzt werden kann. Nun sollte Ihr Schlüsselbund ein iOS-Development-Zertifikat enthalten.


Öffnen Sie nun das WebDriverAgent-Projekt in Xcode. Wenn Sie das Mobile Testing Supplement installiert haben, finden Sie es in dessen Verzeichnis unter
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
Wenn Sie Appium Desktop installier haben, finden Sie es unter
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''
Sie können einfach im Finder zu der Xcode-Project-Datei navigieren und Sie über einen Doppelklick öffnen. Beachten Sie dabei, dass Sie dabei auf die Anwendung Appium Server GUI einen Kontextklick (Rechtsklick bzw. Strg + Klick) machen und im Menü ''Paketinhalt anzeigen'' auswählen müssen, um in deren Unterverzeichnis zu gelangen.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Wählen Sie ''WebDriverAgentLib'' und die Seite ''Signing & Capabilities'' aus. Setzen Sie dort im Abschnitt ''Signing'' die Option ''Automatically manage signing'' und wählen Sie dann ein Team aus. Wechseln Sie nun zu ''WebDriverAgentRunner'' und tun Sie dort dasselbe.

Durch das Setzen des Teams sollten die Fehler für den WebDriverAgentRunner verschwinden. Sollte Xcode kein passendes Provisioning Profile für die Bundle ID ''com.facebook.WebDriverAgentRunner'' erstellen können, können Sie diese anpassen, dass sie zu Ihrem Zertifikat passt. Danach können Sie Xcode beenden oder auch, wie weiter unten beschrieben, direkt den Build über Xcode starten, damit das Projekt bereits gebaut ist, wenn Appium es verwenden möchte.

Wenn Sie sich nun von expecco eine Verbindung zu Ihrem Gerät aufbauen, wird der WebDriverAgent darauf installiert und gestartet, um anschließend zur zu testenden App zu wechseln. Eventuell muss auf dem Gerät muss der Ausführung des WebDriverAgents vertraut noch werden. Ein Anzeichnen dafür kann sein, dass die App WebDriverAgent zwar auf dem Gerät erscheint und zu starten versucht, danach aber wieder deinstalliert wird. Öffnen Sie dazu während des Verbindungsaufbaus auf dem Gerät in die Einstellungen und dort unter ''Allgemein'' den Eintrag ''Geräteverwaltung''. Dieser Eintrag ist nur sichtbar, wenn eine Entwickler-App auf dem Gerät installiert ist. Sie müssen daher möglicherweise warten, bis der WebDriverAgent installiert ist, bevor der Eintrag erscheint. Wählen Sie dort den Eintrag Ihres Apple-Accounts und vertrauen Sie ihm. Da der WebDriverAgent wieder deinstalliert wird, wenn der Start nicht funktioniert hat, müssen Sie dies während des Verbindungsaufbaus tun. Falls Ihnen das zu hektisch ist, können Sie auch folgenden Code ausführen:

<nowiki>xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test</nowiki>
bzw.
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

Damit wird der WebDriverAgent auf dem Gerät installiert ohne dass er wieder gelöscht wird.

Wenn es Probleme beim Installieren des WebDriverAgents gibt, können Sie auch versuchen, den Build über Xcode zu starten. Stellen Sie sicher, dass das richtige Target ''WebDriverAgent'' ausgewählt ist. Fehlermeldungen in Xcode zeigen vielleicht einfacher, wo das Problem liegt. Manchmal hilft es auch, es ein zweites Mal zu versuchen, weil es möglicherweise beim ersten Mal zu lange gedauert hat und abgebrochen wurde. Es kann sein, dass Sie während des Builds mehrmals aufgefordert werden, das Passwort für Ihren Schlüsselbund anzugeben.

[[Datei:WebDriverAgentCodesign.png]]

Lesen Sie auch die Dokumentation von Appium zum [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Aufsetzen von Tests mit iOS-Geräten]. In der [https://support.apple.com/en-us/HT204460 Dokumentation von Apple] finden Sie nähere Informationen zum Installieren und Vertrauen von Apps.

Ist der WebDriverAgent einmal auf dem Gerät installiert, wird er für spätere Verbindungen wieder verwendet und der Verbindungsaufbau sollte schneller funktionieren. Ebenso liegt dann die signierte Version bereits auf Ihrem Mac und muss nicht erneut gebaut werden, was die Verbindung zu weiteren Geräten ebenfalls beschleunigt. Wenn Sie wissen, dass bei Ihrem Verbindungsaufbau der WebDriverAgent erst noch signiert und gebaut werden muss, ist es ratsam, die Capability ''wdaLaunchTimeout'' zu setzen. Dieser Timeout, wie lange auf den Start der WebDriverAgents auf dem Gerät gewartet werden soll, liegt standardmäßig bei 60000$nbsp;ms. Der Build dauert aber häufig über eine Minute, sodass der Versuch zum Verbindungsaufbau dann abgebrochen wird. Ein Wert von 120000 hat sich hier als besser erwiesen.

== Konfiguration des Plugins ==
Bevor Sie loslegen, sollten Sie die Einstellungen des Mobile Testing Plugins überprüfen und ggf. anpassen.

Öffnen Sie im Menü den Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" den Eintrag "''Mobile Testing''" (s. Abb.). Standardmäßig werden diese Pfade automatisch gefunden (1). Um einen Pfad manuell anzupassen, deaktivieren Sie den entsprechenden Haken rechts davon. Sie erhalten in einer Drop-down-Liste einige Pfade zur Auswahl. Ist ein eingetragener Pfad falsch oder kann er nicht gefunden werden, wird das Feld rot markiert und es erscheint ein diesbezüglicher Hinweis. Stellen Sie sicher, dass alle Pfade richtig angegeben sind.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Konfiguration des Plugins]]

*'''appium''': Geben Sie hier den Pfad zur ausführbaren Datei an mit der Appium in der Kommandozeile gestartet werden kann. Unter Windows wird diese Datei in der Regel "<code>appium.cmd</code>" heißen. Dieser Pfad wird benutzt, wenn expecco einen Appium-Server startet.
*'''node''': Geben Sie hier den Pfad zur ausführbaren Datei an, die Node (auch "Node.js") startet. Dieser Pfad wird beim Starten eines Servers an Appium weitergegeben, damit Appium ihn unabhängig von der PATH-Variablen findet. Unter Windows heißt diese Datei in der Regel "<code>node.exe</code>".
*'''JAVA_HOME''': Geben Sie hier den Pfad zu einem JDK an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden. Um einzustellen, welches Java von expecco verwendet werden soll, setzen Sie diesen Pfad in den Einstellungen für die Java Bridge.
*'''ANDROID_HOME''': Geben Sie hier den Pfad zu einem SDK von Android an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden.
*'''adb''': Hier steht der Pfad zum adb-Befehl. Unter Windows heißt die Datei adb.exe. Diese wird von expecco beispielsweise verwendet, um die Liste der angeschlossenen Geräte zu erhalten. Diesen Pfad sollten Sie automatisch wählen lassen, da dann der Befehl im ANDROID_HOME-Verzeichnis verwendet wird. Dieser wird auch von Appium verwendet. Falls expecco und Appium jedoch verschiedene Versionen von adb verwenden kann es zu Konflikten kommen.
*'''android.bat''': Diese Datei wird nur benötigt, um damit den AVD und den SDK Manager zu starten. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.
*'''aapt''': Geben Sie hier den Pfad zum aapt-Befehl an. Unter Windows heißt diese Datei ''aapt.exe''. expecco verwendet aapt nur im Verbindungseditor, um das Paket und die Activities einer apk-Datei zu lesen. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | Konfiguration des JDKs]]

Ab expecco 2.11 gibt es das Feld ''Team-ID''. Wenn Sie iOS-Tests ausführen, tragen Sie hier die Team-ID Ihres Zertifikats ein. Diese wird für jede iOS-Verbindung verwendet, außer Sie setzen den Wert im Einzelfall in den Verbindungseinstellungen um. Wie Sie die Team-ID erhalten, lesen Sie im Abschnitt zur [[#Signierung|Signierung]] ber der Installation auf Mac OS. Mit expecco 2.10 können Sie die Team-ID nur für jede Verbindungseinstellung extra als Capability eintragen. Dazu müssen Sie jedoch die [[#Erweiterte_Ansicht|erweiterte Ansicht]] verwenden. Geben Sie hier die Capability ''xcodeOrgId'' an und setzen Sie als Wert die Team-ID des Zertifikats.

Die Einstellung zur Serveradresse unten auf der Seite bezieht sich auf das Verhalten des Verbindungseditors. Dieser prüft am Ende, ob die Serveradresse auf ''/wd/hub'' endet, da dies die übliche Form ist. Falls nicht, wird in einem Dialog gefragt, wie darauf reagiert werden soll. Das festgelegte Verhalten kann hier eingesehen und verändert werden.

Wechseln Sie ebenfalls zum Eintrag ''Java Bridge'' (s. Abb.). Hier muss der Pfad zu Ihrer Java-Installation angegeben werden, die von expecco benutzt wird. Tragen Sie hier ein JDK ein. Falls Sie unter Windows das aus dem Mobile Testing Supplement verwenden möchten, lautet der Pfad
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
Sie können auch die Systemeinstellungen verwenden.

== Android-Gerät vorbereiten ==
Wenn Sie ein Android-Gerät unter Windows anschließen benötigen Sie möglicherweise noch einen adb-Treiber für das Gerät. Einen passenden Treiber finden Sie üblicherweise auf der jeweiligen Webseite des Herstellers. Haben Sie den Universal-Treiber aus dem Mobile Testing Supplement installiert, sollte für die meisten Geräte bereits alles funktionieren. In einigen Fällen versucht auch Windows automatisch einen Treiber zu installieren, wenn Sie das Gerät zum ersten mal anschließen.
 
===USB-Debugging Einschalten===
'''Achtung:'''
Bevor Sie ein Mobilgerät mit dem Appium-Plugin ansteuern können, müssen Sie für dieses Debugging erlauben!

Für Android-Geräte finden Sie diese Option in den Einstellungen unter ''[https://www.droidwiki.org/wiki/Entwickleroptionen Entwickleroptionen]'' mit dem Namen ''[https://www.droidwiki.org/USB-Debugging USB-Debugging]''. Falls die Entwickleroptionen nicht angezeigt werden, können Sie diese freischalten, indem Sie unter "''Über das Telefon''" siebenmal auf "''Build-Nummer''" tippen.

===Wach bleiben Aktivieren===
Aktivieren Sie auch die Funktion ''Wach bleiben'', damit das Gerät nicht während der Testerstellung oder -ausführung den Bildschirm abschaltet.

Aus Sicherheitsgründen muss USB-Debugging für jeden Computer einzeln zugelassen werden. Beim Verbinden des Geräts mit dem PC über USB müssen Sie dabei am Gerät der Verbindung zustimmen. Falls Sie dies für Ihren Computer noch nicht getan haben, aber auf dem Gerät kein entsprechender Dialog erscheint, kann es helfen, das Gerät aus- und wieder einzustecken. Das kann insbesondere dann passieren, wenn Sie den ADB-Treiber installiert haben während das Gerät bereits über USB angeschlossen war. Falls auch das nicht hilft, öffnen Sie die Benachrichtigungen, indem Sie sie vom oberen Bildschirmrand herunter ziehen. Dort finden Sie die USB-Verbindung und Sie können die Optionen dazu öffnen. Wählen Sie einen anderen Verbindungstypen aus; in der Regel sollten MTP oder PTP funktionieren.

Sie können auch auf einem Emulator testen. Dieser muss nicht gesondert vorbereitet werden, da er bereits für USB-Debugging ausgelegt ist. Es ist sogar möglich, einen Emulator bei Testbeginn zu starten.

Um zu überprüfen, ob ein Gerät, das Sie an Ihren Rechner angeschlossen haben, verwendet werden kann, öffnen Sie den [[#Verbindungseditor|Verbindungseditor]]. Das Gerät sollte dort angezeigt werden.

=== Verbindung über WLAN ===
Es ist auch möglich, Android-Geräte über WLAN zu verbinden. Für Geräte mit Android 11 oder neuer ist dies direkt über WLAN möglich, im anderen Fall müssen Sie das Gerät zuerst über USB verbinden. Ab expecco 22.1 können Sie eine WLAN-Verbindung über den [[Mobile Testing Plugin#Verbindungseditor|Verbindungseditor]] aufbauen. Ansonsten ist es auch über die Eingabeaufforderung möglich.
==== Drahtlos verbinden über die Eingabeaufforderung mit expecco Versionen vor 22.1 (ab Android 11) ====
Mit expecco ab Version 22.1 funktioniert das einfacher über den Verbindungseditor.

Erlauben Sie in den Entwickleroptionen des Geräts Debugging über WLAN und öffnen Sie dessen Optionen. Sie müssen zuerst das Gerät mit dem Rechner koppeln. Wählen Sie dazu "''Gerät mit einem Kopplungscode koppeln''", um einen Kopplungscode und eine IP-Adresse mit Port zu erhalten. Öffnen Sie dann auf dem Rechner die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb pair <IP-Adresse des Geräts>:<Kopplungsport></nowiki>
wobei Sie <tt><IP-Adresse des Geräts>:<Kopplungsport></tt> durch die auf dem Gerät angezeigte IP-Adresse & Port ersetzen. Danach werden Sie aufgefordert, den Kopplungscode einzugeben. Wenn alles geklappt hat, sollte sich das Popup auf dem Gerät schließen und der Rechner als gekoppeltes Gerät angezeigt werden. Geben Sie dann in der Eingabeaufforderung ein:
<nowiki>adb connect <IP-Adresse des Geräts>:<Debug-Port></nowiki>
Die IP-Adresse ist hier noch die gleiche wie beim Koppeln, aber der Port ist ein anderer. Beides wird als IP-Adresse & Port auf dem Gerät angezeigt. Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie entweder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden. Häufig wird beim Neustart des Geräts auch die Erlaubnis für das Debugging über WLAN wieder zurückgesetzt und der verwendete Port ändert sich. Die Kopplung bleibt aber bestehen und muss beim nächsten Verbinden nicht noch einmal durchgeführt werden.

==== WLAN Verbindung über USB starten (Android 10 und früher) ====
Verbinden Sie zunächst das Gerät über USB mit dem Rechner. Öffnen Sie dann die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb tcpip 5555</nowiki>
Damit lauscht das Gerät auf eine TCP/IP-Verbindung an Port 5555. Sollten Sie mehrere Geräte angeschlossen oder Emulatoren laufen haben, müssen Sie genauer angeben, welches Gerät Sie meinen. Geben Sie in diesem Fall ein:
<nowiki>adb devices -l</nowiki>
Sie erhalten eine Liste aller Geräte, wobei die erste Spalte deren Kennung ist. Schreiben Sie dann stattdessen
<nowiki>adb -s <Gerätekennung> tcpip 5555</nowiki>
mit der Gerätekennung des gewünschten Geräts. Sie können die USB-Verbindung nun trennen. Jetzt müssen Sie die IP-Adresse Ihres Gerätes in Erfahrung bringen. Sie finden diese üblicherweise irgendwo in den Einstellungen des Geräts, beispielsweise beim Status oder in den WLAN-Einstellungen. Geben Sie dann ein:
<nowiki>adb connect <IP-Adresse des Geräts></nowiki>
Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie wieder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden.

=== Verbindung zu einem Emulator ===
Sie benötigen dazu den Emulator selbst, sowie mindestens ein AVD (Android Virtual Device). Hinweise zu Installation finden Sie in der [https://developer.android.com/studio/run/emulator Android Studio Dokumentation].

Wenn Sie Android Studio bereits mit den Defaulteinstellungen installiert haben 1), sollte der Emulator bereits mitinstalliert sein. Falls nicht, wählen Sie in Android Studio "''Configure''" - "''SDK Manager''" - "''Android SDK''" - "''SDK Tools''" - ''Android Emulator''", sowie dort die "''Platform Tools''".
Alternativ geht das auch über die Kommandzeile mit dem "sdkmanager" Kommando.

Als nächstes benötigen Sie mindestens ein AVD; auch dies geht am einfachsten über den Dialog in Android Studio:
wählen sie "''Configure''" - "''AVD Manager''" und folgen den Anweisungen (Deviceauswahl, Platform und Android Version).

Auch wenn Sie den Emulator automatisieren benötigen sie Appium; installieren Sie dieses entweder mit dem Mobile Testing Supplement, oder direkt von der Appium homepage (https://github.com/appium/appium-desktop/releases).

1)Android Studio selbst wird nicht von expecco benötigt; es bietet aber kompfortable Dialoge zum Installieren von Paketen und AVDs.

== iOS-Gerät und App vorbereiten ==
Das Ansteuern von iOS-Geräten ist nur über einen Mac möglich. Lesen Sie daher auch den Abschnitt zur [[#Mac_OS|Installation unter Mac OS]].

Bevor Sie ein Mobilgerät mit dem Mobile Testing Plugin ansteuern können, müssen Sie für iOS-Geräte ab iOS 8 Debugging erlauben. Aktivieren Sie dazu die Option ''Enable UI Automation'' unter dem Menüpunkt ''Entwickler'' in den Einstellungen des Geräts. Falls Sie den Eintrag ''Entwickler'' in den Einstellungen nicht finden, gehen Sie wie folgt vor: Schließen Sie das Gerät über USB an den Mac an. Dabei müssen Sie ggf. am Gerät noch der Verbindung zustimmen. Starten Sie Xcode und wählen Sie dann in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie dort Ihr Gerät aus. Danach sollte der Eintrag ''Entwickler'' in den Einstellungen auf dem Gerät auftauchen. Dazu müssen Sie möglicherweise die Einstellungen beenden und neu starten.

[[Datei:Alert.png | thumb | 270px | Beispiel für einen Alert unter iOS]]
Ein Verbindungsaufbau zu dem Gerät ist nicht möglich solange es bestimmte Alerts zeigt. Ein solcher Alert kann z. B. erscheinen wenn FaceTime aktiviert ist, indem ein Hinweis auf anfallende SMS-Gebühren angezeigt wird (siehe Screenshot). Achten Sie darauf, das Gerät so zu konfigurieren, dass es im Leerlauf keine solchen Alerts zeigt.

=== expecco 2.11 und später ===
Sie können beliebige Apps testen, die auf dem verwendeten Gerät lauffähig oder bereits installiert sind. Wenn die App als Development-Build vorliegt, muss die UDID des Geräts in der App hinterlegt sein. In jedem Fall muss der WebDriverAgent für das Gerät signiert werden. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]] unter Mac OS.

Falls Sie in einem Test den Home-Button verwenden wollen, müssen Sie auf dem Gerät AssistiveTouch aktivieren. Sie finden diese Option in den Einstellungen unter ''Allgemein'' > ''Bedienungshilfen'' > ''AssistiveTouch''. Platzieren Sie dann das Menü in der Mitte des oberen Bildschirmrands. Sie können das Drücken des Home-Buttons dann mit dem entsprechenden Menüeintrag im Recorder aufzeichnen oder direkt den Baustein ''Press Home Button'' benutzen.

=== expecco 2.10 ===
Die App, die Sie verwenden wollen, muss als Development-Build vorliegen. Außerdem muss die UDID des Geräts in der App hinterlegt sein.

=== Development-Build signieren ===
Ein Development-Build einer App ist nur für eine begrenzte Zahl von Geräten zugelassen und kann auf anderen Geräten nicht gestartet werden. Es ist aber möglich, das Zertifikat und die verwendbaren Geräte in einem Development-Build auszutauschen.

* Evaluierung mit Demo-App von eXept:
:Gerne stellen wir Ihnen eine Demo-App zur Verfügung, die als Development-Build vorliegt und die wir für Ihr Gerät signieren können. Senden Sie dazu bitte Ihrem eXept-Ansprechpartner die UDID Ihres Gerätes zu. Wie Sie die UDID Ihres Gerätes ermitteln können, ist im folgenden Abschnitt beschrieben.

* Eigene App für Ihr Testgerät verwenden:
:Wenn Sie von den App-Entwicklern einen Development-Build (IPA-Datei) erhalten, der für Ihr Testgerät zugelassen ist, können Sie diesen direkt verwenden. Dazu müssen Sie den Entwicklern die UDID Ihres Geräts mitteilen, damit sie diese eintragen können. '''Sie können die UDID eines Gerätes mithilfe von Xcode auslesen'''. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie Ihr Gerät aus und suchen Sie in Eigenschaften den Eintrag ''Identifier''. Die UDID ist eine 40-stellige Hexadezimalzahl.

* Extern entwickelte App für Ihr Testgerät umsignieren:
:Es können auch Apps umsigniert werden, damit Sie auf anderen Geräten lauffähig sind. Dieser Vorgang ist jedoch kompliziert und setzt insbesondere einen Zugang zu einem Apple-Developer-Account voraus. Eine Dokumentation zur Vorgehensweise ist derzeit in Vorbereitung.

:Für die Evaluierung unterstützen wir Sie gerne beim Umsignieren Ihrer App.


Weitere Informationen zur Verwendung von iOS-Geräten finden Sie auch in der [http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Dokumentation von Appium].

=== Native iOS-Apps ===
Sie können auch Apps verwenden, die bereits nativ auf dem Gerät vorhanden sind. Dazu müssen Sie deren Bundle-ID kennen und diese dann in die Verbindungseinstellungen eintragen. Hier eine kleine Auswahl gängiger Apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

Weitere Bundle-IDs finden Sie [https://github.com/joeblau/apple-bundle-identifiers hier].

= Beispiele =
Bei den Demo-Testsuiten für expecco finden Sie auch Beispiele für Tests mit dem Mobile Testing Plugin. Wählen Sie dazu auf dem Startbildschirm die Option "''Beispiel aus Datei''" und öffnen Sie den Ordner "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
Die Testsuite enthält zwei einfache Testpläne: "''Simple CalculatorTest''" und "''Complex Calculator and Messaging Test''". Beide Tests verwenden einen Android-Emulator, den Sie vor Beginn starten müssen. Die Apps, die im Test verwendet werden, gehören zur Grundausstattung des Emulators und müssen daher nicht mehr installiert werden. Da sich die Apps unter jeder Android-Version unterscheiden können, ist es wichtig, dass Ihr Emulator unter Android 6.0 läuft. Außerdem muss die Sprache auf Englisch gestellt sein.

; Simple CalculatorTest
: Dieser Test verbindet sich mit dem Taschenrechner und gibt die Formel ''2+3'' ein. Das Ergebnis des Rechners wird mit dem erwarteten Wert ''5'' verglichen.

; Complex Calculator and Messaging Test
: Dieser Test verbindet sich mit dem Taschenrechner und öffnet anschließend den Nachrichtendienst. Dort wartet er auf eine einkommende Nachricht von der Nummer ''15555215556'', in der eine zu berechnende Formel gesendet wird. Die Nachricht wird zuvor über einen Socket beim Emulator erzeugt. Nach dem Eintreffen der Nachricht wird diese vom Test geöffnet und deren Inhalt gelesen. Danach wird wieder der Taschenrechner geöffnet, die erhaltene Formel eingegeben und das Ergebnis gelesen. Anschließend wechselt der Test wieder zum Nachrichtendienst und sendet das Ergebnis als Antwort.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
Diese sind Bestandteil des Tutorials zum Mobile Testing Plugin. Der jeweils enthaltene Testfall ist unvollständig und wird im Zuge des Tutorials ergänzt. Lesen Sie dazu den Abschnitt [[#Tutorial|Tutorial]].

= Tutorial =
Es gibt ein Tutorial, das das grundsätzliche Vorgehen zur Erstellung von Tests mit dem Mobile Testing Plugin beschreibt. Grundlage dafür ist ein mitgeliefertes Beispiel, bestehend aus einer einfachen App und einer expecco-Testsuite.

Sie finden es auf der Seite [[Mobile_Testing_Tutorial|Mobile Testing Tutorial]] in zwei Versionen für Android und für iOS.
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_Android|Erste Schritte mit Android]]
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_iOS|Erste Schritte mit iOS]]

= Dialoge des Mobile Testing Plugins =
== Verbindungseditor ==
Mithilfe des Verbindungseditors können Sie schnell Verbindungen definieren, ändern oder aufbauen. Je nach Aufgabe weist der Dialog kleine Unterschiede auf und wird unterschiedlich geöffnet:
*Um eine Verbindung aufzubauen, klicken Sie im GUI-Browser auf "''Verbinden'"' klicken und wählen dann "''Mobile Testing''".
*Um eine bestehende Verbindung im GUI-Browser zu ändern oder zu kopieren, wählen Sie diese aus, machen einen Rechtsklick und wählen im Kontextmenü "''Verbindung bearbeiten''" oder "''Verbindung kopieren''" aus.
*Wollen Sie Verbindungseinstellungen nicht für den GUI-Browser sondern zur Verwendung in einem Test erstellen, wählen Sie im Menü des Mobile Testing Plugins den Punkt "''Verbindungseinstellungen erstellen...''". Darüber können nur die Einstellungen für eine Verbindung erstellt werden, ohne dass eine Verbindung tatsächlich angelegt wird.

Einige der Schaltflächen sind nur beim Erstellen von Verbindungseinstellungen sichtbar:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#"''Einstellungen löschen''": Setzt alle Einträge zurück. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Einstellungen aus Datei laden''": Erlaubt das Öffnen einer gespeicherten Einstellungsdatei (*.csf). Deren Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen aus Anhang laden''": Erlaubt das Öffnen eines Anhangs mit Verbindungseinstellungen aus einem geöffneten Projekt. Diese Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen in Datei speichern''" sowie
#"''Einstellungen in Anhang speichern''": Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern oder als Anhang in einem geöffneten Projekt anlegen. Beide Optionen besitzen ein verzögertes Menü, in dem Sie auswählen können, nur einen bestimmten Teil der Einstellungen zu speichern. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Erweiterte Ansicht''": Damit können Sie in die erweiterte Ansicht wechseln, um zusätzliche Einstellungen vorzunehmen. Lesen Sie dazu mehr am Ende des Kapitels. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Hilfe''": An der rechten Seite wird ein Hilfetext zum jeweiligen Schritt ein- oder ausgeblendet.

Der Dialog ist in drei Schritte unterteilt. Im ersten Schritt wählen Sie das Gerät, das Sie verwenden möchten, im zweiten Schritt wählen Sie aus, welche App verwendet werden soll und im letzten Schritt erfolgen die Einstellungen zum Appium-Server.

===Schritt 1: Gerät auswählen===
Im oberen Teil erhalten Sie eine Liste aller angeschlossenen Appium-Geräte, die erkannt werden. Mit der Checkbox darunter können Sie die Geräte ausblenden, die zwar erkannt werden, aber nicht bereit sind. Falls Sie ein Gerät eintragen wollen, das nicht angeschlossen ist, können Sie dies mit dem entsprechenden Knopf "''Android-Gerät eingeben''" bzw. "''iOS-Gerät eingeben''" anlegen. Dazu müssen Sie jedoch die benötigten Eigenschaften Ihres Geräts kennen. Das Gerät wird dann in einer zweiten Geräteliste angelegt und kann dort ausgewählt werden. Wenn keine Liste mit angeschlossenen Elementen angezeigt werden kann, werden stattdessen verschiedene Meldungen angezeigt:
*Keine Geräte gefunden
*:expecco konnte kein Android-Geräte finden.
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*Keine verfügbaren Geräte gefunden
*:expecco konnte keine verfügbaren Android-Geräte finden. Es wurden aber nicht verfügbare gefunden, z.B. mit dem Status "unauthorized".
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*:Um nicht verfügbare Geräte anzuzeigen, aktivieren Sie unten diese Option.
*Verbindung verloren
*:expecco hat die Verbindung zum adb-Server verloren. Versuchen Sie die Verbindung wieder herzustellen, indem Sie auf den Button klicken.
*Verbindung fehlgeschlagen
*:expecco konnte sich nicht mit dem adb-Server verbinden. Möglicherweise läuft er nicht oder der angegebene Pfad stimmt nicht.
*:Überprüfen Sie die adb-Konfiguration in den Einstellungen und versuchen Sie den adb-Server zu starten und eine Verbindung herzustellen indem Sie auf den Knopf klicken.
*Verbinden ...
*:expecco verbindet sich mit dem adb-Server. Dies kann einige Sekunden dauern.
*adb-Server starten ...
*:expecco startet den adb-Server. Dies kann einige Sekunden dauern.

Mit "''Weiter''" gelangen Sie zum nächsten Schritt. Wenn Sie Einstellungen für den GUI-Browser eingeben, ist das erst möglich, wenn ein Gerät ausgewählt wurde.

Anmerkung zum Freischalten: In jüngeren Android Versionen werden die Entwickleroptionen zunächst nicht mehr in den Einstellungen angeboten. Falls ihr Android Gerät in den Einstellungen keinen Eintrag zu "''Entwickleroptionen''" zeigt, wählen Sie zunächst den Eintrag "''Telefoninfo''", dann "''SoftwareVersionsInfo''" und klicken darin mehrfach auf den Eintrag "''BuildVersion''".

==== Chromedriver verwalten ====
Wenn die App, die Sie bedienen wollen, WebViews mit Chrome benutzt, benötigt Appium Zugriff auf einen passenden Chromedriver. Wenn Sie ein Gerät in der Liste auswählen, können Sie über "''Chromedriver verwalten''" sehen, welche Chrome-Versionen auf dem Gerät vorhanden sind und welche Chromedriver-Versionen durch expecco zur Verfügung stehen. Über diesen Dialog können Sie auch benötigte Chromedriver-Versionen herunterladen. Beachten Sie, dass auf dem Gerät verschiedene Chrome-Versionen vorhanden sein können, da die Apps in ihren WebViews nicht die gleiche Chrome-Version verwenden müssen, wie die als Browser installierte. Damit alles funktioniert, sollte der verwendete Chromedriver zur entsprechenden App passen. Sie können den Pfad zum Chromedriver auch am Ende des Verbindungsdialogs in den erstellten Capabilities ändern.

==== WLAN-Android-Geräte verbinden ====
Sie können sich auch über WLAN zu Android-Geräten verbinden. Dazu muss das Gerät zunächst mit adb verbunden werden, siehe [[Mobile_Testing_Plugin#Verbindung_.C3.BCber_WLAN|Verbindung über WLAN]]. Ab expecco 22.1 bietet der Verbindungseditor hierfür einen Dialog, der Ihnen dabei hilft und den Sie anstatt der Eingabeaufforderung verwenden können. Für Geräte mit Android 11 oder höher können Sie hier das Gerät mit dem Rechner zu koppeln, indem Sie die entsprechenden Parameter angeben und anschließend die Verbindung unter Angabe von IP-Adresse und Port aufbauen. Sie können damit auch für Geräte, die über USB verbunden sind, eine WLAN-Verbindung aufbauen. Wenn Sie das entsprechende Gerät in der Liste auswählen, werden die benötigten Angaben automatisch ausgelesen.

Beachten Sie, dass der Aufbau einer WLAN-Verbindung nicht Teil der Verbindungseinstellungen ist. Wenn Sie mit den erzeugten Einstellungen eine neue Verbindung aufbauen wollen, müssen Sie sicherstellen, dass das Gerät über mit der angegebenen IP-Adresse und dem Port mit adb verbunden ist, damit es gefunden wird. Die ADB-Verbindung geht verloren, wenn der ADB-Server oder das Gerät neu gestartet werden. Die Erlaubnis für das WLAN-Debugging wird beim Neustart des Geräts auch häufig zurückgesetzt und der Debug-Port kann dann wechseln. Daher muss eine WLAN-Verbindung immer manuell hergestellt werden.

===Schritt 2: App auswählen===
Hier können Sie Angaben zur App machen, die getestet werden soll. Dabei können Sie entscheiden, ob Sie eine App verwenden wollen, die bereits auf dem Gerät installiert ist, oder ob für den Test eine App installiert werden soll. Wählen Sie oben den entsprechenden Reiter aus. Je nachdem, ob Sie im vorigen Schritt ein Android- oder ein iOS-Gerät ausgewählt haben, ändert sich die erforderte Eingabe.

*'''Android'''
**''App auf dem Gerät''
**:Wenn Sie im ersten Schritt ein angeschlossenes Gerät ausgewählt haben, werden die Pakete aller installierten Apps automatisch abgerufen und Sie können die Auswahl aus den Drop-down-Listen treffen. Die installierten Apps sind in Fremdpakete und Systempakete unterteilt; wählen Sie die entsprechende Paketliste aus. Diese Auswahl gehört nicht zu den Einstellungen, sondern stellt nur die entsprechende Paketliste zur Verfügung. Sie können den Filter benutzen, um die Liste weiter einzuschränken und dann das gewünschte Paket auswählen. Die Activities des ausgwählten Pakets werden ebenfalls automatisch abgerufen und als Drop-down-Liste zur Verfügung gestellt. Wählen Sie die Activity aus, die gestartet werden soll. In der Regel wird automatisch eine Activity aus der Liste eingetragen. Falls Sie kein verbundenes Gerät verwenden, müssen Sie die Eingabe des Pakets und der Activity von Hand vornehmen.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Benutzen Sie einen lokalen Appium-Server, können Sie den rechten Butten benutzen, um zu der Installationsdatei der App zu navigieren und diesen Pfad einzutragen. Wenn möglich werden dabei auch das entsprechende Paket und die Activity in den Feldern darunter eingetragen. Diese Angabe ist aber nicht notwendig.

*'''iOS'''
**''App auf dem Gerät''
**:Geben Sie die Bundle-ID einer installierten App an. Sie können die IDs der installierten Apps bspw. mithilfe von Xcode erfahren. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü "''Window''" den Eintrag "''Devices''". Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wenn Sie Ihr Gerät auswählen, sehen Sie in der Übersicht eine Auflistung der von Ihnen installierten Apps.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Zu den Vorraussetzungen an Apps für reale Geräte lesen Sie bitte den Abschnitt [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Geräte und App vorbereiten]].

Im unteren Teil können Sie festlegen, ob die App beim Verbindungsabbau zurückgesetzt bzw. deinstalliert werden soll, und ob sie initial zurückgesetzt werden soll. Auch hier wird die entsprechende Capability gar nicht gesetzt, wenn Sie "''(Default)''" auswählen. Mit "''Weiter''" gelangen Sie zum nächsten Schritt.

===Schritt 3: Servereinstellungen===
Im letzten Schritt befindet sich zunächst im oberen Teil eine Liste aller Capabilities, die sich aus Ihren Angaben der vorigen Schritte ergeben. Wenn Sie sich mit Appium auskennen und noch zusätzliche Capabilities setzen möchten, die der Verbindungseditor nicht abdeckt, können Sie durch Klicken auf "''Bearbeiten''" in die erweiterte Ansicht gelangen. Lesen Sie dazu den Abschnitt weiter unten.

Wenn Sie Einstellungen für den GUI-Browser eingeben, können Sie den ''Verbindungsnamen'' eintragen, mit dem die Verbindung angezeigt wird. Dies ist auch der Name unter dem Bausteine diese Verbindung verwenden können, wenn sie aufgebaut ist. Wenn Sie das Feld frei lassen, wird ein Name generiert. Wenn der Haken für "''Von expecco gesteuert''" gesetzt ist, wird expecco einen lokalen Appium-Server an einem freien Port starten, oder einen bereits gestarteten freien Server verwenden. Um einen eigenen Server zu verwenden, schalten Sie diese Funktion ab und geben Sie die entsprechende Adresse ein. Sie erhalten die lokale Standard-Adresse und bereits verwendete Adressen zur Auswahl.

In älteren expecco-Versionen ist der Haken mit "''Bei Bedarf starten''" beschriftet. In diesem Fall müssen Sie auch eine Adresse angeben, wenn expecco den Server starten soll. expecco versucht dann beim Verbinden einen Appium-Server an der angegebenen Adresse zu starten, wenn dort noch keiner läuft. Dieser Server wird dann beim Beenden der Verbindung ebenfalls heruntergefahren. Dies funktioniert nur für lokale Adressen. Achten Sie darauf, nur Portnummern zu verwenden, die auch frei sind. Verwenden Sie am besten nur ungerade Portnummern ab dem Standardport 4723. Beim Verbindungsaufbau wird ebenfalls die folgende Portnummer verwendet, wodurch es sonst zu Konflikten kommen könnte.

Je nachdem, wie Sie den Dialog geöffnet haben, gibt es nun verschiedene Schaltflächen um ihn abzuschließen. In jedem Fall haben Sie die Option zu speichern. Dabei öffnet sich ein Dialog, indem Sie entweder ein geöffnet Projekt auswählen können, um die Einstellungen dort als Anhang zu speichern, oder auswählen es in einer Datei zu speichern, die Sie anschließend angeben können. Durch das Speichern wird der Dialog nicht beendet, wodurch Sie anschließend noch eine andere Option auswählen könnten.

Wenn Sie den Editor zum Verbindungsaufbau geöffnet haben, können Sie abschließend auf "''Verbinden''" oder "''Server starten und verbinden''" klicken, je nachdem, ob der Haken für den Serverstart gesetzt ist. Für das Ändern oder Kopieren einer Verbindung im GUI-Brower heißt diese Option "''Übernehmen''", da in diesem Fall nur der Verbindungseintrag geändert bzw. neu angelegt wird, der Verbindungsaufbau aber nicht gestartet wird. Das können Sie bei Bedarf anschließend über das Kontextmenü tun. Falls Sie Capabilities einer bestehenden Verbindung geändert haben, fordert Sie anschließend ein Dialog auf zu entscheiden, ob diese Änderungen direkt übernommen werden sollen, indem die Verbindung abgebaut und mit den neuen Verbindungen aufgebaut wird, oder nicht. In diesem Fall werden die Änderungen erst wirksam, nachdem Sie die Verbindung neu aufbauen.

Zur Verwendung des Verbindungseditors lesen Sie auch den entsprechenden Abschnitt im jeweiligen Tutorial in Schritt 1 (Android: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren|Demo ausführen]], iOS: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren_.28iOS.29|Demo ausführen (iOS)]]).

===Erweiterte Ansicht===
Die erweiterte Ansicht des Verbindungseditors erhalten Sie entweder durch Klicken auf "''Bearbeiten''" im dritten Schritt oder jederzeit über den entsprechenden Menüeintrag, wenn Sie den Editor über das Plugin-Menü gestartet haben. In dieser Ansicht erhalten Sie eine Liste aller eingestellten Appium-Capabilities. Zu dieser können Sie weitere hinzufügen, Einträge ändern oder entfernen. Um eine Capability hinzuzufügen, wählen Sie diese aus der Drop-down-Liste des Eingabefelds aus. In dieser befinden sich alle bekannten Capabilities sortiert in die Kategorien ''Common'', ''Android'' und ''iOS''. Haben Sie eine Capability ausgewählt, wird ein kurzer Informationstext dazu angezeigt. Sie können in das Feld auch von Hand eine Capability eingeben. Klicken Sie dann auf "''Hinzufügen''", um die Capabilitiy in die Liste einzutragen. Dort können Sie in der rechten Spalte den Wert setzen. Um einen Entrag zu löschen, wählen Sie diesen aus und klicken Sie auf "''Entfernen''". Mit "''Zurück''" verlassen Sie die erweiterte Ansicht.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Laufende Appium-Server ==
Im Menü des Mobile Testing Plugins finden Sie den Eintrag "''Appium-Server...''". Mit diesem öffnen Sie ein Fenster mit einer Übersicht aller Appium-Server, die von expecco gestartet wurden und auf welchem Port diese laufen. Durch Klicken auf das Icon in der Spalte "''Log anzeigen''" können Sie das Logfile des entsprechenden Servers anschauen. Dieses wird beim Beenden des Servers wieder gelöscht. Mit den Icons in der Spalte "''Beenden''" kann der entsprechenden Server beendet werden. Allerdings wird dies verhindert, wenn expecco über diesen Server noch eine offene Verbindung hat. Für welche Verbindung ein Server verwendet wird, sehen Sie in der rechten Spalte. Steht dort ''<idle>'' wird er zur Zeit nicht von expecco verwendet.

[[Datei:MobileTestingAppiumServer.png]]

Beim Öffnen des Editors um eine Appium-Verbindung aufzubauen, wird direkt ein Appium-Server gestartet, um den folgenden Verbindungsaufbau zu beschleunigen. Zu diesem Zweck hält sich expecco auch immer einen freien Appium-Server offen. Weitere laufende Server, die nicht mehr verwendet werden, werden jedoch nach einiger Zeit automatisch beendet.

Im Menü des Mobile Testing Plugins finden Sie auch den Eintrag "''Alle Verbindungen und Server beenden''". Dies ist für den Fall gedacht, dass Verbindungen oder Server auf andere Weise nicht beendet werden können. Beenden Sie Verbindungen wenn möglich immer im GUI-Browser oder durch Ausführen eines entsprechenden Bausteins. Server, die Sie in der Server-Übersicht gestartet haben, beenden Sie dort; Server, die mit einer Verbindung gestartet wurden, werden automatisch mit dieser beendet.

Beachten Sie, dass in der Übersicht nur Server aufgelistet sind, die von expecco gestartet und verwaltet werden. Mögliche andere Appium-Server, die auf andere Art gestartet wurden, werden nicht erkannt.

== Recorder ==
Besteht im GUI-Browser eine Verbindung zu einem Gerät, kann der integrierte Recorder verwendet werden, um mit diesem Gerät einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

[[Datei:MobileTestingRecorder.png|caption|]]

====Komponenten des Recorderfensters====
#'''Aufnahme fortsetzen/pausieren''': Über das rechte Symbol können Sie die Aufnahme pausieren. Sie sehen dann ein großes Pause-Symbol in der Anzeige. Alle Aktionen, die Sie währenddessen im Recorder machen werden zwar ausgeführt, es werden aber keine Bausteine aufgezeichnet. Über das linke Symbol können Sie dann wieder in den normalen Aufnahmemodus wechseln.
#'''Aufnahme stoppen''': Stoppt die Aufnahme und schließt das Recorderfenster.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Gerät. Dies wird nötig, wenn das Gerät zur Ausführung einer Aktion länger braucht oder sich etwas ohne das Anstoßen durch den Recorder ändert. Seit expecco 21.2 gibt es hier zusätzlich ein Untermenü, mit dem automatisches Aktualisieren angeschaltet werden kann, indem im Hintergrund auf Änderungen geprüft wird (siehe auch ''Automatisches Aktualisieren'' weiter unten).
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Elemente einzeichnen''': Die Rahmen aller Elemente der Ansicht werden angezeigt.
#'''Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst. Dabei stehen folgende Aktionen zur Verfügung:
#*Aktionen auf Elemente:
#**Klicken: Kurzer Klick auf das Element, über dem der Cursor steht. Zur genaueren Bestimmung, welches Element verwendet wird, benutzen Sie die Funktion Follow-Mouse oder Element-Highlighting.
#**Antippen mit Dauer (Element): Ähnlich zum Klicken, nur dass zusätzlich die Dauer des Klicks aufgezeichnet wird. Dadurch sind auch längere Klicks möglich.
#**Antippen mit Position (Element): Ähnlich zum Klicken, aber zusätzlich wird die Position innerhalb des Elements aufgenommen. Die Position kann relativ zur Größe des Elements aufgenommen werden oder, wenn Sie dabei Strg gedrückt halten, absolut zur linken oberen Ecke des Elements.
#**Text setzen: Ermöglicht das Setzen eines Textes in Eingabefelder.
#**Text löschen: Löscht den Text eines Eingabefelds.
#*Aktionen auf das Gerät:
#**Antippen (Bildschirm): Löst einen Klick auf die Bildschirmposition aus.
#**Antippen mit Dauer (Bildschirm): Löst einen Klick auf die Bildschirmposition aus, bei dem auch die Dauer berücksichtigt wird.
#**Wischen: Wischen in einer geraden Linie vom Punkt des Drückens des Mausknopfes bis zum Loslassen. Die Dauer wird ebenfalls aufgezeichnet.
#:Beachten Sie bei diesen Aktionen, dass das Ergebnis sich auf verschiedenen Geräten unterscheiden kann, bspw. bei verschiedenen Bildschirmauflösungen.
#*Erstellen von Testablauf-Bausteinen
#**Attribut prüfen: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Das Ergebnis triggert den entsprechenden Ausgang.
#**Attribut zusichern: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Bei Ungleichheit schlägt der Test fehl.
#**Attribut holen: Liest den aktuellen Wert eines Attributs aus.
#*Automatisch
#:Ist das Auto-Werkzeug ausgewählt, können alle Aktionen durch spezifische Eingabeweise benutzt werden: ''Klicken'', ''Element antippen'' und ''Wischen'' funktionieren weiterhin durch Klicken, wobei sie anhand der Dauer und der Bewegung des Cursors unterschieden werden. Um ein ''Antippen'' auszulösen, halten Sie beim Klicken Strg gedrückt. Die übrigen Aktionen erhalten Sie durch einen Rechtsklick auf das Element in einem Kontextmenü.
#'''Kontext-Aktionen''': Hier können Sie Aktionen aufzeichnen, die Kontexte betreffen:
#*Zu Kontext wechseln: Bietet eine Liste der aktuell verfügbaren Kontexte und Sie können auswählen, zu welchem gewechselt werden soll.
#*Aktuellen Kontext holen: Holt den Handle des aktuellen Kontexts.
#*Kontext-Handles holen: Holt eine Liste aller aktuell verfügbaren Kontext-Handles.
#'''Softkeys''': Nur unter Android. Simuliert das Drücken der Knöpfe Zurück, Home, Fensterliste und Power.
#'''Home-Button''': Nur unter iOS ab expecco 2.11. Ermöglicht das Drücken des Home-Buttons. Vor expecco 19.2 funktioniert es nur, wenn AssistiveTouch aktiviert ist und sich das Menü in der Mitte des oberen Bildschirmrands befindet. Ab expecco 19.2 verwendet die Funktion kein AssistiveTouch mehr.
#'''Hilfe''': Öffnet diese Online-Dokumentation auf der allgemeinen Seite zu [[GuiBrowser_Recorder|GUI-Browser Recordern]].
#'''Anzeige''': Zeigt einen Screenshot des Geräts. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Ansicht anpassen''': Öffnet einen Dialog um die Ansicht anzupassen, falls expecco das Bild nicht richtig darstellt. Sie können die Skalierung anpassen oder das Bild um 90° drehen.
#'''Ausrichtung anpassen''': Korrigiert das Bild, falls dieses auf dem Kopf stehen sollte. Über den Pfeil rechts daneben kann das Bild auch um 90° gedreht werden, falls dies einmal nötig sein sollte. Ab expecco 19.1 finden Sie diese Funktion in ''Ansicht anpassen''. Die Ausrichtung des Bildes ist für die Funktion des Recorders unerheblich, dieser arbeitet ausschließlich auf den erhaltenen Elementen.
#'''Skalierung''': Ändert die Skalierung des Screenshots.
#'''Meldungen''': Zeigt den Pfad des ausgewählten Elements oder andere Meldungen an. Es gibt ein Kontextmenü, um eine Liste der vorigen Meldungen zu sehen.

====Verwendung====
Mit jedem Klick im Fenster wird eine Aktion ausgelöst und im Arbeitsbereich des GUI-Browsers aufgezeichnet. Dort können Sie das Aufgenommene abspielen, editieren oder daraus einen neuen Baustein erstellen.
Aktionen zum Auslösen von Sofkeys finden Sie direkt in der Menüleiste (s.o.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Werkzeugs in der Menüleiste (s.o.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion.
Zur Verwendung des Recorders lesen Sie auch Schritt 2 im Tutorial ([[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen|Android]] bzw. [[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen_.28iOS.29|iOS]]).

====Elemente verbergen====
Ab expecco 21.2 gibt es im Kontextmenü außerdem die Möglichkeit, das ausgewählte Element im Recorder zu verbergen. Das bedeutet, dass dieses Element fortan nicht mehr ausgewählt werden kann. Diese Funktion eignet sich dazu, Elemente zu ignorieren, die im Vordergrund liegen, um auf Elemente darunter zugreifen zu können. Um diesen Zustand wieder rückgängig zu machen, müssen Sie das entsprechende Element im Baum des GUI-Browsers finden, dort gibt es im Kontextmenü ebenfalls einen solchen Eintrag.

====Automatisches Aktualisieren====
Der Recorder zeigt kein Livebild des Geräts sondern nur eine Momentaufnahme. Um mit der Anzeige auf dem Gerät übereinzustimmen muss daher nach Änderungen aktualisiert werden. Der Recorder aktualisiert sich automatisch, nachdem er eine Aktion ausgeführt hat. Ab expecco 20.2 sind zudem weitere automatische Updates möglich. Sie können Sie im Menü ''Fenster'' aktivieren.

Zum einen kann kurze Zeit nach dem Ausführen einer Aktion überprüft werden, ob es noch Änderungen nach der ersten Aktualisierung gegeben hat, damit in diesem Fall eine zweite Aktualisierung stattfinden kann. Dies soll das Problem beheben, dass der Recorder nach einer Aktion nicht aktuell ist, weil die Aktualisierung zu früh stattgefunden hat.

Zum anderen kann eine periodische Aktualisierung eingeschaltet werden. Nach einem einstellbaren Interval wird der Recorder automatisch aktualisiert, sollte es Änderungen geben. Dadurch ist die Anzeige im Recorder immer weitgehend aktuell, allerdings entsteht dadurch auch ein Mehraufwand was die Kommunikation mit dem Gerät betrifft.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid-Apps und WebViews =

'''!!! WICHTIGER HINWEIS - Wenn Sie Probleme haben, auf den Webview zu wechseln, geben Sie bitte unter den Android Einstellungen - Apps -Standard Apps "Chrome" als "Browser-App" an !!!
'''

Hybrid-Apps enthalten neben den Plattform-nativen Elementen weitere Elemente, die in einen WebView eingebunden sind. Diese Elemente können ebenfalls bedient werden, allerdings muss zuvor in den entsprechenden Kontext gewechselt werden. Mit dem Baustein "''Get Current Context''" erhalten Sie den aktuellen Kontext. Zu Beginn ist dies "''NATIVE_APP''", also der Kontext der nativen Elemente. Mit dem Baustein "''Get Context Handles''" bekommen Sie eine Collection aller vorhandenen Kontexte. Gibt es einen WebView-Kontext, so heißt dieser "''WEBVIEW_1''" oder "''WEBVIEW_<package>''" mit dem Paket des WebViews. Es kann auch mehrere WebView-Kontexte geben. Zu jedem WebView-Kontext gibt es im nativen Kontext ein entsprechendes WebView-Element. Mit dem Baustein "''Switch to Context''" können Sie in einen solchen Kontext wechseln und haben fortan nur Zugriff auf die Elemente in diesem Kontext.

Im GUI-Browser werden zum einen oben im Baum die vorhandenen Kontexte angezeigt, zum anderen wird der Baum eines Kontexts unterhalb des entsprechenden WebView-Elements eingefügt.

= XPath anpassen mithilfe des GUI-Browsers =
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen "''GTIN-13 (EAN-13)''" und "''Verify''", das Eingabefeld der Zahl "''4006381333986''" und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des "''GTIN-13''"-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch "''Pfad überprüfen''" (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit "''Verify Path: OK''" (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit "*" zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert "''GTIN-13 (EAN-13)''" besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer "''hierarchy''" (für iOS wäre es "''AppiumAUT''"), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix "''android.widget.''", das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend "''XCUIElementType''" am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. "''FrameLayout''" ist ein Kindelement von "''hierarchy''", "''LinearLayout''" ist ein Kind von "''FrameLayout''" usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element "''hierarchy''" beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben "''TextView''"-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ "''Button''" gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut "''resource-id''". Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut "''name''" verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem "@" eingeleitet und der Wert mit einem "=" in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter "''Test''" eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf "''Lauf''". Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu "''Eigenschaften''", wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

== Weitere Locator-Strategien ==
Appium bietet neben XPath noch weitere Strategien zur Adressierung von Elementen an. Einige davon stehen Ihnen '''ab Version 20.1''' ebenfalls mit expecco zur Verfügung. Diese sind nicht ganz so mächtig wie XPath, dafür aber häufig schneller bei der Auflösung auf dem Gerät. Insbesondere bei der Verwendung mit iPhones, wo die Hierarchie bei jeder XPath-Auflösung erst aufgebaut werden muss, bieten alternative Strategien einen Vorteil für die Laufzeit.

XPath ist weiterhin der Standard, das heißt alle Locator ohne besondere Angabe werden als XPath interpretiert. Um eine der anderen Strategien zu verwenden, schreiben Sie diese mit einem Gleichzeichen vor den gewünschten Locator. Diese Technik können Sie sowohl an den Blöcken verwenden, als auch im GUI-Browser testen.

{|
|-
| style="vertical-align:top" | AccessibilityId || style="padding-bottom:0.5em" | Verwendet den Wert des Elements, der dazu dient, die App barrierefrei zu machen. Für iOS ist das das Attribut '''Accessibility-id''', für Android das Attribut '''content-descr'''. ''Beispiel: accessibilityId=Löschen''
|-
| style="vertical-align:top" | className || style="padding-bottom:0.5em" | Verwendet den Namen der Klasse des Elements. ''Beispiel: className=android.widget.FrameLayout''
|-
| style="vertical-align:top" | id || style="padding-bottom:0.5em" | Verwendet die Kennung des Elements. Für iOS ist das das Attribut '''name''', für Android das Attribut '''resource-id'''. ''Beispiel: id=android:id/text1''
|-
| style="vertical-align:top" | iOSClassChain1 || style="padding-bottom:0.5em" | Verwendet die Hierarchie der Elemente ähnlich wie bei XPath. Eine Erklärung zum Aufbau finden Sie [https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules hier]. ''Beispiel: iOSClassChain=XCUIElementTypeWindow/XCUIElementTypeButton[`label == "Ok"`]''
|-
| style="vertical-align:top; padding-right:1em" | iOSNsPredicateString1 || style="padding-bottom:0.5em" | Verwendet einfache Kriterien, wie Attribute, die auch kombiniert werden können. ''Beispiel: iOSNsPredicateString=type == 'XCUIElementTypeButton' AND name == 'Weiter'''
|-
| style="vertical-align:top" | name1 || style="padding-bottom:0.5em" | Verwendet den Namen des Elements. ''Beispiel: name=Bestätigen''
|-
|}

:1 ''nur für iOS''

Um eine direkte Beschleunigung mit iOS zu erzielen, ohne dass Sie Ihre bisherigen Pfade anpassen müssen, wandelt expecco zudem Pfade, die nur aus einem Element mit Klasse und name-Attribut bestehen, zur Laufzeit automatisch in einen entsprechenden Locator der Strategie iOSNsPredicateString um. Wenn Sie einen Pfad explizit als XPath markieren, wird diese Anpassung nicht vorgenommen.

=Probleme und Lösungen=
== Locator sind versionsabhängig oder variabel ==
Dann sollten Sie die Locator (xPath) entweder in einer Variablen halten oder ein Locator-Mapping in einem Screenplay Anhang definieren. Es ist auch möglich, lediglich Teile des Locators (z.B. Locator-Pfad eines Elternelements oder Attributwert) in einer Variable zu halten und im Freezevalue des Locator-Pins mit "''$(varName)''" einzufügen.

==Unsichtbare UI-Elemente==
Beachten Sie, dass im [[#Recorder|Recorder]] auch Elemente berücksichtigt werden, die Sie auf dem Bildschirm nicht sehen. Schalten Sie daher das Element-Highlighting an oder nutzen Sie die Follow-Mouse-Funktion und den Elementbaum im GUI-Browser, um festzustellen, ob das richtige Element verwendet wird. Es kann vorkommen, dass unsichtbare Elemente vor anderen Elementen liegen und diese verdecken, so dass die gewünschten Elemente im Recorder nicht ausgewählt werden können. Lesen Sie dazu den Abschnitt [[#Elemente_verbergen|Elemente verbergen]].

==iOS: Kabel nicht zertifiziert==
In manchen Fällen erscheint beim Verbinden eines iOS-Geräts über USB der Hinweis, das verwendete Kabel sei nicht zertifiziert. In diesem Fall hilft es nur, das entsprechende Kabel auszutauschen.
==iOS: Alerts beim Verbindungsaufbau==
Stellen Sie sicher, dass beim Verbindungsaufbau mit einem iOS-Gerät keine Alerts geöffnet sind. Der Aufbau schlägt sonst fehl, da die App nicht in den Vordergrund kommen kann. Siehe auch [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Gerät und App vorbereiten]].

==iOS: .ipa installieren nicht möglich==
Beachten Sie, dass auf iOS-Simulatoren keine ''.ipa''-Dateien sondern nur ''.app''-Dateien installiert werden können.

==iOS: Erster Verbindungsaufbau funktioniert nicht==
Wenn auf Ihrem Mac noch kein signierter Build des WebDriverAgents liegt, muss dieser beim ersten Verbindungsaufbau erst erzeugt werden. Das kann in der Regel etwas länger als eine Minute dauern. Standardmäßig verwendet Appium aber einen Timeout von 60000 ms um zu warten bis der WebDriverAgent auf dem Gerät startet, so dass der Aufbau in diesen Fällen abgebrochen wird. Sie können den Timeout mit der Capability ''wdaLaunchTimeout'' setzen, z.B. auf ''120000''.

Außerdem müssen die Einstellungen für die Signierung passen. Am zuverlässigsten funktioniert das nach unserer Erfahrung, wenn man im Xcode-Projekt des WebDriverAgents auf automatische Signierung stellt und das Team setzt. Siehe dazu die Erklärung im Abschnitt [[#WebDriverAgent-Signierung|WebDriverAgent-Signierung]]. In diesem Fall sollten Sie die Capabilities ''xcodeConfigFile'' bzw. ''xcodeOrgId'' und ''xcodeSigningId'' '''nicht''' verwenden, da es sonst zu Konflikten kommen kann. Achtung: Wenn Sie eine Team-ID in den Mobile-Testing-Einstellungen gesetzt haben, setzt expecco diese automatisch als ''xcodeOrgId''!

Achten Sie beim ersten Verbindungsaufbau außerdem auf Ihr Gerät, da Sie dort möglicherweise der Installation per Passwort zustimmen müssen. Auf dem Mac kann die Eingabe des Passworts zur Freigabe des Schlüsselbunds für die Signierung nötig werden, häufig auch mehrmals.

==Android: Gerät nicht im Verbindungsdialog==
Wenn ein über USB angeschlossenes Android-Gerät nicht im Verbindungsdialog auftaucht, versuchen Sie, den USB-Verbindungstyp zu ändern. In der Regel sollten MTP oder PTP funktionieren. Prüfen Sie nochmal, ob "USB Debugging" in den Entwicklereinstellungen des Geräts aktiviert ist (diese Einstellungen sind bei manchen Geräten zunächst unsichtbar, und müssen durch einen Trick zugänglich gemacht werden). Siehe auch [[#Android-Ger.C3.A4t_vorbereiten|Android-Gerät vorbereiten]].

==Android: Abgeschnittene Elemente unten==
Bei Android-Geräten, die die Steuerungsleiste bzw. Softkeys automatisch ein- und ausblenden, kann es vorkommen, dass der Recorder im unteren Bereich Elemente abschneidet, die durch die Softkeys verdeckt würden, auch wenn sie zu diesem Zeitpunkt gar nicht angezeigt werden. In diesem Fall hift es, die Softkeys so einzustellen, dass sie in einer permanenten Leiste angezeigt werden.

Bei neueren Android-Versionen gibt es eine solche Einstellung in der Regel nicht. Auch wenn die Steuerelemente permanent eingeblendet sind, liegen sie auf keiner extra Leiste, sondern vor dem Inhalt der App. Es gibt dann im unteren Teil einen Bereich, der nicht bedient werden kann, weil er nicht zum aktiven Bereich der App gezählt wird, weshalb die Elemente von Appium abgeschnitten werden. Dieser Bereich kann auch größer sein als von den Steuerungselementen beansprucht. Bekannt ist dies für Samsung-Geräte mit Android 11. Da die Information über die Größe des App-Bereichs bereits auf Android-Ebene so geliefert wird, können wir hierfür keine Lösung anbieten, sondern können nur hoffen, dass das Problem vom Hersteller behoben wird. Sie können versuchen, ob Sie mit der Einstellung von Gestensteuerung bessere Ergebnisse bekommen, allerdings gibt es hier das gleiche Problem.

== Android: Test hängt beim Suchen eines Elements==
Der Baustein ''Find Element by XPath'' und alle Element-Bausteine warten bis ein Element zum angegebenen Pfad auftaucht. Den Timeout dafür kann man entweder am Baustein direkt oder in den Umgebungsvariablen ändern. Wenn das Element aber bereits da sein sollte und es dennoch sehr lange dauert, bis der Test weitergeht, kann das am UIAutomator/UIAutomator2 liegen. Dieser wartet, bis die App in den Idle-Zustand geht, bevor er überhaupt nach Elementen sucht. Dies kann länger dauern, wenn die App z.B. im Hintergrund noch Animationen abspielt oder andere Aktionen ausführt. Auch das Holen des Page-Sources z.B. beim Aktualisieren im GUI-Browser oder im Recorder kann dadurch länger dauern. Standardmäßig gibt es hierfür einen Timeout von 10 Sekunden, nach dem nicht weiter auf den Idle-Zustand gewartet wird. Dieser Timeout lässt sich durch eine Einstellung in Appium anpassen (waitForIdleTimeout). Falls Sie einen anderen Wert für diesen Timeout setzen möchten, ist dies ab expecco 21.2 möglich, indem Sie vor dem Test den Smalltalk-Code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> ausführen. Der Timeout wird in Millisekunden angegeben, das Beispiel setzt ihn also auf 2 Sekunden.

==Android: Aktualisieren des Trees oder Wechseln zum Webview-Kontext braucht zu lange==
Speziell mit älteren Geräten kann es vorkommen, dass neuere Chromedriver nicht initialisiert werden können. Das führt dann dazu, dass nicht in den Webview-Kontext gewechselt werden kann. Dies wird von Appium allerdings nur über einen Timeout festgestellt, der standardmäßig bei 4 Minuten liegt. Da expecco auch beim Aufbauen des Trees im GUI-Browser versucht in den Webview-Kontext zu wechseln, kann das zu sehr langen Ladezeiten führen. Da es in Appium keine Möglichkeit gibt, diesen Timeout herunter zu setzen, haben wir die Version, die wir im MobileTestingSupplement bereitstellen, um eine entsprechende Capability erweitert. Ab der Version 1.13.1.0 des [[#Windows|MobileTestingSupplements]] kann mit ''chromedriverStartTimeout'' der Timeout in Millisekunden gesetzt werden. Der Wechsel funktioniert dadurch zwar trotzdem nicht, aber expecco braucht dann nicht mehr so lange beim Aktualisieren des Trees und der Baustein zum Wechseln des Kontextes schlägt schneller fehl. Der Verbindungsdialog fügt diese Capability ab expecco 22.1 automatisch hinzu.

==Keine Aktion bei Klick==
Der Baustein zum Klicken auf ein Element ist erfolgreich, aber auf dem Gerät wurde keine Aktion ausgeführt.
:Dies kann vorkommen, wenn das Element von einem anderen Element verdeckt ist und ein Klick auf das Element deshalb nicht möglich ist. In diesem Fall wird von Appium kein Fehler geworfen, sondern es passiert einfach nichts. Wenn Sie dennoch einen Klick an der Position des Elements machen möchten, auch wenn es verdeckt ist, benutzen Sie stattdessen den Baustein ''Tap'' und übergeben Sie diesem die Position des Elements (''Get Location''). Wenn Sie stattdessen vor einem Klick prüfen möchten, ob das Element zu diesem Zeitpunkt verdeckt ist, versuchen Sie, ob Ihnen die Eigenschaften ''Is Displayed'' oder ''Is Enabled'' weiterhelfen.

==Kein Update nach Aktion==
Über den Recorder wurde eine Aktion ausgeführt, für die auch ein Baustein aufgezeichnet wurde, der Recorder zeigt aber immer noch das alte Bild.
:Der Recorder zeigt kein Livebild des Geräts, sondern immer nur eine Momentaufnahme. Nachdem eine Aktion ausgeführt wurde, aktualisiert sich der Recorder automatisch. Es kann aber vorkommen, dass das Bild schon aktualisiert wurde, bevor die Auswirkungen der Aktion auf dem Gerät vollständig abgeschlossen sind. In diesem Fall sollten Sie den Recorder von Hand aktualisieren über das Symbol mit den blauen Pfeilen. Ab expecco 20.2 können Sie für diesen Fall auch automatisches Aktualisieren einstellen. Siehe auch Beschreibung zum [[#Recorder|Recorder]].

=="clickable" Attribut falsch==
Ein Element hat im "''clickable''" Attribut/Property den Wert "''false''", ist aber dennoch anklickbar.
:Das "''clickable''" Attribute muss explizit vom App-Programmierer gesetzt werden, und hat tatsächlich keine Relevanz für das tatsächliche Verhalten der App. Sie sollten dieses Attribut i.A. in Ihren Tests nicht beachten. Leider existieren viele Apps, bei denen der Programmierer hier "lazy" war.

==Verbindungsaufbau schlägt fehl==
Schlägt der Verbindungsaufbau mit dem Appium-Server fehl, erhalten Sie in expecco eine Fehlermeldung ähnlicher der unten abgebildeten.

[[Datei:MobileTestingVerbindungsfehler.png]]

Hier sehen Sie die Art des aufgetretenen Fehlers. Klicken Sie auf "''Details''" um nähere Informationen zu erhalten. Mögliche Fehler sind:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:Der angegebene Server läuft nicht oder ist nicht erreichbar. Überprüfen Sie die Serveradresse.
*''org.openqa.selenium.WebDriverException''
:Lesen Sie in den Details in der ersten Zeile die Meldung hinter ''Original Error'':
:*''Unknown device or simulator UDID''
::Entweder ist das Gerät nicht richtig angeschlossen oder die udid stimmt nicht.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::Dieser Fehler kann verschiedene Ursachen haben. Entweder konnte tatsächlich der WebDriverAgent nicht gebaut werden, weil die Signierungseinstellungen falsch sind oder das passende Provisioning Profile fehlt. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]]. Es kann auch sein, dass der WebDriverAgent auf dem Gerät nicht gestartet werden kann, weil sich beispielsweise ein Alert im Vordergrund befindet oder Sie dem Entwickler nicht vertraut haben.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::Die angegebene App kann nicht auf dem iOS-Gerät installiert werden, weil es nicht im Provisioning Profile der App eingetragen ist.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.'''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die Datei unter dem angegebenen Pfad auf dem Mac befindet.
:*''packageAndLaunchActivityFromManifest failed.''
::Die angegebene ''apk''-Datei ist vermutlich kaputt.
:*''Could not find app apk at [...]''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die ''apk''-Datei am angegebenen Pfad befindet.

Falls der Fehler nicht durch eine der oben gelisteten Ursachen bedingt ist, kann es sein, dass die auf dem Gerät befindlichen Automation-Anwendungen nicht mehr richtig funktionieren. Hier hilft es, diese vom Mobilgerät zu deinstallieren. Beim nächsten Verbindungsaufbau werden sie dann automatisch neu installiert.

*Für iOS-Geräte ist das der WebDriverAgent, den Sie einfach vom Home-Screen deinstallieren können. Dies behebt in der Regel Probleme durch den Wechsel des verwendeten Macs oder der Xcode-Version.

*Für Android-Geräte ist es der UIAutomator2; hier tritt auf einigen Geräten sporadisch ein Problem auf, die Ursache dafür ist uns z.Z. noch nicht bekannt. Zur Deinstallation navigieren Sie auf dem Gerät zu "''Einstellungen''" > "''Anwendungen''"* und suchen in der Liste nach folgenden Einträgen:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Klicken Sie auf die jeweilige Anwendung und dann auf "''Deinstallieren''".
*''Der entsprechende Eintrag heißt auf manchen Geräten möglicherweise etwas anders.''

Falls dies nicht hilft, kann eventuell die Ausgabe des Appium-Servers weiterhelfen. Für einen von expecco gestarteten Server finden Sie das Log in der Liste der [[#Laufende_Appium-Server|laufenden Appium-Server]].

==Ich habe keinen Mac==
Vielleicht hilft Ihnen diese Webseite weiter: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Release Notes 24.x

2024-05-29T07:42:43Z

Matilk: /* Release 24.1 (2Q 2024) */

See also: [[Release Notes 23.x]]
 

== Release 24.1 (2Q 2024) ==
*Feature: [[Expecco_API/en#Global_and_Static_Variables|Static Variables for Python]]
*Feature: Qt-Testing: Logging with log levels <code>DEBUG</code>, <code>INFO</code> and <code>WARN</code> ([[Qt_Inject_Windows/en#Logging|Qt-Logging]])
*Feature: Qt-Testing: Qt-Connections now use the ConnectionManager like the other Gui test technologies
*Feature: WindowsAutomation: Native Touch, Tap, Drag & Drop support now in the base WindowsAutomation Library
*Feature: Show Log and [[Timeline/en|Timeline view]] for testplans
*Feature: Search and Goto Line menu functions in the activity log view
*Feature: [[Embedded Systems C Bridge API|C-Bridge]] now supports SSL connections (encryption and authentication using certificates)
*Feature: [[Testsuite_Editor-ExecutionSettings_Editor/en|Settings for execution]] (thread pool and log activities/pins/info) can now be saved in the test suite settings
*Feature: CSV test report, values for start time, end time and duration added
*Feature: Improved refactoring for compound blocks: "Extract (& Replace) New Compound Action"
*Feature: Enhanced expecco reflection library
*Feature: Logprocessors can be executed for embedded testplans
*Feature: Logging of background actions can be individually enabled and disabled for testplans and nested testplans
*Fix: Current temporary testplan settings (like selected testcases, do-not-execute of pre/post action, etc.) don't get lost anymore when reimporting a library
*Fix: WindowsAutomation: Fix blocking of applications after <Mouse Button Down>
*Fix: asynchronous write to an output pin with no wait() in bridged actions are now detected and reported as error (see Example3 in the [[Expecco_API/en#Asynchronous_and_Callback_Functions|NodeJS API Documentation]])
*Fix: Bridges: Detect (and ignore) invalid requests from forked background bridge threads
*Fix: Acitivity logs of asynchronous events in background actions are now displayed correctly in the background activity log.
*Fix: Qt: Drag and drop improved by revising the "Move mouse event" (Windows)
*Fix: Disabling logs of sub-activities (if successful, if not successful, etc.)

Release Notes 24.x

2024-05-28T07:12:16Z

Matilk: /* Release 24.1 (2Q 2024) */

See also: [[Release Notes 23.x]]
 

== Release 24.1 (2Q 2024) ==
*Feature: [[Expecco_API/en#Global_and_Static_Variables|Static Variables for Python]]
*Feature: Qt-Testing: Logging with log levels <code>DEBUG</code>, <code>INFO</code> and <code>WARN</code> ([[Qt_Inject_Windows/en#Logging|Qt-Logging]])
*Feature: Qt-Testing: Qt-Connections now use the ConnectionManager like the other Gui test technologies
*Feature: WindowsAutomation: Native Touch, Tap, Drag & Drop support now in the base WindowsAutomation Library
*Feature: Show Log and [[Timeline/en|Timeline view]] for testplans
*Feature: Search and Goto Line menu functions in the activity log view
*Feature: [[Embedded Systems C Bridge API|C-Bridge]] now supports SSL connections (encryption and authentication using certificates)
*Feature: [[Testsuite_Editor-ExecutionSettings_Editor/en|Settings for execution]] (thread pool and log activities/pins/info) can now be saved in the test suite settings
*Feature: CSV test report, values for start time, end time and duration added
*Feature: Improved refactoring for compound blocks: "Extract (& Replace) New Compound Action"
*Feature: Enhanced expecco reflection library
*Fix: Current temporary testplan settings (like selected testcases, do-not-execute of pre/post action, etc.) don't get lost anymore when reimporting a library
*Fix: WindowsAutomation: Fix blocking of applications after <Mouse Button Down>
*Fix: asynchronous write to an output pin with no wait() in bridged actions are now detected and reported as error (see Example3 in the [[Expecco_API/en#Asynchronous_and_Callback_Functions|NodeJS API Documentation]])
*Fix: Bridges: Detect (and ignore) invalid requests from forked background bridge threads
*Fix: Acitivity logs of asynchronous events in background actions are now displayed correctly in the background activity log.
*Fix: Qt: Drag and drop improved by revising the "Move mouse event" (Windows)
*Fix: Disabling logs of sub-activities (if successful, if not successful, etc.)

Test Editor/en

2024-05-07T15:18:56Z

Matilk: /* Timeline View */

[[Bild:Test Editor.png|thumb|300px|Test Editor after a run]]
Notice: starting with release 1.8, this editor has been split into separate editor and execution tabs:
;Test/Demo
:Definition of the network under test. This is used to define a test or demo for the edited action. As such, it combines features of the [[CompoundBlock Editor-CompoundWorksheet Editor/en|network editor]].
;Run
:Shows information of the current or last execution of the network under test.

The separation was made to make better use of the screen (which was too filled for small displays) and also to reuse the execution output view in the [[GUI Browser/en|GUI-Browser]]. This document describes the previous combined editor.

=== As Part of an Action Block Definition ===
Every action can have an associated "''Test Network''" which is shown in the "''Test/Demo''" tab. The test network typically shows how the action is to be used and/or contains a unit test of the action.
We highly recommend that all of your actions provide an executable example of its use, both as a "unit test" and as additional documentation. It may also be used as a place to provide ready-to-use setups, which can be copied/pasted into other networks.

The "''Test/Demo''" network should not be used for "official" test-runs. Instead, always put real tests into a testplan and only use the test/demo network for the "private" execution of a single block
(i.e. unit tests for the action itself) or as a place for demonstration or "executable documentation".

To the right, you see a test editor after the successful execution of a test-block.

=== As Part of the GUI Browser ===

In this context, the test run tab presents the outcome of the last
execution within the GUI browser. This can be either the single action or the complete sequence as recorded so far.

=== As Part of the Testplan Editor ===

Here the outcome of the selected test case is presented.

= Buttons =

*[[Bild:Icon Run.png]] "Run" Starts or continues execution. All auto started steps will be triggered. Unless enabled in the execution settings, no debugger is opened when an error occurs or a breakpoint is hit. Instead, on error or fail, the execution is terminated and the failed/error status remembered in the log (shown in red). Halts or breakpoints are ignored.

*[[Bild:Icon Run Debug.png]] "Debug Run" Start or continue the test execution in debug mode causing the debugger to open on exceptions (regardless of what is specified in the execution settings) and also when a breakpoint is hit. In addition, skipInTrace and doNotLog attributes are ignored. Thus, all activities will be logged.

*[[Bild:Icon Run Single Step.png]] "Step" Start the test execution in single step mode or continue single stepping (when at a breakpoint).

*[[Bild:Icon Run SingleStepInto.png]] "Step Into" Like the above, but steps into other compound actions.

*[[Bild:Icon Pause.png]] "Pause" Pause the current test run. To proceed or single step, click on the according button.

*[[Bild:Icon Stop.png]] "Stop" Stop the execution of the current test run. Exception handling & cleanup (post actions) will be performed.

*[[Bild:Icon InterruptRun.png]] "Interrupt" (new in 18.1 aka "2.12") Interrupt the execution of the current test run and open a debugger. Useful to debug endless loops or to inspect the execution state in a long running elementary action. In the debugger, the execution can be proceeded, single stepped or aborted.

*[[Bild:Icon PauseOnError.png]] "Pause on Error" This toggle controls how the executor behaves when an error is encountered. The default is to stop the test execution and to mark the test case as "FAILED" or "ERROR". However, especially during the test development process itself, it is often useful to be able to proceed after an error. For example, when the test consists of a web-browser's input field values being checked and validated, you may want to continue after a validation error. With this toggle set, the executor goes into the pause-state whenever an error is encountered, and execution can be continued by pressing the "Run" or "Single Step" button again (i.e. it behaves as if "Pause" was pressed).

*[[Bild:Icon Hard Stop.png]] "Hard Stop" Hard-Terminate the execution of the current test run, without doing any exception/cleanup handling. This is useful e.g. for recursion hang-ups, or if a block's cleanup action leads to another blocking situation.

*[[Bild:Icon Print Report.png]] "Report" Generate a report from the log data

*[[Bild:Icon Follow Execution.gif]] "Follow execution" To enabled/disable auto-select of the currently active block in the log (animation while running). This button also provides a drop-down box (right click or press-and-hold), to select the number of levels and a tag filter, to further control which actions should be followed. The button's icon image shows a "minus" when automatic follow is disabled. If the tag filter is set, it gives a list of match-patterns (GLOB patterns) separated by semicolon. Automatic follow will then only show action which are both within any level-limit and which have a tag which matches any in the given tag filter pattern

*[[Bild:Icon FindNextError.png]] "Find Error" In the log, select the next activity which has finished with an error.

*[[Bild:Icon Next Inconclusive.png]] "Find Inconclusive" In the log, select the next activity which has finished with an inconclusive state.

*[[Bild:Icon FindNextActive2.png]] "Find Active" In the log, select the next activity which is currently executing.

*[[Bild:Icon BackToPreviouslyVisited.png]] "Previously Visited" In the log, select the previously visited activity (i.e. back in visited-history).

The remaining edit- and breakpoint-related buttons are described in the [[CompoundBlock Editor-CompoundWorksheet Editor/en#Buttons|network editor]].



= Views =
After a run, the recorded ''Activity Log'' is presented as a hierarchical tree of executed actions. Select individual actions the tree to see the action's details (inputs, outputs and generated logging messages).

== Activity Tree ==
The activity tree displays a hierarchical view of the activities that are invoked during the test run, each with a single entry in the tree. If an activity spawns sub activities, these sub activities are enlisted in the branch of the spawning activity, and you can expand or collapse the branch with the node browsing item. Only the first level is expanded automatically when the test run is started. Activities that perform elementary actions never have sub activities, while those that perform compound actions always have at least one sub activity (else they fail due to lack of executable steps inside). Activities on the same level are sorted chronologically by invocation time.

The symbol in front of the activity indicates the state of the activity. This can be either in progress or one of the [[Glossary/en#Verdict | test results (verdicts)]]: "PASSED", "FAIL", "INCONCLUSIVE" or "ERROR".

[[Bild:Context Menu Activity Tree.png|thumb|231px|Context Menu]]
A context menu is available in the activity tree view, relating to the Activity that is currently selected:

;Find Next Unhandled Error
:This option switches the selection in the tree from the currently selected activity to the next, failed activity for which no error handling was performed (and which was not ignored). The search is in the order of the tree hierarchy (i.e. deep-first search, starting at the current selection).

;Find Next Error
:Similar to the above, but this menu function will find both handled and unhandled errors and failures.

;Find Previous Unhandled Error
:Similar to the above, but searches backward for the previous unhandled failure or error.

;Find Previous Error
:Similar to the above, but searches for any error (both handled and unhandled)

;Generate Report from here...
:This option generates a report of the selected activity and all nested activities.

;Open page on selected Item
:This opens a new page on the block corresponding to the selected activity.

== Network View ==
This view is shown for compound activities. It displays the activity diagram and highlights steps as they are executed. A step's color reflects its execution state, as described below in "State Colors".

Note that in this view, editing is not possible. You can, however, press <kbd>Enter</kbd> after selecting a step, causing a new browser page to open up, showing the selected step's diagram.

== Log View ==
This view shows the log created by the activity. The log consists of the messages (and possibly attached data or screenshots) as generated by the activity (and subactivities) via the "logInfo" / "logWarning" / "logError" and "logFailure" calls (either from elementary code or via the corresponding action steps in a compound action).

The toolbar buttons show or hide different message types. The checkbox named "''Sublogs''" shows or hides the logs of subactivities.

== [[Timeline/en|Timeline View]] ==
This pane is new with version 23.2. It shows a graphical presentation of the execution times.

== Pin Data View ==
This view is available for all types of activities. It shows two lists, the input pin value list to the left, and the output pin value list to the right. In each of the lists, three columns arrange the information. The first field of each row displays the pin name, the second one displays the value, and the third one displays the sender, or the receiver, respectively.

Note that input information is not changing after an activity was spawned, while output values can still be produced or changed during the execution of the activity. In each list, only one row can be selected at a time. According to the selected row, the above icon buttons can be used:

;[[Bild:Icon Sender.png]]
: Jump to the sender (the source) of the value. Only available for input pins when a sender object is available. This causes the selection in the activity tree to change to the activity that sent the selected value to this activity.
;[[Bild:Icon Receiver.png]]
: Jump to the receiver (the sink) of the value. Only available for output pins when a receiver object is available. This causes the selection in the activity tree to change to the activity that received the selected value from this activity.
;[[Bild:Icon Inspect Value.png]]
: Inspect the value object. As a shortcut, double click on the pin value's row.

The popup menu (right click) depends on the selection. If no row is selected, functions operating on all values are provided. Otherwise, functions on the selected item are offered. The selection can be toggled by pressing CTRL with the mouse click.

= State Colors =
When a compound action's diagram is executed, a read-only version of the diagram editor is showing the state of the execution.
There, steps are colored according to their [[Glossary/en#Verdict|execution state (verdict)]]. The color setting is part of the user settings and
can be changed according to your personal taste (or, if you suffer from red-green color blindness, for example).
 The defaults are:
* grey/original color the step was not yet executed

* blue the step is about to be executed. This means that it has all of its input values (and possibly any required resources) available and it is ready to run. However, its code or network is not yet being executed - either because other steps are still running and the maximum execution parallelity has been reached, or because the diagram is being single stepped and waiting for you to press the "''Step Next''" button.

* bright green (lime) the step is being executed

* normal green (darker green) the step has finished execution with success

* yellow the step has finished execution with success, but a warning was generated during its execution or an exception was caught or ignored. Select the step and the "Log" tab for details.

* normal red the step finished execution with an unhanded error

* dark red the step finished execution with a failure

* dark grey the step was skipped or its execution was aborted. Either due to the user initiating an explicit abort ("''Stop''" or "''Hard Stop''" button), or because another step forced the containing diagram's execution to stop.

= Tasks =
==Running a Trial Test of the Block==
To invoke the test wrapper, click on the start button in the editor's tool bar. The network is executed as usual, by starting with steps marked as autostart. If logging is enabled, the lower monitoring panel monitors the execution status. If logging is not enabled, the monitoring panel will be cleared and remains empty. Logging is initially enabled.

The monitoring panel is split vertically, showing the activity tree on the left, and the observation panel to the right, which displays the current state of the selected activity. Select any activity to see the details in the right area. The depth of the activity tree can be limited by setting a log depth limit. See [[Settings/en#Logging Settings|settings]].

If the "follow execution" toggle([[Bild:Icon Follow Execution.gif]]) has been checked, the selection in the tree automatically follows the currently executing activity.

==Debugging==
The "normal" reaction to errors during a testplan-run is to finish the test plan with a FAIL or ERROR status. This behavior is OK for test execution; however, during test development, it is helpful to get a symbolic debugger which gives more detail about what happened, the current state (i.e. variables) and how the program got there (called "''backtrace''" or "''walkback''" or "''call chain''" in the literature).

The debugger can be enabled via the global settings dialog. These settings are also used if you press the "''Run''"-button in this test-block runner. However, the additional "''Run with Debug''" button starts executing with the debugger enabled, ignoring the global settings.

==Modifying the Program while Executing==
It is possible to change the running program. This may sound a weird thing to do at first, but is very useful when test cases are created in an explorative manner, or changes have to be made to a long running test, and you do not want (or cannot) restart the test from the beginning.

You can change the program at any time (simply edit the action in another tab or window and accept). However, any action being already executed continues execution until finished in the old action definition. Only then (when invoked for the next time) will any changed definition become effective.

This means:
* if an elementary block is currently being executed, the changed program text will be effective when the elementary block is called the next time
* if a compound action is changed, it will use the new activity diagram, when invoked the next time.

To make code and diagram changes an atomic action, all changes are first done to a temporary edit-copy, which is finally installed as an atomic action when the "''Accept''" button is pressed. If multiple actions are to be edited, any ongoing execution should be paused first, and proceeded once all changes have been done.

==Single Stepping and Breakpoints==
===Steps in an Activity Diagram===
Either place a breakpoint on a step and proceed by pressing the "''Single Step''" button, or start the execution right from the start via the "''Single Step''" button. There is also a "breakpoint"-action, which can be placed into the network. By conditionally enabling these steps, conditional breakpoints can be added. When a breakpoint is reached, you can:
* continue single stepping (by pressing the "Step" button),
* cancel execution (press the "Stop" or "Hard Stop" button), or
* continue with normal execution (press the "Run" button).

Notice that there are now two different single step buttons; one is showing steps as executed in the currently visible network, the other ("''Step In''") also halts before any step in any subnetwork is about to be executed.

===Code Lines in an Elementary Action===
In a JavaScript action, place a line such as:
this.halt();
or
halt();
(in Smalltalk code, write "<CODE>self halt</CODE>")
somewhere in your elementary block's code. When executed, a debugger will be opened, highlighting the line containing the code-breakpoint.

As an alternative, place a line breakpoint by double-clicking beside the code line in the left side-bar area (a red breakpoint sign will be shown then). Notice that line breakpoints can only be placed at expressions starting in that very line, whereas the above described <CODE>halt</CODE> can be placed anywhere, where an expression is allowed.

In the debugger, press one of
* "''Next Line''" to single step to the next code line
* "''Step''" to single step over the next expression
* "''Send''" to step into the next expression
* "''Continue''" to proceed.
* "''Abort''" to stop the execution

The debugger also shows the calling chain (how did I get there) in the top pane, and the activity's local variables and temporary variables in the lower pane.

The debugger is described in detail in http://live.exept.de/doc/online/english/tools/debugger/TOP.html.

==Premature Stop of a Test==
Occasionally, it might be required to stop a test even though it has not completed. For example, if you detect an error or malfunction which is not detected by the test, or the test is caught in an endless loop due to an unexpected situation.
In this case, press the "''Stop''" button.

The "''Stop''" button asks the test-executor for a controlled termination of the run. "''Controlled''" means, that any cleanup actions (post-execution actions) are to be executed.

This is the preferred way to stop test execution, because those cleanup actions are meant to free any acquired resources, remove temporary files or to turn off hardware equipment which was acquired and configured by the test. I.e. to bring the state of your equipment back to a well known (initial) state.

However, sometimes, a cleanup action might itself encounter trouble. For example, if your test requires a login procedure to a remote machine, and the cleanup tries to perform a logout, this may block if the connection was lost during the test. In this case, the cleanup action will not be able to perform its logout and may even block forever.

To handle this situation gracefully, expecco will wait for some pre-configured time for all the cleanup actions to complete (this is a configurable settings value found in the "''Extras''" → "''Execution Settings''"-dialog). After that, a dialog window will appear, asking if the cleanup should be aborted or if you want to continue waiting for the cleanup.

If you are certain that no cleanup action is required, or if you know in advance, that it will fail or block, use the "''Hard Stop''" button, which terminates the execution without even attempting to perform any cleanup actions.
Use this with care, as it may leave allocated resources and devices in a non-determined state. It may also lead to file streams or sockets being left open. You can repair this (i.e. manually close any streams) via the "''Extra''" - "''Debugging''" menu, where you fild menu items to find and/or close those streams.
 Notice that unreferenced resources are usually automatically freed after some time via the automatic memory manager's finalization mechanism. However, this would not work if eg. an open file stream is still referenced by being held in an activity log or an expecco environment variable.

= Typical Error Messages when Execution Fails =

=== Empty action "..." (no steps) ===

Obviously, there is no action step at all in your diagram. This makes no sense in a production test suite, and is therefore reported as an error.
However, when developing tests, it may be useful to create dummy actions as placeholders for "to-be-implemented" actions. Then, got to "''Extras''" - "''Settings''" - "''Execution''" - "''Debugging''" and check the "''Allow empty Actions''" toggle.

Solutions:
* add some dummy action to you network. A step which writes a log message such as "to be implemented" is a good idea. This can be written to either the activity log (and will therefore appear in any printed test report) or to the Transcript (console).

* check "''Allow empty Actions''" in the settings.

=== No executable step in action "Test/Demo" ===

No inner action step could be executed inside the diagram.
 This happens if:
* an explicit "Start" step is missing,
* and/or no step has the "autostart" attribute set (which is equivalent to a start step)
* and no inner step got a value at one of its required triggering pins (from the compound action).
Solution:
:typically, you forgot to provide an input value to the tested compound action in the "Test/Demo" diagram.

=== No value for input pin "..." of step "..." ===
An inner step was started, but got no input value at one of its required pins.
The inner step was started (probably due to autostart or an explicit trigger, bt not due to an input value arriving).

Solution:
:make sure the inner pin is connected, and also that it will receive a value at the input pin(s). If it has an autostart or explicit trigger, check if that is really what you intended. In most cases, steps should be triggered by incoming data, and not only by control flow triggers (but to have both is perfectly ok).
:
:Be especially careful when steps are in a loop: often an input value is "consumed"in the first iteration, and then no value is present in further loop cycles. Then, make the input a "non-consuming" (parameter) pin, to preserve the value across loop cycles.

= See Also =
API for the builtin and bridged languages: "[[Expecco API]]",
"[[Expecco_API/en#Pin Functions | Pin-API ]]" and "[[ Expecco_API/en#Current Activity | Activity-API ]]"
 [[Expecco_API/en#JavaScript_and_Smalltalk_Elementary_Blocks|API for Smalltalk/JavaScript actions]]
 [[Expecco_API/en#Groovy_Elementary_Blocks|API for Java/Groovy actions]]
 [[Expecco_API/en#Bridged_Python_Elementary_Blocks|API for Python actions]]
 [[Expecco_API/en#Node.js_.28Bridged.29_Elementary_Blocks|API for NodeJS actions]]
 [[Expecco_API/en#Bridged_Ruby_Elementary_Blocks|API for Ruby actions]]
 [[Expecco_API/en#Bridged C Elementary Blocks|API for C actions]]
 Scripted actions: "[[ElementaryBlock_Element/en#Script_Action_Blocks | Script Action Blocks]]"
 [[ElementaryBlock_Element/en#Bridge_Action_Blocks_vs._Script_Action_Blocks | Bridged Actions vs. Script Actions]]"
 [[Code_Editor/en|Code Editor]]
 [[GUI Browser/en|GUI-Browser]]

[[Category:Editors]]

Release Notes 24.x

2024-05-07T14:50:59Z

Matilk: /* Release 24.1 (2Q 2024) */

Release Notes 24.x

2024-05-06T13:32:19Z

Matilk:

See also: [[Release Notes 23.x]]
 

== Release 24.1 (2Q 2024) ==
*Feature: [[Expecco_API/en#Global_and_Static_Variables|Static Variables for Python]]
*Bug Fix: asynchronous write to an output pin with no wait() in bridged actions are now detected and reported as error (see Example3 in the [[Expecco_API/en#Asynchronous_and_Callback_Functions|NodeJS API Documentation]])
*Feature: Qt-Testing: Logging with log levels <code>DEBUG</code>, <code>INFO</code> and <code>WARN</code>
*Feature: WindowsAutomation: Native Touch, Tap, Drag & Drop support now in the base WindowsAutomation Library
*Feature: Log and timeline view also for the root testplan
*Enhancement: Current temporary testplan settings (like selected testcases, do-not-execute of pre/post action, etc.) don't get lost anymore when reimporting a library
*Bug Fix: WindowsAutomation: Fix blocking after <Mouse Button Down>

Release Notes 24.x

2024-04-22T09:31:37Z

Matilk: /* Release 24.1 (2Q 2024) */

See also: [[Release Notes 23.x]]
 

== Release 24.1 (2Q 2024) ==
*Feature: [[Expecco_API/en#Global_and_Static_Variables|Static Variables for Python]]
*Bug Fix: asynchronous write to an output pin with no wait() in bridged actions are now detected and reported as error (see Example3 in the [[Expecco_API/en#Asynchronous_and_Callback_Functions|NodeJS API Documentation]])
*Feature: Qt-Testing: Logging with log levels <code>DEBUG</code>, <code>INFO</code> and <code>WARN</code>
*Feature: WindowsAutomation: Native Touch, Tap, Drag & Drop support now in the base WindowsAutomation Library
*Enhancement: Current temporary testplan settings (like selected testcases, do-not-execute of pre/post action, etc.) don't get lost anymore when reimporting a library
*Bug Fix: WindowsAutomation: Fix blocking after <Mouse Button Down>

Testplan Editor/en

2024-04-17T12:07:07Z

Matilk: /* Log Processor Action */

[[Bild:Testplan Editor 1.png|thumb|300px|Testplan Editor showing the plan's attributes]]
[[Bild:Testplan Editor 2.png|thumb|300px|Testplan Editor showing a test-case item's attributes]]

The test plan editor is used to create, modify and execute test plans. It is shown in the "''Testplan''" tab when a [[Testplan Element/en|testplan element]] is selected in the navigation tree.

Testplans are constructed as a sequence of test cases. Notice that in literature and other test frameworks, these are often called "''test steps''". Expecco uses the term "''test case''" for items in a test plan and "''test step''" for individual action steps within a test case. The reason is that in expecco, a "''test step''" (which defines what is done) can be put into multiple test plans as test case (which defines when and under which conditions it is execute).

To add test cases to a test plan, drag actions (from the left tree) into the test case list.
If you want to define your test plan in a top-down fashion (i.e. create the list of test cases first, before any actions are defined), you can also create the test plan's list items with the "''Add Test Case''" button or menu function, and later specify the concrete action by dragging actions into the "''Action''" field at the bottom or by selecting the test action vie the "..." button at the right. Finally, you can copy (CTRL-C) tree items and paste them elow the selected testcase with CTRL-V.

Later, when the test plan is executed, these test cases will be executed in sequence one after the other.

The test plan editor consists of two major areas: the top list presents the list of test cases, the bottom presents attributes of the selected item in the list.
Attributes specify the behavior of the test plan and of individual test cases.

To execute the test plan, click on the green "''run''" button in the toolbar.

When a test plan has been executed, the state of its last execution outcome is shown in the top list. Not executed or inconclusive items are shown with a grey color, successful items in green, and failed items in red.

To the right you can see two examples for an opened testplan editor. In the first, the test plan itself is selected; in the second, a test case is selected and shown. Both show a situation after a test run which was only partially successful.

= Testplan Hierarchies and Slices =

Items in a test plan (called "''Test Cases''" in the previous paragraph) are typically implemented as
actions from the tree. I.e. usually, you will define a test action and bring it into a test plan's list.

Any action can be used as test case and thus placed into a test plan's list. However, it is recommended that test actions be tagged as "TEST-CASE" (tree menu → "''More''" → "''Mark as TEST_CASE''"), so they will be presented with a different icon in the tree (that us just to make things easier to find; it has no semantic meaning).

In addition to actions, it is also possible to place other test plans as items into a test plan.
This allows for tests to be grouped (for example: by component or variant of the [[Glossary/en#SUT_.28System_Under_Test.29 | SUT]]) and placed as group into another test plan. Thus, the group can be executed individually (for component tests) or under another test plan (for final acceptance tests).

Because of this, it may be better to call these "''Testplan Items''" instead of "''Test Cases''" (but your milage may vary and users tend to use different naming for these entities).

= Buttons =

*[[Bild:Icon Run.png]] Start the test execution (stop execution on error).
*[[Bild:Icon Run Debug.png]] Start the test execution with debug (open a debugger on error).
*[[Bild:Icon Run Failed.png]] Runs all previously failed and inconclusive test cases again (i.e. all cases which ended with success will be skipped)
*[[Bild:Icon Run Inconclusive.png]] Runs all previously inconclusive test cases.
:This includes both cases which have not yet been executed and cases which have ended in the inconclusive state.
*[[Bild:Icon Run Single Step.png]] Start execution in single step mode or continue single stepping.
*[[Bild:Icon Run Single Step2.png]] Start execution in single step mode or continue single stepping. Steps into called actions.
*[[Bild:Icon Pause.png]] Pause the current test run. To proceed, click on the run button. To proceed single stepping, click on one of the single-step buttons.
*[[Bild:Icon StopAndSkip.png]] Stop the execution of the current test-case, marking it as aborted (inconclusive). Proceed by starting the next test-case.
*[[Bild:Icon Stop.png]] Stop the execution of the current test run. Exception handling and cleanup actions will be performed.

*[[Bild:Icon Hard Stop.png]] Hard-Terminate the testrun, without exception handling or cleanup actions.
: This is useful e.g. for hang-ups or communication failures (i.e. if a cleanup action itself hangs). Be aware, that this may lead to leftover open web-browser windows (in case of web-testing) or leftover open communication channels (sockets, serial line connections). These may have to be closed manually via the "''Extras''" → "''Debugging''" → "''Close Connections''" menu, if required.

*[[Bild:Icon Logging Menu.png]] Logging drop down menu to load/save a result log
*[[Bild:Icon Print Report.png]] Generate a [[Report Generation/en|report]] from the log data

*[[Bild:Icon Add Testcase.png]] Adds an empty test-case to testplan. The item's action can then be specified in the lower details area. However, a more convenient way to add test-cases is to simply drag&drop an action into the list.
*[[Bild:Icon Remove Testcase.png]] Remove the selected test-case(s) from test plan
*[[Bild:Icon Up.png]]/[[Bild:Icon Down.png]] Change the execution order of the test-cases, by moving the selected test-case(s) up or down in the list

*[[Bild:Icon Follow Execution.png]] Follow execution: autoselect the currently active block in the log (while running). In recent expecco versions, this button got replaced by a drop-down box, to selecte the number of levels, which should be followed. The button's icon image is slightly different.
*[[Bild:Icon Previous Error.png]] Find the previous failed or erroneous test case
*[[Bild:Icon Next Error.png]] Find the next failed or erroneous test case
*[[Bild:Icon Next Inconclusive.png]] Find the next inconclusive test case
*[[Bild:Icon Next Active.png]] Find the next active (currently running) test case

= Tasks =
== Adding and Arranging Test Cases ==
There are multiple ways to create new test case entries in the test plan:
# Create empty items with the toolbar button shown above, then specify the action block in the lower editor's "''Action''" field.
# Directly drag & drop an action block or another test plan from the navigation tree into the testplan area. For this, it is useful to open a secondary popup or split tree.
# Copy-Paste items from the left tree; using either menu- or keyboard shortcut functions.
# Use a programatic testplan generator from the reflection library

Please note that not any block can serve as test case item in this list.
Allowed are:
* actions without input pins (or where all pins have default values)
* actions where input pins have only simple types (strings, numbers, filenames). See [[#Action Parameters | "''Action Parameters''" below]].
* other test plans (this creates a hierarchical test plan, with sub-test sequences).

When creating an entry with the toolbar button or by pasting, new entries will be inserted below the currently selected entry. If nothing is selected or when an item is dropped onto the test plan itself, the new entry is added at the very bottom of the list.

The items' order (which is also the execution order) can be changed via the "''Move Item Up''" / "''Move Item Down''" items found on the the popup menu of a selected item. There are also [[Common_Keyboard_Shortcuts/en#Tree.2FList_Organisation|keyboard shortcuts]] (<kbd>Ctrl-↑</kbd> / <kbd>Ctrl-↓</kbd>) and toolbar buttons to move selected item(s).

== Executing a Test ==

Start the execution by clicking on the "''Start''" (or "''Run''") button ([[Bild:Icon Run.png]]). By default, execution starts with the first item and proceeds downward in the list.
You'll find multiple such run buttons: regular run, to run with debugger opening on error, to rerun failed cases only (as described above) or to rerun only inconclusive test cases. There are also two single step options in the toolbar.

Test cases can be individually skipped or activated by toggling the "''Enable''" checkbox in the list. There are also popup-menu entries to enable/disable multiple items in one operation (i.e. select multiple items, then use the menu function "''Skip Selected Items''").

The list keeps the information of the previous run, even if you switch to another editor and come back later. However, only the last execution's result of a test plan is remembered (unless you save the result in a file). Before any run, all test-cases' states are reset to the "Untested" state (which counts as "INCONLUSIVE"), no matter if they are activated for execution or not.

All checked test-cases are executed sequentially. While running, the currently executing test-case is marked with a little clock symbol. The symbols of all other test cases indicate their result state, which is one of the [[Glossary/en#Verdict|verdicts]] or the already mentioned "Untested".

After the test run, the list-elements can be expanded (the little [+]/[-] icons) to browse the test-cases' activity logs. You can also follow the execution while running, to keep track on the current execution state. Either click on those activity items, or check the "''Follow Activity''" toggle, to have expecco automatically follow the currently active action.

Create a report from this test-run by clicking on the "''Report''" button. Initially, a standard report template (with probably way too much detail) is printed. This can be customized in various ways to suit your needs. For more information see: [[Report Generation/en|Report Generation]].

== Stopping / Pausing / Resuming ==

* The "''Pause''" button ([[Bild:Icon Pause.png]]) will pause the execution. Useful to look into the trace or message log. You may later continue with or without the debug option (without the debug option, errors will lead to non-success of the corresponding test case, without user intervention. With debug, a debugger will pop up allowing for inspection of data and the state of any pending elementary action).

* The "''Stop''" button ([[Bild:Icon Stop.png]]) will end the execution. All currently active actions will be marked as "aborted", which is treated like "inconclusive" when interpreted as [[Glossary/en#Verdict | test verdict]].

* If you press either the "''Run''" ([[Bild:Icon Run.png]]) or the "''Run-with-debug''" ([[Bild:Icon Run_Debug.png]])button, execution will start from the very first test case (unless you change the check-toggles which control the individual test case executions). If the suite was paused, it will be resumed.

* If you press the "''Run Failed''" button ([[Bild:Icon Run_Failed.png]]), test cases which already finished with success will NOT be reexecuted. Thus their outcome and trace data is preserved. This is useful after a fix of the system under test and a rerun of affected cases.

* If you press the "''Run Inconclusive''" button ([[Bild:Icon Run_Inconclusive.png]]), only tests which where aborted previously or which have not yet been executed will be executed. Both successful and failed tests will NOT be reexecuted. This is useful to resume a test after a longer session interruption. Notice, that this "Run not Executed" function even works if you saved the previous test result and restarted expecco in the mean time. This works even if you proceed testing on another machine (testers will appreciate this, when their laptop battery is about to die...).

== Selective Execution ==
You can execute individual test-cases or a subset of all the test plan.

Of course, selective execution requires that test cases are independent from previous cases. That means that either each case leaves the SUT in a defined initial state, or every case makes sure to bring it into a defined state before doing its thing.

*'''Individual Selection:''' Individual testcases are excluded/included by toggling their execution toggle in the list. Notice that this is a session setting. When the suite is reloaded in a new session, all execution toggles will be reset to their default state (which can be specified for each individual item in the lower attribute area).

*'''Rerun of Failed Tests:''' The "''Execute Failed''" button executes those tests which failed in the previous run. This is useful if the whole suite would take a long time and individual tests are to be executed again after a fix of the system under test. Or after a change of a test-case's definition. Although this might save time, it is good practice (i.e. highly obligatory) to rerun the test plan completely eventually.

*'''Selection by Risk:''' You can define individual risk levels to each test-case of the plan. Now toggle the "''Risk''" check-box at the top of the test plan and set a risk limit. Then, when executing, only those test-cases will be executed which have a greater or equal risk level.

*'''Selection by Group:''' By attaching individual group-tags to each test-case, you can also group related test cases into test groups. Then, toggle the "''Testgroup''" check-box at the top of the test plan and enter some identifier(s) to specify, which group(s) to execute. The next test-run will only execute test-cases with a matching group tag.

*'''Dynamic Selection by Pre-Execution Checks''' If present, the pre-execution action is run before the actual test case. If it generates a non-successful result, the corresponding test case is skipped (a corresponding post-execution action is also skipped, if present).

*'''Dynamic Selection by Condition Variables''' You can attach a ''condition variable'' or a set of condition variables to a testcase. If a name or list of names is specified in the "''Check Condition Variable''" field, all of them must contain a boolean <code>true</code> value, otherwise, the test case is skipped with an inconclusive outcome. The variables must be defined in the testplan's environment (or the project's top environment) as boolean variables.In addition, it is possible to update a condition variable (or a set of condition variables) depending on the outcome of a test case. All variables listed in the "''set condition variable''" field will be set to <code>true</code>, if the test case passed, <code>false</code> otherwise. These two allow for a simple conditional execution of individual test cases. Of course, these variables are also visible in the network as regular environment variables. Therefore, more complex checks can be performed using arbitrarily complex logic there.

*'''Sub-Testplans''' Finally, by dropping another test-plan into the test-case area, all of its test-cases are embedded and are treated as a single test-case in the outer test-plan. Thus, hierarchies of testplans can be created, which can of course still be executed individually.

== Repeated Execution (Loop Modes) ==

It is often useful to run the same test scenario multiple times. For example if an error only occurs sporadically, you may want to repeat the test run until an error occurs. Or if your goal is to detect memory leaks or performance degration of the system under test, you may want to run it multiple times to put stress on it.
For this, various loop modes can be configured (see "''Execution Modes''" below):
* repeat the test for a particular number of runs
* repeat the test for a given time duration
* repeat the test until an error occurs
* repeat the test until no error occurs

Of course, all of the above can be easily implemented by creating a compound block and placing the test scenario's action block into it with either an iteration count or by adding appropriate looping blocks around. This is also the preferred mechanism, if different input values or configuration data has to be used for each run.
However, in most cases, only a simple repetition of the same test is desired, and this can be done without programming, by setting up a loop mode in the execution configuration.

=== Individual versus Full Report ===

When executing a test in loop mode, a big amount of trace and report data may accumulate, which may be cumbersome to examine and may also reach the available memory limits (in this case, expecco prunes the execution log, by removing older trace information).

For this, it is possible to specify that individual reports are generated and written to a file after each run - either unconditionally or only when an individual run is successful or failed. You can specify a filename pattern for this, so that each file gets a distinguished name (with optional run-number and/or time stamp in the file name). The files will be created relative to the project's attachment folder, unless an absolute pathname is specified.

=== Alternative Postprocessing Options ===

To postprocess the accumulated trace/log information, define a log-processor action and add it to individual testcases as "''Log Processor Action''". The log processor action gets the collected activity-log as input. This allows for arbitrary filtering and/or processing of the log information, but requires some knowledge about the structure of the log items and the operation of the log-processing action blocks in the [[ Standard Library ]] and/or the [[ Expecco Reflection Library | Reflection Library ]].
 (You can of course create an dummy log processor first, place a breakpoint on it and inspect the received object to see its structure).

== Data Driver / Generator (Feeding Loop) ==

You can execute the same suite with multiple data value tuples,
by defining a data generator action (drag&drop it into the "''Data Generator''" input field).
This action will be executed and each output value tuple will be
used to set variables in the testplan's environment, and execute the testplan
once for for each generated tuple.
The variables are named according to the generator action's output pin names.
(i.e. if you define environment variables "a" and "b", the generator should (must) have two output pins named "a" and "b", and generate the driving values there.)

== Configuring the Testplan ==
=== Adding Pre and Post Execution Actions===
Testplans can have pre- and post-execution blocks. The pre-execution block is executed before the plan is executed; the post-execution block is executed after it has finished.
If the pre-execution block does not finish with success, the testplan is not executed. This can be useful e.g. to allocate and/or release resources. To add a pre- or post-execution action, drag & drop an action block from the navigation tree into the corresponding field. Please note that these blocks cannot receive values via an input pin. See also below for pre- and post actions of individual test cases.

=== Adding a Background Execution Action ===
Testplans can have a background-execution block. The background-execution block is executed in parallel to the execution of the testplan and will be terminated after the execution of the testplan has finished. Typically, this will be a block which opens a socket, pipe or other communication channel or to start an external (shell-) process to feed or monitor the system under test. See also below for individual testcase background actions.

=== Adding an Inventory ===
If a test case requires a resource (device, lock or operator), an inventory can be specified, which defines the set of available resources and from which the resource will be allocated. Without an inventory, the test will not be able to perform.
 An inventory can be defined locally in a test plan, or globally in the top-level testSuite's ''misc'' tab (the later is used, if the test plan does not specify its own inventory preferences).

If tests are executed from AIDYMO via remote-execution, the inventory is provided by AIDYMO instead.
This ensures that measurement devices are correctly acquired and locked
for the duration of a test's execution - even among multiple tests running at the same time on different test machines.
To add an inventory, drag & drop an existing inventory definition element from the navigation tree.

=== Execution Settings ===
*'''Run Time Limit''' This field is used to set a time limit for the execution of the test plan. The execution will stop after the specified duration. The entered number can be followed by a time unit, e.g. "ms" / "s" / "m" / "h" / "d". Without unit, "seconds" are assumed. To remove a previously set time limit simply leave the field blank.

*'''Finish Suite even if Time Limit Reached''' This check box determines if either the execution of a test plan is stopped immediately after reaching the time limit or let the execution finish, e.g. to execute the remaining items and any post actions.

*'''Loop (Stop on Error or Failure / Success)''' This check box toggles looping on or off. If on, the execution of the test plan will be repeated until an error or failure (success) is encountered or otherwise the time limit for the execution is reached. The stop on condition feature is useful to catch sporadic error-behavior of a system under test. For example, to run a test unattended over night, but stop when a certain condition arises.

*'''Loop (Skip successful tests when looping)''' This check box toggles, if only failed or inconclusive tests should be run when looping. This is useful, when you want to retry failed tests until all testcases in the testplan are successful.

*'''Loop Count''' This field is used to set a maximum loop count for the test plan execution. To loop endless just leave the field blank.

*'''Period''' Forces cycles to be executed with this periodic time. For example, if you specify 30m, the testplan will be repeated every 30 minutes. If an individual run takes longer than the period, the next loop iteration will be performed immediately - otherwise, the system waits (idle) for the time difference between period and previous execution time. Use this, if the system under test needs some cleanup or "healing" time after each test run - especially when doing stress tests on a system which needs database or memory management cleanup after each run (e.g. systems which need some pause to perform garbage collection to prevent ever growing memory usage). Another

*'''Save Result after each Run''' If checked, a report file is written as specified in the filename pattern field after each run - either unconditionally, or for every successful or for every failed run. This is useful if a test only fails/succeeds sporadically, and you need a trace/log for those runs. If you do not specify this option, a single huge report may be generated, which is both hard to examine and which may become larger than the systems memory capacity (in this case, expecco would prune the report and throw away older items, which is usually not the user's intention). The filename pattern specifies the names of those individual report files, and should contain meta patterns such as: <ul><li>"%1" for the current run-number (1..)<li>"%2" for the individual run's start timestamp (as YYYYMMDDHHMMSS)<li>"%3" for the name of the test plan<li>"%4" for the name of the test suite.<li>"%5" for the individual run's start timestamp (as YYYYMMDD-HHMMSS) (V23.2 only)<li>"%6" for the individual run's start timestamp (as YYYY-MM-DD-HHMMSS) (V23.2 only)</ul> Thus, "<code>%4-%3-%1-%2.elf</code>" will generate report files named "suite-plan-1-20141004140005.elf", "suite-plan-2-20141004140007.elf", etc. You may specify multiple report file patterns in this field (separated by semicolon ";"), to generate reports in different formats. For example, enter "<code>run%1.elf , run%1.pdf</code>" to generate both a full log (which can be reopened with expecco for detail information) and a summary report as pdf document. For all reports, the default report template of the suite (or the user settings) is used.   The individual report files are created either in the project's attachment folder or, if an absolute pathname is given as pattern, in that folder. The attachment folder is a temporary folder, which is automatically removed when expecco is closed, or another suite is opened. Thus, you should archive those after execution. If expecco ALM is used as a test execution management system, these files will be uploaded and archived automatically after a run.   If expecco is used without expecco ALM, you may want to add a post-execution action, which copies those files to an archive, a database or checks them into a versioning repository. This is also a possible solution, if expecco-tests are to be started via another system, like jenkins or a batch script.

:New in V23.2:
::You may also provide shell- and environment variable replacements in the filename; $(xxx) will be expanded by either a shell/cmd or a project-variable named "xxx".
::Thus, if you "<code>setenv ELF_DIR /tmp/myrun</code>" and define the report file pattern as "<code>$(ELF_DIR)/run%1.elf</code>", your files will be stored as "/tmp/myrun/run1.elf", "/tmp/myrun/run2.elf", etc.
::Or if you set a project variable named "ELF_DIR" (possibly even dynamically during the run), the directory is defined by that variable's value.

*'''Severity Ignore Limit''' (new in 21.2) By default, a test plan stops executing further test cases if a "Mandatory (also called "Required") test case fails, and only continues after a fail with the next test case if the failed test case was marked as "Optional".
:Test cases should be marked as "Mandatory", if it really does not make any sense to continue with a test; for example, if the device under test has no power, if a login procedure failed or if a measurement device is offline.
:However, it is sometimes useful to have a more fine-grain control over the severity of a failure.
:For this, you can pass a severity level with a FAIL (either by calling <code>fail_severity()</code> in elementary code, or via the "<code>FAIL-with-SEVERITY</code>" action from the standard library).
:In the tesplan, you can now specify which severity level is considered severe enough to stop the test plan. In other words, of a FAIL-severity is less than the limit specified in that field, then test plan will continue executing mandatory test cases.
:Severities are numbers from 0 to 100. For backward compatibility, a regular FAIL (i.e. without an explicit severity) are handled like a max-severe failure with a pritority of 100.
:These cannot be ignored by the severity limit field.
:Thus old suites which where developed before the 21.2 version will keep their behavior of stopping when a mandatory test case fails, whereas new test actions can use the new "<code>FAIL-with-SEVERITY</code> action to pass aseverity level, which is then compared against the limit set for the run.
:Notice that this is a per-run setting. The severity limit will not be stored with the suite and it will not be made persistent in the user's settings. This limit is meant to be used when tests are manually started by an operator or during test development, but not for productions systems. Therefore, in a production run, all FAILS within a mandatory test case will stop the run.
:For now, the elementary "<code>fail_severity()</code>" API is only available in expecco elementary actions (i.e. script actions and bridged actions cannot as-yet call this. These may be provided in future releases, if there are sufficient requests from customers (for now, you can pass a fail severity from a bridged elementary action via an output pin back to expecco, and raise the FAIL there, using the action from the std-lib).

=== Manual Execution Settings ===
*'''Stop between individual Tests''' This check box allows you to stop the execution between each testcase. A confirmation dialog will pop up, asking for a confirmation-click to continue. Useful if any manual handling is needed after each test-case.

*'''Stop between loop cycles''' Similar to the above. If checked and one of the loop modes is selected, a confirmation dialog pops up after every loop cycle, asking for a confirmation-click to continue.

*'''Stop on Error''' This check-box determines whether the execution of the test plan is stopped when an error occurs. There are two such check boxes, to specify if it should apply only to test-cases marked as "required" or also to "optional" test cases.

=== expecco ALM Settings ===
These settings are only relevant if expecco is used as a "slave test execution engine" for AIDYMO (formerly called "''expecco ALM''"). They are ignored if expecco is running as a stand alone application (e.g. by the test developer) or started manually by a test engineer (see [[Command_Line_Options|"Command Line Options"]]).

*'''Visible in AIDYMO''' This checkbox determines whether the test plan is visible in [[Expecco_ALM_Overview/en|expecco ALM/AIDYMO]]. Such externally visible test plans can later be executed automatically by AIDYMO. Invisible test plans are useful for the test developer, to leave partial tests, setup, shutdown or cleanup sequences in the test suite, which are not meant for public use (or use by the automatic test scheduler).
*'''Operator Needed''' This checkbox determines whether an operator is required during execution of the test. AIDYMO will then ask a human operator to supervise/perform the test.
*'''Cases Visible in AIDYMO''' This checkbox determines whether test cases are individually selectable for execution in AIDYMO. If unchecked, only the whole test plan can be configured for an automatic run. You should only turn this check on, if the test cases are independent from each other, and do not need state from a previous test case or leave the system under test in a state needed by another test case. Otherwise, it is better to define multiple test plans, each with its individual setup/shutdown actions to leave the system under test in a defined state, and let the test manager choose among those plans, instead of individual test cases.



== Configuring Testcases ==

=== Testcase Description Field ===
Specifies the test case's descriptive name which is shown in reports, traces and log files.
If this field is left blank, the name of the action block which implements the test case is shown.
This field does not affect the execution - it only controls the names used in reports and logs.

=== Action ===
The action block, which implements the test case. This can be any compound or elementary action block from the left tree. The block must be one without input pins - if required, wrap it into a new compound block and provide input values from any source, such as constant freeze values, database values, CSV values from a file or environment variable values. You can either set the action by dragging a block from the left tree into this field, or by opening a selection dialog via the "..." button at the field's right.

=== Condition Variables ===
Condition variables provide an easy to use control mechanism over which testcase items are executed during a run. By specifying a list of boolean condition variables in this field, the testcase item will only be executed if all of those variables contain a "<CODE>true</CODE>" value (non-existing variables are treated like being "<CODE>true</CODE>"). After the execution, the success-state is written to the variables named in the "''Set Variables''" field.
These variables are managed in the testplan's environment. Therefore, you can also access these variables via regular environment blocks or via the low level code API (environmentAt: / environmentAt:put: calls). Condition variables can be used to disable individual test cases or to guide execution through different paths depending on previous actions. A typical application is to read out the system under tests configuration by a pre-action or first test case step, then setting condition variables, and execute only specific subsets of the suite, depending on the outcome.

More complex conditional execution is possible by wrapping individual test case actions into a compound block and placing condition test actions into that.

=== Adding Pre and Post Execution ===
Individual testcase items can have pre- and post-execution actions too. The pre-execution action (if specified) is executed each time the item is executed; the post execution action is executed after the item's execution has finished. This can be useful e.g. to allocate and/or release resources, to check for more complex preconditions, system state or for the test system's configuration, and to leave that information in environment variables to be accessed by later test steps, or be used as condition variables. To add a pre- or post-execution action, simply drag and drop a block from the navigation tree into the according slot. Please note that these block may not have input pins.

The pre-execution action is also a ''pre condition''.
If it ends non-successful, the corresponding test case and any post execute action are skipped.

=== Background Action ===
Sometimes, a background server process, monitor or data feeder activity is required to run in parallel to the actual test scenario.
This field allows for an action to be defined, which is started in parallel with (actually: right before) the test plan and terminated afterwards. Any compound or elementary block can be specified. Typically, this will be a block which opens a server socket, pipe or other communication channel to feed the system under test, or to start an external program for monitoring, capturing or generating data.
Please note that this block may not have input pins.
 If you need a background action to run during individual actions, place them as a step into the action's diagram.

=== Log Processor Action ===
Test executions generate an execution log/trace, which is later used to generate a more or less detailed report. For most customers, the report settings allow for the most common type of reports to be generated (by specifying the amount of data and detail of the report there).

However, for very special reports, or if specific data has to be extracted and postprocessed, it may be useful to process the generated raw activity data before it is used or instead of being used as input to the report generator.

The "''Log Processor''" field allows for an action block to be specified, which gets the raw log as input and may produce a cooked-up version of it as output. If the log processor has no output, the original activity log will be passed on to the report generator.

Arbitrary processing, filtering, renaming or archival of the raw data is possible in this action. Of course, some knowledge about the structure of that raw data is required, and you should consult the class browser and/or open a data inspector on a generated raw log for this. You will find an example in the "d11_LOG_Processing_Example.ets" suite (in "projects/examples"). Also, the reflection library now contains activityLog processing actions in the "Analysis" folder, and a sample testplan.

The log processor can also be used to extract particular information and save it into a separate database or file in any format. In this case, the log processor should not modify the given activity log, and either not having an output pin, or send it unchanged to its output.

Notice that there are both per-testcase log processors and a an overall (per testplan) log processor.
The latter gets a collection (i.e. Array) of individual activity logs as input, which it should process in an enumeration loop.



=== Testgroup and Risk Setting ===
For the selective execution of a test plan it can be useful to set a risk level for certain test cases or to collect related test cases in test groups. The risk level can go from "<CODE>very low</CODE>" to "<CODE>very high</CODE>" or can be set to "<CODE>unknown</CODE>". To add a block to an test group, just enter identifiers for the groups into the according field. Multiple identifiers must be separated by spaces. See [[Testplan_Editor-TestplanListView_Editor/en#Selective Execution|"Selective Execution"]] for more information.

=== Execution Settings ===
The check box in front of each test case determines whether it is executed or not (in the upper list). Please note that this setting is temporary and will not be saved. To set the default execution toggle setting, use the "''Default for Execute''" check box in the lower attribute area.

=== Action Parameters ===
Actions which have input pins need additional values when executed. If such an action is placed into a test plan, an additional tab is provided in the lower attribute area where values for those pins are to be entered.

Notice that only a limited set of data types are allowed for these. If more complex values are needed, you must place the action as a step into another compound ''Test Case Action'', feed the step's input pins as required and place this ''wrapper'' action into the test plan. There of course, any arbitrary complex data may be generated or acquired from a file, attachment or database.

= Context Menu of the Testcase List =
Some of the context menu (right-click) functions of the test-case/activity-log list operate on the selected item or set of items.

[[Bild:Context Menu Testplan.png|thumb|373px|Context Menu]]

*'''Add Testcase''' Adds a new (blank) test-case to the test-plan. You should drag and drop a test action into the "block" field in the lower pane.

*'''Delete Testcase''' Removes the selected test-case from the test-plan.

*'''Enable selected Testcases''' Enables (activates) the selected test-cases for execution.

*'''Disable selected Testcases''' Disables the selected test-cases for execution.

*'''Make all Enable Flags the Default for Execution''' Sets the state of the selection as the default for the test case. This will be the initial enable/disable-state of those test-cases, when the suite is loaded.

*'''Make selected Testcase Required''' Sets the priority of the selected test-cases to "Required".

*'''Make selected Testcases Optional''' Sets the priority of the selected test-cases to "Optional".

*'''Open Page on selected Item''' Opens a new browser page on the selected test-case's action. This function is only available if exactly one test-case is selected.

*'''Update''' Update all activity logs and sublogs under the selected item.

*'''Find Next Error''' Find and select the next failed or erroneous test-case in the activity log.

*'''Find Previous Error''' Find and select the previous failed or erroneous test-case in the activity log.

*'''Remove Result for selected Items''' Removes the test results of the selected test-case.

*'''Compress Result for selected Items''' Compresses the log result for the selected items. Compression means that only erroneous log entries are kept; all passed and OK infos are removed.

*'''Generate Report from here...''' Generates a [[Report Generation/en|report]] for the selected test-case (and, if this is a sub-testplan, for all nested test-cases).

*'''Move Up/Down''' To change the execution order of the test-cases.

The full online documentation can be found under: [[Online Documentation/en|Online Documentation]]

= Plugin Extension Tabs =

Plugins may add additional pages to this editor. Please refer to the individual plugin documentation.
For example, the Jira plugin adds a tab to specify the issue action to be taken in case of a failed test case execution.

[[Category:Editors]]

Java Browser/en

2024-02-21T16:39:53Z

Matilk: /* Using Java Browser */ new location in the menu

== Introduction ==

The '''Java Browser''' provides a simple interface to browse Java code. This is useful for test developers who write tests which use [[ElementaryBlock_Element/en#Groovy_Blocks|Groovy blocks]] to connect to the system under test.

== Using Java Browser ==

[[Datei:Select_Workspace_01.png|200px|thumb|right|Workspace selection dialog]]
[[Datei:JBrowser 01.png|200px|thumb|right|Java browser window]]
To open the Java Browser, select "''Plugins''" → "''Productivity''" → "''Java Browser''" → "''Open...''" and then select a [[#Workspace|workspace]]. To create a new workspace, enter a new, empty directory.

After the workspace is chosen, a single Java Browser window appears. It shows Java packages, classes and methods as well
as source code if it's available. If the source code is not available then it still shows the class structure without actual methods' source code.

== Workspace ==

'''Java Browser''' stores all Java code and sources in a folder called a ''workspace''. You can freely move workspaces around or store them on a shared network drive.

To create a workspace, select an empty directory. To add Java code to the workspace, open the workspace settings (in Java Browser window, select ''Workspace'' ► ''Settings''). In the settings dialog you may add ".jar" files or directories containing ".class" files and attach sources to then. Of course, you may use the workspace settings dialog any time later to add or remove ".jar" or ".class" file directories.

Java GUI Plugins/en

2024-01-29T13:33:51Z

Matilk: /* Connection to Remote Systems */

[[Java_GUI_Plugins|Deutsche Version]] | '''English Version'''
== Supported Java Technologies ==
expecco supports the automation of Java applications implemented with Java Swing, Java SWT or JavaFX. Also supported are applications that combine several of these technologies, e.g. a Swing application with embedded JavaFX content.

=== Java Swing ===

This plugin for expecco allows you to create automated tests for Java applications whose user interfaces were created with Swing. The block library contains blocks for controlling and checking Swing user interfaces. This plugin is also integrated into the expecco GUI Test Extension. This extension supports the development of test sequences.

==== Main Features ====

* Automated operation and verification of Swing user interfaces
* Simultaneous operation of several applications
* Control of Swing user interfaces on remote target systems
* Control of Java applications already running independently (no change to source code necessary, no recompilation of the application necessary)
* Addressing of control elements by XPath
* Access at object level possible via Java Bridge Interface Library
* Integration into the [[Expecco GUI Tests_Extension Reference/en|expecco GUI Tests Extension]]
* Block library with actions and checks for Swing components

=== Java SWT ===
Similar for applications created with the SWT GUI framework.

=== JavaFX ===
Since Java 11, JavaFX is no longer included in the JDK. Therefore you have to install an additional JavaFX SDK, e.g. from [https://openjfx.io/ OpenJFX]. Then copy the jar files from the lib directory of the JavaFX JDK to <code>packages\exept\expecco\plugin\javafx\lib</code> in the expecco installation directory.

== Functionality ==

The interface establishes a connection to the Java VM and provides functions for reading widget attributes, recording user input, and remotely controlling the application. In addition, a library provides additional building blocks for automating tests.
Essentially, the Java Swing plugin consists of two parts, the plugin
for expecco and the application control (agent). To control the Swing application, an agent is loaded into the Java Virtual Machine of the running Java application. A Java Development Kit 1.8 (JDK) or higher is required to load the agent. However, the application to be tested can be run in a normal Java Runtime Edition 1.8 (JRE).

== Requirements ==

On the computer where the application to be tested is to run (local or remote):

* [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html Java Development Kit 1.8] or higher (to load the agent)
* [http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html Java Runtime Edition 1.8] or higher (to run the application to be tested)

The expecco requirements apply on the expecco computer.

Please note that both the agent and the application to be tested must be started with either 32 or 64 bit Java, otherwise no connection is possible.

Caused by JDK changes between Java versions, potential version conflicts may occur.

The compatibility of the versions is as follows. [[Java GUI Plugins#Fehlerbehandlung|Further information on this.]]

[[Datei:JavaSwing Bridge Compatibility.png|border|200px|]]

===Access Permissions===

To be able to guarantee a connection on the target system, additional parameters must be specified when starting the application to be tested (as well as the Java agent).

There are two ways to do this

* Set an environment variable that is automatically loaded at the start of each Java application
* Manual transfer of parameters at each start of a Java application
* (Alternatively you can change access rights in the module-info.java files directly, but this is anything but practical)

'''Up to Java 11''' it should be sufficient to set the following parameters:
: <code>-Djdk.attach.allowAttachSelf=true</code>
: <code>--illegal-access=permit</code>

Setting an environment variable works as follows (''Example JDK_JAVA_OPTIONS which is loaded at every JVM start'')

'''for Windows Systems'''
* <code>setx JDK_JAVA_OPTIONS "-Djdk.attach.allowAttachSelf=true; --illegal-access=permit"</code>
* or via the GUI (Windows key + Pause).

[[File:Windows Setenvironment.png|border|600px|]]]

'''for Unix systems'''
* Bash: <code>export _JAVA_OPTIONS='-Djdk.attach.allowAttachSelf=true; --illegal-access=permit'</code>
* C Shell: <code>setenv _JAVA_OPTIONS '-Djdk.attach.allowAttachSelf=true; --illegal-access=permit'</code>

'''Since Java 11''' there is a stricter separation for the encapsulation of modules:

<code>--illegal-access=permit</code> will no longer work if the target application has a fixed module encapsulation ([https://stackoverflow.com/questions/46741907/what-is-an-automatic-module Details]).
In this case, additional parameters must be specified at program start which allow expecco access to the inherent resources.
Depending on the technology used, the required parameters can vary, which is why you have to find them out for yourself.
<code>jdeps list-deps JARNAME.jar</code> Jdeps is a freely available (part of the jdk) very useful tool for this purpose.
A short overview of the commands can be found [https://doc.expecco.de/w2.x/images/0/03/Java_module_cheat_sheet.pdf here] [https://zeroturnaround.com/rebellabs ©]

----

'''Example JavaFX''':

The environment variable <code>PATH_TO_FX</code> which points to the JavaFX directory must be set (functionality see above)
and the following parameters must be available when starting the Java application:

<div class="toccolours mw-collapsible mw-collapsed">
Parameter list (fold out)
<div class="mw-collapsible-content">
*<code>--modul-path "%PATH_TO_FX%" </code>

* <code>--add-modules=javafx.controls </code>
* <code>--add-modules=javafx.swing </code>
* <code>--add-modules=javafx.web </code>

* <code>--add-opens javafx.graphics/com.sun.javafx.sg.prism=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.stage=ALL-UNNAMED </code>.
* <code>--add-opens javafx.graphics/javafx.scene=ALL-UNNAMED </code>.
* <code>--add-opens javafx.graphicss/com.sun.javafx.stage=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.scene.layout=ALL-UNNAMED </code>

* <code>--add-opens javafx.controls/javafx.scene.control=ALL-UNNAMED </code>.
* <code>--add-opens javafx.controls/javafx.scene.control.skin=ALL-UNNAMED </code>.
* <code>--add-opens javafx.controls/javafx.scene.chart=ALL-UNNAMED </code>.
* <code>--add-exports javafx.controls/com.sun.javafx.charts=ALL-UNNAMED </code>
* <code>--add-opens javafx.controls/com.sun.javafx.charts=ALL-UNNAMED </code>
* <code>--add-exports javafx.controls/com.sun.javafx.scene.control=ALL-UNNAMED </code>
* <code>--add-opens javafx.controls/com.sun.javafx.scene.control=ALL-UNNAMED </code>.

* <code>--add-opens javafx.graphics/javafx.scene.image=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.scene.shape=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.scene.text=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/javafx.application=ALL-UNNAMED </code>.
* <code>--add-opens javafx.graphicss/javafx.geometry=ALL-UNNAMED </code>.
* <code>--add-opens javafx.graphics/javafx.scene.robot=ALL-UNNAMED </code>.
* <code>--add-exports javafx.graphicss/com.sun.glass.ui=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/com.sun.glass.ui=ALL-UNNAMED </code>
* <code>--add-opens javafx.graphics/com.sun.glass.ui.win=ALL-UNNAMED </code>.
* <code>--add-opens javafx.graphics/javafx.scene.input=ALL-UNNAMED </code>.

* <code>--add-opens javafx.base/javafx.event=ALL-UNNAMED </code>
* <code>--add-exports javafx.base/com.sun.javafx.runtime=ALL-UNNAMED </code>
* <code>--add-opens javafx.base/com.sun.javafx.runtime=ALL-UNNAMED </code>

* <code>--add-exports javafx.graphicss/com.sun.javafx.scene=ALL-UNNAMED </code>
* <code>--add-exports javafx.graphicss/com.sun.javafx.util=ALL-UNNAMED </code>
* <code>--add-exports javafx.graphicss/com.sun.javafx.scene.input=ALL-UNNAMED </code>

* <code>--add-exports javafx.web/com.sun.webkit.dom=ALL-UNNAMED</code>

* <code>--add-opens java.base/java.util=ALL-UNNAMED</code>
</div>
</div>

If you do not want to supply 10+ command line parameters, you can use instead [[File:Java_fx_command_options.txt]]. Then you start your application with the java command:
java @java_fx_command_options.txt ....

If you still get a <code>java.lang.IllegalAccessError</code>, you have to extend this parameter in the following way:
* Error text of the type <code>Module <module> does not open "<package>" for unnamed modules</code>:
: <code>--add-opens <modules>/<package>=ALL-UNNAMED </code>>
: Example:'' <code>Module java.base does not open java.lang for unnamed module</code> ''solve with:'' <code>--add-opens java.base/java.lang=ALL-UNNAMED</code>.
* Error text of the type <code>cannot access the class <package>.<class name> (in module <module>), because the module <module> <package> does not export to the unnamed module</code>:
: <code>---add-exports <modules>/<package>=ALL-UNNAMED </code>>
: Example:'' <code>cannot access the class com.sun.javafx.scene.input.ExtendedInputMethodRequests (in the module javafx.graphics) because the module javafx.graphics com.sun.javafx.scene.input not exported into an unnamed module </code> ''solve with:'' <code>--add-exports javafx.graphicss/com.sun.javafx.scene.input=ALL-UNNAMED</code>>

'''Tool Generate CmdLine File for arbitrarily modules (Java 11 et sqq.)'''

See [[JavaBridgeOpenModule/en|Generate CmdLine File for Java 11 et sqq.]]

== Configuration ==

=== Installation on the expecco Computer ===

When installing expecco, make sure that the Java plugin is selected as the component to be installed.

If the application to be tested for the development of test sequences is executed on the same computer, start expecco and under "''Extras''" → "''Settings''" → "''Plugins''" → "''Java Bridge''"
set the local path to a Java Development Kit 1.8 or higher.

The mandatory setting here is <code>JDK Installation Path</code> which is used for the main connection. <code>Java Installation Path</code> is an alternative setting for Groovy which only requires a JRE. For local connections, the Java Agent is automatically started with these settings.

[[Datei:JDKPfadEinstellungen.png|border|600px|]]

=== Installation on Test Application Computer ===

You have to copy the javaBin folder of the expecco bridge framework to the test computer. It is in the expecco installation directory at:

<nowiki>...\exept\bridgeFramework\javaBridge\javaBin</nowiki>

== expecco GUI Browser ==

The expecco GUI-Browser is an additional tool which offers the possibility to analyze running applications and to develop test sequences. Then you can use the information, such as names and properties of individual elements, to perform actions with the function library or to interact with individual elements.

=== Connecting ===

The following is a short series of pictures that can be used as a '''guide''' when setting up a connection 

[[File:JavaSwing GUI Browser.png|border|600px|]]]

First open the <code>GUI Browser</code> (black circle) and in the tab <code>Connect</code> select the option <code>Java</code> (red circle).
In the opening dialog you can now choose between 3 options.
 

* '''Start Application on the Local Machine'''
: provides a convenient way to start a local Java application via command line command
* '''Connect to an already running Application on the Local machine'''
: Allows connection to locally running Java applications. The Java Agent is automatically started with the Java version you specified in the expecco settings.
* '''Connect to an already running Application on a Remote Machine'''
: Allows you to connect to an already started Java Agent on another machine. This will then connect to the Java application running there.

----

[[File:JavaSwing Connection Window.png|border|600px|]]]

A search for Java applications lists all running Java virtual machines on the target system (in the example: localhost). A selection of the individual entries lists further information about the respective application.

----

[[File:JavaSwing Connection Connected.png|border|600px|]]]

If a connection has been successfully established, it will automatically be entered in the Expecco configuration list. There you can also see the GUI structure of the application as a hierarchical tree. Information on how to proceed can be found here: [[Expecco_GUI_Tests_Extension_Reference| GUI Test Reference]]

----

[[File:JavaSwing Connection Reconnect.png|border|600px|]]]

Closed connections stay in the GUI browser. If the application is still running, you can reestablish the connection. To do this, right-click on the entry and select ''Connect'' from the context menu.
If the connection settings have changed, you must reconfigure the connection. This can happen if you have restarted the application in the meantime. When using a remote system, this also applies to the agent.

=== Connection to Remote Systems ===
[[File:JavaSwing Connection RemoteSetup.png|border|600px|]]]

To establish a connection remotely, the Java Agent must first be started on the target computer. To do this, navigate to the directory <code>...\exept\bridgeFramework\javaBridge\javaBin</code> on the computer.
There is a script which automatically detects the Java version in JAVA_HOME and starts the correct agent.
* Windows users start <code>startAgentLoader.bat</code>
* UNIX users start <code>startAgentLoader.sh</code>
These scripts can be provided with parameters via the command line as shown in the picture.
* <code>-ip <HostnameOderIP></code> gives the agent a special IP to wait for a connection. Useful for specific network masks.
: Default host is 0.0.0.0.
* <code>-port >PortNumber</code> gives the agent a specific port to wait for connections from Expecco.
: Default port is 56784.

=== Warnings ===
[[Datei:JavaSwing Connection Warnings.png|border|600px|]]
 
If any problems occur with the applications in this list, as can be seen in the picture above,
the connection dialog automatically returns a suggested solution. If the error that occurs would make a connection impossible, the corresponding entry is automatically marked as invalid.
 
The following error messages may occur and can be easily corrected:
::{|
|JAVA VERSION MISMATCH
|As you can see in the picture, there may be Java version conflicts between the agent and the application. In this case it is easiest to adjust the Expecco settings for Java Bridge. A remote connection would have to start the program manually with the desired Java version instead. The Java Agent, if called via the <code>startAgentLoader</code> script, selects the version Based on <code>JAVA_HOME</code> on the remote system
|-
|32 BIT - 64 BIT CONFLICT
|The 32 and 64 bit versions of Java are not compatible with each other. Both the agent and the application must be started with the same "bit version" of Java. 
|-
|UNABLE TO DETERMINE VERSION
|The agent cannot determine which Java version the application is using. A connection may be possible, but there may be a potential version conflict.
|}
:

== Cross-Technology Connections ==
If an application uses multiple Java technologies, you only need to establish one connection and then use the blocks from the library according to the technology of the element to be addressed. Since expecco 21.1 you can alternatively use blocks from the CommonJavaGUILibrary. Read more about the different libraries in the next section.

=== Embedded JavaFX in Java Swing ===
If JavaFX is embedded in a Swing application, it contains a JFXPanel element. In the GUI browser, the JavaFX elements are displayed below this panel. For the FX blocks to find these embedded FX elements, the block ''Set FX Context To Panel'' from the Swing Library with the path to the JFXPanel must be executed at the beginning.

=== WebView in JavaFX ===
If a WebView is included in JavaFX, its elements are displayed in the GUI browser below the WebView element. For these elements there are separate blocks in the JavaFX library, which are combined in the folder ''Embedded WebView''. In order for the elements to be found in the test, the block ''Set WebView Context'' must first be executed on the element WebView.

=== Embedded Java Swing in JavaFX ===
If Java Swing is embedded in a JavaFX application, it contains a SwingNode element. In the GUI browser, its content is still displayed parallel to the FX content. The modules of the Swing library can be used directly with these elements.

=== Compound Paths ===
Since expecco 21.1 the CommonJavaGUITestLibrary contains blocks, which generally work with each of the three supported Java technologies as well as Embedded WebView in FX. Just as some blocks only work with special types of elements, there are blocks, which so far do not support all technologies. But the whole functionality provided by the specific Java libraries is also available here.

For cross-technology connections, these blocks use compound paths, i.e. an embedded element is addressed by a path which combines the path to its embedder with the subpath of the element. For example let's take a look at a Swing application embedding FX elements using a JFXPanel. The path to an FX button then may look like this
/frame/rootpane/layeredpane/panel/JFXPanel/Scene/Node/Button
where ''/frames/rootpane/layeredpane/panel/JFXPanel'' is the path within the Swing context to the JFXPanel and ''/Scene/Node/Button'' is the path to the button within the FX context of the JFXPanel. Blocks to switch the context are not needed anymore. The paths can also be shortened, but the embedding node, in this case the JFXPanel, has to be an explicit part of the path. E.g.
//JFXPanel//Button
would also work.

Compound paths only work with the blocks in the CommonJavaGUITestLibrary. The blocks in the specific Java libraries still work with the old path and can be used side by side. To switch back to the usage of the old paths and blocks in the GUI Browser, open the menu ''GUI Browser > Recording'' and uncheck ''Record Compound Paths'' there.

== Libraries ==
There are several libraries that can be used for Java connections. Originally a separate library was provided for each technology, but since expecco 21.1 there is a common library that works with all supported Java technologies. Each of the libraries contains connect blocks that all establish a connection of the same type. Therefore, blocks from all libraries can be used in the same test using the same connection.

=== JavaSwingLibrary ===
Contains blocks for testing JavaSwing applications and embedded JavaSwing content. There are also blocks to set the context for embedded JavaFX content (see JavaFXLibrary). Paths for these blocks always refer to the JavaSwing content only, e. g. even if it is embedded in a JavaFX application.

=== JavaSWTLibrary ===
Contains blocks for testing JavaSWT applications.

=== JavaFXLibrary ===
Contains blocks for testing JavaFX applications and embedded JavaFX content. To access embedded JavaFX elements within a Swing application, the context must first be set to the corresponding JFXPanel. There is a block in the JavaSwingLibrary for this purpose. The paths are then resolved within this context. Otherwise the paths are resolved within the existing stages. There are also blocks for embedded WebView. To use these the context must be set to the corresponding WebView.

=== CommonJavaGUILibrary ===
Starting with expecco 21.1 the CommonJavaGUILibrary contains blocks which can be used with all Java elements. If an application uses different Java technologies, [[Java_GUI_Plugins/en#Compound_Paths|compound paths]] are used to specify an element. This eliminates the need to switch to different contexts.

However, this library and the extension of the functionality of the block to each element type is still under construction, so some blocks do not yet work with all elements. Furthermore, the library also requires a corresponding new expecco version.

== Example ==

== FAQ ==


==== The tree in the GUI browser does not show all elements of my application====
An application consists of many different elements. Some of them are not interactive, i.e. they are not directly visible to the user and are only used for formatting, such as panels.

If many such elements are present, the tree can become very large and very deep.
As these elements are usually uninteresting for automation, they can be hidden in expecco by default.
If you need to access one of those elements, or need it to create a unique path, that behavior should be turned off.

The JavaSwingLibrary contains the ''Set Skip Mode'' block for this purpose. On of the following modes can be selected:
::{|
|INTERACTIVE
|Collect only interactive elements
|-
|ALL
|Collect all elements
|-
|INTERACTIVE_HYBRID
|like INTERACTIVE, but with the fallback to ALL if a path cannot be resolved
|-
|ALL_HYBRID
|like ALL, but with the fallback to INTERACTIVE if a path cannot be resolved
|}
:Execution of the block changes the behavior for the current connection. It refers to what is displayed in the tree as well as how the paths on the blocks are handled. Since expecco 19.1 the default is ALL_HYBRID and in earlier versions it is INTERACTIVE.

====I cannot connect, but all settings are correct====
Even though this should not happen in general, here are a few more aspects which affect the connection:
*Firewall The firewall can interfere with the Java Agent's communication with the application. Either set up an exception rule for the agent or deactivate the firewall for the duration of the test.
* Socket in use It can happen, especially when debugging, that a previous instance of a Java agent was not closed correctly. This can lead to it occupying the socket and rejecting other connections. Try "''Extras''" → "''Debugging''" → "''Close all bridge connections / Close all socket connections''". Be warned that this will also close all other existing (local) Expecco connections. In the case of remote connection, a restart of the agent and possibly of the application may help.
== See Also ==
[[Expecco GUI Tests Extension Reference/en]]

Release Notes 23.x

2024-01-11T08:51:47Z

Matilk: link to 24.x release notes

See also: [[Release Notes 24.x]] 
See also: [[Release Notes 22.x]]
 

== Release 23.2 (December 2023) ==
*Feature: [[Environment_Editor/en#Fields|Static (Step-) Variables]]
*Feature: DOM inspector (try an XML attachment) generates better xpath suggestions (alternatives in [[Attachment_Editor/en#XML_Inspector | attachment editor]])
*Feature: [[Testplan_Editor/en#Log_Processor_Action|log processors]] are now configurable both for individual test cases and for the overall result of a testplan
*Feature: [[Testplan_Editor/en#Log_Processor_Action|log processor]] activities are shown in a testplan's activity log (but not in a report)
*Feature: Qt-Library: New Action ''QButton::Click'': direct click, not being delegated to a thread
*Feature: Qt-Testing: ExpeccoTestService library and Inject-Tool for QT5.15.0 and VS2022: [[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]]
*Feature: [[Timeline/en|Timeline view]] for the activity log (Still experimental, might reach its limits with too large logs or while running)
*Feature: more [[Testplan_Editor/en#Execution_Settings | pathname options]] for testplan when generating ELF-per-run result files (in loops)
*Feature: a new [[Testplan_Editor/en#Execution_Settings | option]] in testplan to skip successful tests when looping
*Feature: enhanced manual test wizard with the option to execute the manual tests with a mobile device (Android, Apple IOS or Web-Browser)
*Feature: [[Expecco_API/en#Bridged_Ruby_Elementary_Blocks |bridged Ruby elementary actions]]
*Feature: Improvements in the XML inspector (tree popup menu & string search)
*Feature: [[Expecco_API/en#Bridged_Python_Elementary_Blocks |bridged Python elementary actions]] can now be cancelled and terminated
*Feature: Python settings: Reorganize Python paths, export Python bridge code for debugging in external IDE ([[Installing additional Frameworks/en#Python_Installation|Python_Installation]])
*Feature: improved [[Tools_TestSuiteDifferenceBrowser|difference viewer]] (project and version compare UI)
*Feature: environment: current value (possibly changed from initial value) is saved in .elf log file
*Feature: StandardLibrary: additional optional pins for encoding (e.g. #utf8) in "FileStream [ Open For xxxx ]" blocks
*Feature: Values that cannot be saved in a .elf log file (e.g. web elements) are now saved and restored as UnrestoreableDate instead of nil
*New Python Version: Delivered installation package for Python 3.11.6
*Change in the format of .elf log files to store handled error states. Older expecco versions cannot handle this and might have problems to open such a file.
*Bug Fix: log processor actions were themself added to the log, possibly leading to problems when executed again
*Bug Fix: time-limited actions with the ''timeLimitOK'' flag set did not trigger the enable output pin.
*Bug Fix: zip archive view generated wrong name-list if language setting was EN-US (AM/PM from timestamp was interpreted as part of filename)
*Bug Fix: unicode strings in environment variables could not be stored to CSV files
*Bug Fix: a cancelled compound action did write to an output pin in certain situations

== Release 23.1 ==
*Feature: Continue an interrupted test plan (i.e. even in a new expecco session and/or on another machine)
*Feature: Webtest (Selenium WebDriver): Support of [[Selenium_WebDriver_Plugin/en#Compound_Paths|compound paths]] for embedded elements.
*Feature: Webtest (Selenium WebDriver): [[Selenium_WebDriver_Plugin/en#Recorder|Recorder]] shows available windows and the current frame context.
*Feature: Webtest (Selenium WebDriver): Support of [[Selenium_WebDriver_Plugin/en#Shadow_Elements|shadow elements]] in the GUI browser and recorder, accessible by compound paths.
*Feature: Qt-Plugin supports Qt6 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Qt-Versions]])
*Feature: Expecco Remote Control & Monitoring Service with Web Front-End (App for Android or Apple IOS is available on request) ([[Expecco_Remote_Control_App/en|expecco Mobile Remote App]])
*Feature: Diagram Editor: default style for new connections (e.g. hidden)
*Feature: Diagram Editor: shortcut keys for environment-freeze and others
*Feature: Diagram Editor: connections can be named
*Feature: User defined menu operations: Activity-Log in case of an error
*Feature: Zip-Archive viewer/extractor/inspector in [[Attachment_Editor/en#Zip_Archive_Inspector | attachment editor]]
*Feature: ManualTest actions are now part of the base system; the extra plugin licence is only needed to import Excel test descriptions
*Feature: Logging with microsecond resolution timestamps now works in Windows (if enabled in the settings)
*Feature: Support XML report file fetching via the REST interface
*Feature: PCAN (USB Can-Bus Adapter) is now supported in 64-bit expecco
*Feature: Folders can pass Tags to new sub-elements (inherit)
*Feature: Menu entry to set Test Groups for Tree Elements
*Standard Library: Warning Dialog with Opt-out option (show only once)
*FMU/CBridge: [[Functional Mockup Interface | support FMI2 API; partial support for FMI3]]
*FMU/CBridge: download resources to CBridge (eg. unifmu generated python FMUs work)
*Fix: nth-root: lost precision when applied to higher than 64bit floats.
*Fix: LargeFloats rounding was broken
*Fix: WSDL import with namespace redefinitions
*New [[Mobile_Testing_Plugin/en#Windows|Mobile Testing Supplement]] for Windows with an option in the installer to add Appium to the Autostart.

Mobile Testing Plugin/en

2023-12-22T09:42:59Z

Matilk: /* Windows */ new supplement version

[[Mobile_Testing_Plugin|Deutsche Version]] | '''English Version'''

= Introduction =
With the ''Mobile Testing Plugin'' applications can be tested on Android and iOS devices. This includes both real and emulated devices. It does not matter whether real mobile devices or emulated devices are used. The plugin can (and usually is) used in conjunction with the [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]], which supports the creation of tests. It can also be used to record test procedures.

[http://appium.io/ Appium] is used to connect to the devices. Appium is a free open source framework for testing and automating mobile applications.

We recommend to go through the [[Mobile_Testing_Tutorial/en|Tutorial]] to familiarize yourself with the Mobile Plugin. This tutorial leads step by step through the creation of a test case using an example and explains the necessary basics.

= Installation and Setup =
To use the ''Mobile Testing Plugin'', you must have installed expecco together with the corresponding plugin, and you need the appropriate licenses. expecco communicates with the mobile devices via an Appium server, which either runs on the same computer as expecco, or on a second computer. This must be accessible for expecco.

== Installation Overview ==
'''Computer running expecco:'''
* Java JDK version 8, 9, 10 or 11
'''Computer connected to Android devices :'''
* Appium Server, you can install it via the Mobile Testing Supplement (see below), of which we regularly provide a new version
* Android SDK, you can also get it with the Mobile Testing Supplement
* Java JDK version 8, 9, 10 or 11
'''Computer connected to iOS devices*:'''
* Appium Server, you can install it via the Mobile Testing Supplement for MacOS (see below), of which we regularly provide a new version
* Xcode in a version that supports the iOS version used, available from the Apple App Store
* Java JDK version 8, 9, 10 or 11
* Apple Developer Certificate incl. matching private key (to sign the WebDriverAgent)
* Provisioning Profile for the mobile devices to be used

* Please note that due to the requirements (no connection to non-Apple devices available) iOS devices can only be controlled from a Mac.

Depending on the setup, the above-mentioned computers can also be the same device. expecco can either connect to a remote Appium Server and mobile devices connected to it via the network, or start an Appium Server locally itself and use it with local mobile devices. However, some of expecco's functions that make it easier to create test cases are only available if the mobile devices are connected to the same computer on which expecco is running. A possible setup may therefore look like the following figure:

[[Datei:MobileTestingAufbau.png | 400px]]

The following explains how to install Appium and other necessary applications for Windows and Mac OS.

== Windows ==
The easiest way is to install everything from our Mobile Testing Supplement. However, newer versions do not contain a JDK anymore due to a change in Oracle's license terms, so you have to install it additionally. Of course, you are free to install Appium directly to use the version you want. However, to then be able to start an Appium server with expecco, a suitable batch file must be available and specified in the [[Mobile_Testing_Plugin/en#Plugin_Configuration|settings]]. However, connections can also be established to other running Appium servers.
*'''expecco 23.2''': [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Same versions as in the predecessor, but with updated chromedriver versions
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Same versions as in the predecessor, but the installer now allows to add Appium to the Autostart.
*expecco 22.2 and 22.1: [https://download.exept.de/transfer/h-expecco-22.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 from platform-tools 33.0.2
:''* We added the capability'' startChromedriverTimeout ''to Appium, to get a timeout earlier, if Chromedriver cannot be initialized. (see [[#startChromedriverTimeout|Problems and Solutions]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Contains Appium version 1.22.0, Node still is version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Only minor changes compared to the previous version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Compared to the previous version, Appium was updated to version 1.16.0-rc.1 and node 12 is used.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:This installs Appium in the version 1.12.0 and now additionally contains build-tools in the version 28.0.3 in the android-sdk. Apart from this, it is the same as the previous version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:This installs Appium in the version 1.8.1. In addition, an installation of ''Android Debug Bridge'' and ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) is offered. This covers drivers for a broad range of Android devices, and you won't have to install an individual driver for each device. A '''JDK is not contained anymore (due to a change in Oracle's license terms)''', you have to download it on your own, e.g. from [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: same procedure as for expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:This installs a Java JDK Version 8, android-sdk and Appium Version 1.6.4. The supplement also offers a universal adb driver ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]). This driver supports a wide range of Android Devise, and avoids the need to search for individual device-specific drivers.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:It installs a Java JDK version 8, android-sdk and Appium version 1.4.16. During the installation the graphical user interface of Appium is started, you can close this window immediately. The supplement also offers a universal adb driver (ClockworkMod). This combines drivers for a wide range of Android devices so that you do not have to search for and install a separate driver for each device.

If expecco has to use mobile devices that are connected to another computer, you have to start an Appium server there. You can do this by using the file <code>appium_standalone.cmd</code>. The server is then started on default port 4723. If you want to use a different port number, start the server with

appium_standalone.cmd -p <portnummer>

The server is ready, as soon as the line
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
is displayed, where you can read the used port number at the end.

If your Android device is connected to a remote machine,
you may want to see the live screen locally using a tool like
[https://github.com/Genymobile/scrcpy scrcpy].

When Appium is started for the first time – either standalone or by expecco – it may happen that the Windows firewall blocks access to the node server. Allow the access or Appium cannot be started.

== Mac OS ==
Note: the following can be ignored if you do not plan to test iOS (iPhone) devices. The Mac setup is not needed for Android devices.

=== Xcode ===
Automation with iOS devices needs [https://developer.apple.com/xcode/ Xcode]. You can install it from the App Store. Please make sure that the version matches the tested iOS versions.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
This table is only a simplified overview, better see [https://xcodereleases.com/ Xcode releases] or [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode versions] for the exact versions. For new iOS minor versions, there is usually also a new release of Xcode, e.g. for iOS 10.2 you need at least Xcode 8.2, for iOS 10.3 at least Xcode 8.3, etc. So if you are upgrading to a newer iOS version, you will usually need a newer Xcode version as well. Newer versions of Xcode may not run on older operating systems, which in turn may require an operating system upgrade. If you also want to test older iOS versions, it can be useful to install the corresponding Xcode versions in parallel.

=== Appium ===
You can install Appium either as command-line tool or use it with [https://github.com/appium/appium-desktop Appium Desktop], which provides a GUI to start the server. Meanwhile there is also Appium 2.0, which is not tested with expecco yet and therefore not recommended to use.

==== Appium Desktop ====
Download the newest version of [https://github.com/appium/appium-desktop/releases/ Appium Desktop]. For the Mac, it is best to take the dmg file and install it to the applications. When starting ''Appium Server GUI'' you will probably get the error message, that it is not possible for security reasons. In this case, open the context menu of the app file (right click or Ctrl + click) and choose ''Open'' there. Then confirm that you really want to open the application. From now on you can open the application normally.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Since Xcode 14 there are problems with signing the WebDriverAgent, which Appium loads on the device for the automation. This means that no connection is possible with version 1.22.3-4 of Appium Desktop. In newer versions of WebDriverAgent, this problem is solved, but currently there is no version of Appium Desktop using such a new version (as of November 2022). However, you can manually download a new version (e.g. 4.10.2) and replace the files in Appium. To do this, download one of the two archive files (zip or tar.gz) containing the source code from the [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent download page]. Then open and extract this file. Copy the contents of the folder ''WebDriverAgent-4.10.2' to

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

If you navigate there by Finder, make a context click (right click or Ctrl + click) on the application and choose ''Show Package Contents'' from the menu. Replace all files that are already present with the same name.

==== Install Appium using npm ====
You can install Appium using npm (Node Package Manager) as well. To do this, you have to install node/npm first. This can be done using [https://github.com/nvm-sh/nvm nvm] (Node Version Manager), which you can get on Github. If the following installation instructions should not work for you, you will find detailed information in the [https://github.com/nvm-sh/nvm#readme Readme] there.

Open a Terminal window. Then clone the Github repository of nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
and load it
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Then execute
command -v nvm
to see if it works. It should print ''nvm''. If there is no response, execute
touch ~/.zshrc
and try again.

Now you can install node with the following command.
nvm install 16.15.1
As there are problems installing Appium using the newest version of node, we recommend this version.

After node is installed, you can use it to install Appium:
npm install -g appium

The Appium server now simply can be started with the command
appium
The output will then be written directly to the terminal.

This version also has problems with signing the WebDriverAgent, like explained in [[#Appium_Desktop | Appium Desktop]]. Therefore download a newer version of WebDriverAgent in this case as well and replace the old files. You will find them at
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
We provide older versions of Appium via the Mobile Testing Supplement for Mac OS, with which you can easily install it:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.2)]
:Contains Appium version 1.18.3 and uses node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.0)]
:Only a few changes compared to the previous version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.98)]
:Appium is updated to version 1.16.0-rc.1 and node 12 is used.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.96)]
:This version contains Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.94)]
:This version contains Appium 1.8.0.

* expecco 2.11:[http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.0.94)]
:This version contains Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement for Mac OS]
:Diese Version entält Appium 1.4.16.

After you have downloaded the supplement, you can move it to a directory of your choice (e.g. your home directory) and unpack it there. A suitable command in a shell could look like this, adjust the version number accordingly:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

If your default Xcode installation is the one you want to use, you can start Appium directly from the file in the ''bin'' directory with the appropriate version number:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

If you want to use another Xcode than the one configured as default, you have to tell Appium the corresponding path by using the environment variable ''DEVELOPER_DIR''. For example, if you have installed Xcode in ''/Applications/Xcode-11.3.app'', you can start Appium this way:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

To find out what is set as the default Xcode installation on your system, use this command:

xcode-select -p

If Appium cannot find your Xcode installation, a message like this appears:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
In such a case, restart Appium by specifying a valid ''DEVELOPER_DIR''.

==== Signing WebDriverAgent ====
For automation, Appium installs an App called WebDriverAgent on the device and therefore has to be able to sign it. You need an Apple account and a respective certificate for this. For evaluation you can use a free account. This has the disadvantage that created profiles are only valid for one week and must be recreated afterwards. Also be careful when sharing the account, as certificates may be revoked or invalidated by automatic generation. As a result, apps that have already been signed can no longer be used.

If you already have a respective certificate and its associated private key in your keychain on the Mac, you can have the WebDriverAgent automatically signed. If not, it is recommended to set and manage the signing using Xcode.

First, connect the device you want to use to your Mac via USB. Make sure both the Mac and the device are in the same network or there will be problems when connection with Appium. Start Xcode and open ''Preferences''. Go to the Accounts page and create an entry with your account. You can then click on ''Manage Certificates...'' to see the certificates that belong to that account. To run tests, you need an iOS Development Certificate and the associated private key. If you do not already have one, create one. If you already have one, but it is not in your keychain (indicated by "Not in Keychain"), you can import it. You can do that by the [https://support.apple.com/en-us/guide/keychain-access/welcome/mac keychain access] on your Mac, if you have exported it previously from the keychain, where it is stored. The certificate with the associated key should be in the keychain ''Login''. It can be exported from there as PKCS#12 file (typical ending .p12). To import a certificate into your keychain, select the option ''Import objects'' from the ''File'' menu. If you don't know where the certificate is stored, you can also revoke it in Xcode and recreate it in your keychain. However, only do this if you know that the old certificate is no longer in use because it can no longer be used afterwards. Now the keychain should contain an iOS development certificate.


Now open the WebDriverAgent project in Xcode. If you have installed the Mobile Testing Supplement, you will find it in this directory at
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
If you have installed Appium Desktop, you will find it at
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''

You can use the Finder to navigate to the Xcode project file and open it by double clicking. Note, that you have to perform a context click (right click or Ctrl + click) on the Appium Server GUI app and select ''Show Package Contents'' in the menu, to get to its subdirectory.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Select ''WebDriverAgentLib'' and the page ''Signing & Capabilities''. In the section ''Signing'' set the option ''Automatically manage signing'' and then select a team. Now switch to ''WebDriverAgentRunner'' and do the same there.

By setting the team, the errors showing up for WebDriverAgentRunner should disappear. If Xcode should not be able to create a Provisioning Profile matching the Bundle ID ''com.facebook.WebDriverAgentRunner'', you can edit the latter so that it fits your certificate. After that you can quit Xcode or you can, like explained further below, directly start the build in Xcode, so the project will be already built when Appium wants to use it.

If you now connect to your device from expecco, the WebDriverAgent will be installed and started on it and then switch to the app to be tested. You may still have to trust the execution of the WebDriverAgent on the device. It maybe a sign that you have to do this, if the app WebDriverAgent first appears on the device and tries to start, but then is uninstalled again. To trust the execution, open the settings during the connection setup on the device and then the entry ''Device management'' under ''General''. This entry is only visible if a developer app is installed on the device. You may therefore have to wait until the WebDriverAgent is installed before the entry appears. Select the entry of your Apple account and trust it. Since the WebDriverAgent will be uninstalled again if the start did not work, you have to do this during the connection setup. If this is too hectic for you, you can also execute the following code:

xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

or
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

This installs the WebDriverAgent on the device without deleting it again.

If there are problems while installing the WebDriverAgent, you can also try and start the build in Xcode. Make sure the right target ''WebDriverAgent'' is selected. Error messages in Xcode might indicate easier what the problem is about. Sometimes it even helps to try for a second time, if it took too long for the first time and got aborted. It may occur, that you are asked several times during the build to enter the password for the keychain.

[[Datei:WebDriverAgentCodesign.png]]

Read also the documentation of Appium on [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Setting up tests with iOS devices]. Refer to the [https://support.apple.com/en-us/HT204460 Apple documentation] for details on installing and trusting of apps.

Once the WebDriverAgent is installed on the device, it will be reused for later connections und connecting should work faster. The signed version is then already on your Mac as well and doesn't have to be built again. This should speed up the connect with other devices as well. If you know, that the connect has to build and sign the WebDriverAgent first, it is advisable to set the capability ''wdaLaunchTimeout''. This timeout specifies how long Appium waits for the WebDriverAgents to start up on the device and is per default set to 60000 ms. Building often takes a little longer than one minute, so the connect attempt will be canceled. A value of 120000 will be more reliable here.

== Plugin Configuration ==
Before you start, please check the settings of the Mobile Testing Plugin and adjust them if necessary. Select the menu item "''Extras''" → "''Settings''" → "''Extensions''" → "''Mobile Testing''" (see fig.). By default, these paths are found automatically (1). To adjust a path manually, deactivate the corresponding check mark at the right. You'll see a drop-down list with some paths to choose from. If an entered path is wrong or cannot be found, the field is marked red and a message appears. Make sure that all paths are specified correctly.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Plugin Configuration]]

*'''appium''': Enter the path to the executable file with which Appium can be started in the command line. Under Windows this file will usually be called "<code>appium.cmd</code>". This path is used when expecco starts an Appium server.
*'''node''': Enter the path to the executable that starts Node (also called (also called "Node.js"). This path is passed to Appium when a server is started so that Appium can find it independently of the PATH variable. Under Windows this file is usually called "<code>node.exe</code>".
*'''JAVA_HOME''': Enter the path to a JDK (Java Development Kit)here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable. To specify which Java should be used by expecco, set this path in the Java Bridge settings.
*'''ANDROID_HOME''': Enter the path to an Android SDK here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable.
*'''adb''': The path to the adb command. Under Windows the file is called "<code>adb.exe</code>". This file is used by expecco, for example, to get the list of connected devices. This path should be selected automatically, if the command is found in the ANDROID_HOME directory. This is also used by Appium. If expecco and Appium use different versions of adb, conflicts may occur.
*'''android.bat''': This file is only needed to start the AVD and the SDK Manager, which deal with phone emulators. The file in the ANDROID_HOME directory will be selected automatically, if present there.
*'''aapt''': The path to the "aapt" command here. Under Windows this file is called "<code>aapt.exe</code>". expecco uses "aapt" only in the connection editor to read the package and activities of an "apk" file. The file in the ANDROID_HOME directory will be selected automatically, if present there.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | JDK Configuration]]

Starting with expecco 2.11, there is an additional field called ''Team ID''. If you run iOS tests, enter the Team ID of your certificate here. This is used for every iOS connection, unless you change the value in the connection settings in individual cases. For information on how to obtain the team ID, please refer to the section on [[#Signing| signing]] for installations on Mac OS. With expecco 2.10 and older, you can only enter the Team ID as capability for each connection setting separately. However, you must use the [[#Extended_View|extended view]] to do this. Enter the capability ''xcodeOrgId'' here and set the Team ID of the certificate as value.

The server address setting at the bottom of the page refers to the behavior of the connection editor. It checks at the end whether the server address ends in ''/wd/hub'' as this is the usual form. If not, a dialog asks how to react. The defined behavior can be viewed and changed here.

Also switch to the entry ''Java Bridge'' (see figure). Here you have to specify the path to your Java installation, which is used by expecco. Enter a JDK here. If you want to use the one from the Mobile Testing Supplement under Windows, the path is
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
You can also use the system settings.

== Prepare Android Device ==
If you connect an Android device under Windows, you may still need an adb driver for the device. You can usually find a suitable driver on the manufacturer's website. If you have installed the universal driver from the Mobile Testing Supplement, everything should already work for most devices. In some cases, Windows will automatically try to install a driver when you connect the device for the first time. 
'''Attention''': Before you can control a mobile device with the Appium plugin, you have to allow this debugging!

For Android devices, you can find this option in the settings under ''[https://developer.android.com/studio/debug/dev-options Developer Options]'' called ''USB-Debugging''. If the developer options are not displayed, you can unlock them by tapping Build Number seven times in About the Phone.

Also enable the ''Stay awake'' feature to prevent the device from turning off the screen during test creation or execution.

For security reasons, USB debugging must be allowed for each computer individually. When connecting the device to the PC via USB, you must agree to the connection on the device. If you haven't done this for your computer yet, but no corresponding dialog appears on the device, it may help to unplug and reconnect the device. This can happen especially if you have installed the ADB driver while the device was already connected via USB. If this doesn't help either, open the notifications by dragging them from the top of the screen. There you will find the USB connection and you can open the options. Select another type of connection; usually MTP or PTP should work.

You can also test on an emulator. It does not need to be prepared separately, as it is already designed for USB debugging. It is even possible to start an emulator at the beginning of the test.

To check if a device you have connected to your computer can be used, open the [[#Connection_Editor|connection editor]]. The device should be displayed there.

=== Connection via WLAN ===
It is possible to connect to Android devices via Wireless LAN. For devices using Android 11 or newer, this can be done wirelessly, else you have to connect initially via USB. Since expecco 22.1, WiFi connections can be established using the [[Mobile_Testing_Plugin/en#Connection_Editor|Connection Editor]]. It is also possible to do this using a command window.
==== Wireless Connect (Android 11) ====
In the developer options of your device, enable wireless debugging and open its options. You initially have to pair your machine with the device. To do this, choose "''Pair device with pairing code''" to get a pairing code and an IP address with port. Then open a command window (terminal window) on your machine and enter:
<nowiki>adb pair <Device IP Address>:<Pairing Port></nowiki>
where <tt><Device IP Address>:<Pairing Port></tt> is the IP address and port as shown on the device. After that, you will be asked for the pairing code. If everything went right, the popup on the device should have closed and your machine is added to the list of paired devices. Then enter at the command window:
<nowiki>adb connect <Device IP Address>:<Debugging Port></nowiki>
The IP address is the same as for pairing, but the port is different. Both are shown as IP address & Port on the device. The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted. Restarting the device often disables wireless debugging and the used port is changed. The pairing, however, is permanent and has not to be done again the next time you connect.
==== Start via USB ====
First, connect your device via USB. Then open a command window (terminal window) and enter:
<nowiki>adb tcpip 5555</nowiki>
The device listens for a TCP/IP connection on port 5555. If you have several devices connected or emulators running, you have to specify which device you mean. Enter in this case:
<nowiki>adb devices -l</nowiki>
to get a list of all devices, where the first column gives the device's ID.
Then, enter:
<nowiki>adb -s <deviceID> tcpip 5555</nowiki>
with the device identification of the desired device. You can now disconnect the USB connection. Now you have to find out the IP address of your device. You can usually find it somewhere in the device's settings, for example in the Status or WLAN settings of the phone. Then type in:
<nowiki>adb connect <IP address of device></nowiki>
The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> again or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted.

== Preparing an iOS-Device and App ==
Control of iOS devices is only possible via a Mac. Please also read the section [[#Mac_OS|Installation under Mac OS]].

Before you can control a mobile device with the Mobile Testing Plugin, you must allow debugging for iOS devices with iOS 8 or higher. Activate the option "''Enable UI Automation''" under the "''Developer''" menu in the device settings. If you cannot find the "''Developer''" entry in the settings, proceed as follows: Connect the device to the Mac via USB. If necessary, you must still agree to the connection on the device. Start Xcode and then select "''Devices''" from the menu bar at the top of the screen in the "''Window''" menu. A window opens in which a list of the connected devices is displayed. Select your device there. Then the entry "''Developer''" should appear in the settings on the device. You may have to exit the settings and restart.

[[Datei:Alert.png | thumb | 270px | Alert unter iOS]]
It is not possible to establish a connection to the device as long as it shows certain alerts. Such an alert may appear if FaceTime is activated (by displaying a message about SMS charges as shown in the screenshot). Be sure to configure the device so that it does not show such alerts when idle.

=== expecco 2.11 and later ===
You can test any app which is executable or already installed on the device used. If the app is available as a development build, the UDID of the device must be stored in the app. In any case, the WebDriverAgent must be signed for the device. Please read the section about [[#Signing|signing]] under Mac OS.

If you want to use the Home button in a test, you must activate "AssistiveTouch" on the device. You will find this option in the settings under "''General''" > "''Operating Help''" > "''AssistiveTouch''". Then place the menu in the middle of the upper edge of the screen. You can then record pressing the Home button with the corresponding menu entry in the recorder or use the "''Press Home Button''" block directly.

=== expecco 2.10 ===
The app you want to use must be available as a development build. The UDID of the device must also be stored in the app.

=== Sign the development build ===
A development build of an app is only allowed for a limited number of devices and cannot be started on other devices. However, it is possible to exchange the certificate and the usable devices in a development build.

* Evaluation with demo app of eXept:
:We will be happy to provide you with a demo app which is available as a development build and which we can sign for your device. Please send the UDID of your device to your eXept contact person. How to determine the UDID of your device is described in the following section.

* Using your own app for your test device:
:If you receive a development build (IPA file) from the app developers that is approved for your test device, you can use it directly. To do this, you must tell the developers the UDID of your device so they can enter it. '''You can use Xcode to read the UDID of a device'''. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window opens in which a list of the connected devices is displayed. Select your device and search for the ''Identifier'' entry in Properties. The UDID is a 40-digit hexadecimal number.

* Externally developed app for your test device:
:You can also re-sign apps to make them run on other devices. However, this process is complicated and requires access to an Apple Developer account. A documentation on the procedure is currently in preparation.

:For the evaluation we will gladly support you with the re-signing of your app..


For more information about using iOS devices, see also the
[http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Appium documentation].

=== Native iOS-Apps ===
You can also use apps that are already natively present on the device. To do this, you must know their bundle ID and then enter it in the connection settings. Here is a small selection of common apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

You can find further Bundle-IDs [https://github.com/joeblau/apple-bundle-identifiers here].

= Examples =
In the demo test suites for expecco you will also find examples for tests with the Mobile Testing Plugin. To do this, select the option "''Example from File''" on the start screen and open the folder named "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
The test suite contains two simple test plans: "''Simple CalculatorTest''" and "''Complex Calculator and Messaging Test''". Both tests use an Android emulator, which you must start before starting. The apps used in the test are part of the basic equipment of the emulator and therefore no longer need to be installed. Since the apps may differ under every Android version, it is important that your emulator runs under Android 6.0. In addition, the language must be set to English.

; Simple CalculatorTest
: This test connects to the calculator and enters the formula ''2+3''. The result of the calculator is compared with the expected value ''5''.

; Complex Calculator and Messaging Test
: This test connects to the calculator and then opens the message service. There it waits for an incoming message from the number ''15555215556'', in which a formula to be calculated is sent. The message is generated before via a socket at the emulator. When the message arrives, it is opened by the test and its contents are read. Then the calculator is opened again, the received formula is entered and the result is read. The test then switches back to the message service and sends the result as an answer.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
These are part of the tutorial for the Mobile Testing Plugin. The included test case is incomplete and will be added during the tutorial. Please read the section [[#Tutorial|Tutorial]].

= Tutorial =
There is a tutorial describing the basic procedure for creating tests with the Mobile Testing Plugin. It is based on a supplied example consisting of a simple app and an expecco test suite.

You find it on the page [[Mobile_Testing_Tutorial/en|Mobile Testing Tutorial]] in two versions for Android and iOS devices.
*  [[Mobile_Testing_Tutorial/en#First_steps_with_Android|First steps with Android]]
*  [[Mobile_Testing_Tutorial/en#First_steps_with_iOS|First steps with iOS]]

= Dialogs of the Mobile Testing Plugin =
== Connection Editor ==
You can use the Connection Editor to quickly define, change, or establish connections. Depending on the task, the dialog has small differences and is opened differently:
*If you want to establish a connection, access the dialog in the GUI browser by clicking on ''Connect'' and then selecting ''Mobile Testing''.
*To change or copy an existing connection in the GUI browser, select it, right-click and select ''Edit Connection'' or ''Copy Connection'' from the context menu.
*If you do not want to create connection settings for the GUI browser but for use in a test, choose ''Create Connection Settings'' from the Mobile Testing Plugin menu.... This only allows you to create the settings for a connection without creating a connection in the GUI browser.

The Connection Editor menu has several buttons, some of which are only visible when creating connection settings:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#''Delete Settings'': Resets all entries. (Only visible when creating settings.)
#''Load settings from file'': Allows to open a saved settings file (*.csf). Its settings are transferred to the dialog. Entries already made without conflict are retained.
#''Load settings from attachment'': Allows you to open an attachment with connection settings from an open project. These settings are applied to the dialog. Entries already made without conflict are retained.
#''Save settings to file'' and
#''Save settings to attachment'': Here you can save the entered settings to a file (*.csf) or create them as an attachment in an open project. Both options have a delayed menu in which you can choose to save only a certain part of the settings. (Only visible when creating settings.)
#''Advanced View'': Allows you to switch to the advanced view to make additional settings. Read more about this at the end of this chapter. (Only visible when creating settings.)
#''Help'': A help text for the respective step is shown or hidden on the right side.

The dialog is divided into three steps. In the first step you select the device you want to use, in the second step you select which App should be used and in the last step the settings for the Appium server are made.

===Step 1: Select Device ===
In the upper part you will see a list of all connected Appium devices that are detected. With the checkbox below you can hide devices that are detected but not ready. If you want to enter a device that is not connected, you can create it with the corresponding button ''Enter Android device'' or ''Enter iOS device''. However, you need to know the required properties of your device. The device is then created in a second device list and can be selected there. If no list with connected elements can be displayed, various messages are displayed instead:
*No devices found
*:expecco could not find any Android devices.
*:To automatically configure a connection to a device, make sure
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*No available devices found
*:expecco could not find any available Android devices. But not available ones were found, e.g. with the status "unauthorized".
*:To configure a connection to a device automatically, make sure that
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*:To view unavailable devices, enable this option below.
*Connection lost
*:expecco has lost the connection to the adb server. Try to re-establish the connection by clicking on the button.
*Connection failed
*:expecco could not connect to the adb server. Possibly it is not running or the specified path is not correct.
*:Check the adb configuration in the settings and try to start the adb server and establish a connection by clicking on the button.
*Connect ...
*:expecco connects to the adb server. This may take a few seconds.
*Start adb-Server ...
*:expecco starts the adb-Server. This may take a few seconds.

With ''Next'' you get to the next step. If you enter settings for the GUI browser, this is only possible once a device has been selected.

Note on unlocking: In newer Android versions the developer options are no longer offered in the settings at first. If your Android device does not show an entry for "''Developer options''" in the settings, first select the entry "''Phone info''", then "''SoftwareVersionsInfo''" and click on the entry "''BuildVersion''" several times.

==== Manage Chromedrivers ====
If the App you want to automate uses WebViews with Chrome, Appium needs to have access to an appropriate Chromedriver. If you have selected a device in the list, you can use "''Manage Chromedrivers''" to see, which Chrome versions are installed on the device and which Chromedriver versions are provided by expecco. With this dialog you can also download required Chromedriver versions. Beware that there may be several Chrome versions on the device. An App doesn't have to use the version of the installed Chrome browser for its WebViews. The Chromedriver you use should fit your app for everything to work properly. You can also change the path to the Chromedriver in the capabilities generated at the end of the connection editor.

==== Connect WiFi Android Device ====

You can connect to Android devices using WiFi as well. In this case, the device has to be connected to ADB first, see [[Mobile_Testing_Plugin/en#Connection_via_WLAN|Connection via WLAN]]. Since expecco 22.1, the connection editor provides a dialog helping to set this up, which can be used instead of the command window. For devices using Android 11 or newer, you can pair the device with your machine here by specifying the appropriate parameters and then establish the connection by specifying the IP address and port. You can also use this to establish a wireless connection for devices that are connected via USB. When you select the corresponding device in the list, the required information is read out automatically.

Note that establishing a wireless connection is not part of the connection settings. If you want to establish a new connection with the generated settings, you must make sure that the device is connected to ADB with the specified IP address and port so that it can be found. The ADB connection will be lost if the ADB server or the device are restarted. The permission for wireless debugging is also often reset when the device is restarted and the debug port can then change. Therefore, a wireless connection must always be established manually.

===Step 2: Select App===
Here you can enter information about the app to be tested. You can decide if you want to use an app that is already installed on the device or if you want to install an app for the test. Select the appropriate tab above. Depending on whether you selected an Android or an iOS device in the previous step, the required input will change.

*'''Android'''
**''App on Device''
**:If you have selected a connected device in the first step, the packages of all installed apps are automatically retrieved and you can select from the drop-down lists. The installed apps are divided into third-party packages and system packages; select the appropriate package list. This selection does not belong to the settings, but only provides the corresponding package list. You can use the filter to further narrow down the list and then select the desired package. The activities of the selected package are also automatically retrieved and made available as a drop-down list. Select the activity you want to start. As a rule, an activity is automatically entered from the list. If you are not using a connected device, you must enter the package and the activity manually.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. If you are using a local Appium server, you can use the right button to navigate to the App installation file and enter this path. If possible, the corresponding package and the activity are also entered in the fields below. However, this entry is not necessary.

*'''iOS'''
**''App on Device''
**:Specify the bundle ID of an installed app. You can find out the IDs of the installed apps using Xcode, for example. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window will open displaying a list of connected devices. If you select your device, you will see a list of the apps you have installed in the overview.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. For the requirements of apps for real devices, please read the section [[#iOS-Ger.C3.A4t_and_App_Preparing|Preparing an iOS-Device and App]].

In the lower part you can specify whether the app should be reset or uninstalled when the connection is terminated, and whether it should be reset initially. Again, the corresponding capability is not set if you select ''(Default)''. With ''Next'' you get to the next step.

===Step 3: Server Settings===
In the last step, a list of all the capabilities that result from your entries in the previous steps is first displayed in the upper part. If you are familiar with Appium and want to set additional capabilities that are not covered by the connection editor, you can click on ''Edit'' to open the extended view. See the section below for more information.

If you enter settings for the GUI browser, you can enter the ''Connection name'' with which the connection is displayed. This is also the name under which devices can use this connection when it is established. If you leave the field blank, a name will be generated. If the box "''Managed by expecco''" is checked, expecco will start a local Appium server on a free port, or use a free server that has already been started. To use your own server, turn this feature off and enter the appropriate address. You will get the local default address and already used addresses to choose from.

In older expecco versions the box is labeled "''Start on demand''". In this case, you must also enter an address if you want expecco to start the server. expecco then tries to start an Appium server at the given address when connecting, if none is running there yet. This server will then also be shut down when the connection is terminated. This only works for local addresses. Make sure that you only use port numbers that are free. It is best to only use odd port numbers from the standard port 4723. The following port number is also used when establishing a connection, which could otherwise lead to conflicts.

Depending on how you opened the dialog, there are now different buttons to close it. In any case you have the option to save. This opens a dialog where you can either select an open project to save the settings there as an attachment, or choose to save it to a file that you can then specify. Saving does not close the dialog, allowing you to select another option.

If you have opened the editor for establishing a connection, you can finally click on ''Connect'' or ''Start and connect server'', depending on whether the check mark for server start is set. For changing or copying a connection in the GUI Browser, this option is called ''Apply'', since in this case only the connection entry is changed or created, but the connection setup is not started. If necessary, you can do this afterwards via the context menu. If you have changed capabilities of an existing connection, a dialog then prompts you to decide whether these changes should be applied directly by closing the connection and establishing the new connection or not. In this case, the changes only take effect after you reestablish the connection.

To use the connection editor, also read the corresponding section in the respective tutorial in step 1. (Android: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo|Run Demo]], iOS: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo_2|Run Demo]]).

===Extended View===
The extended view of the connection editor can be obtained either by clicking on ''Edit'' in the third step or at any time via the corresponding menu item if you have started the editor via the plugin menu. This view displays a list of all configured Appium Capabilities. You can add, change or remove further entries to this list. To add a capability, select it from the drop-down list of the input field. In this list all known capabilities are sorted into the categories ''Common'', ''Android'' and ''iOS''. If you have selected a capability, a short information text is displayed. You can also enter a capability manually in the field. Then click on ''Add'' to add the capability to the list. There you can set the value in the right column. To delete an entry, select it and click on ''Remove''. With ''Back'' you leave the extended view.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Running Appium Servers ==
In the menu of the Mobile Testing Plugin you will find the entry ''Appium-Server...''. This opens a window with an overview of all Appium servers started by expecco and on which port they are running. By clicking on the icon in the column ''Show Log'' you can view the logfile of the corresponding server. This is deleted when the server is shut down. With the icons in the column ''Exit'' the corresponding server can be terminated. However, this is prevented if expecco still has an open connection via this server. The rightmost column shows for which connection the server is in use. If it reads ''<idle>'', the server is currently not used by expecco.

[[Datei:MobileTestingAppiumServer.png]]

When opening the editor to start an Appium connection, an Appium server is started immediately to speed up the connection process. For this purpose, expecco always keeps one idle running Appium server. Additional running servers however, which are not in use anymore, will be terminated automatically after a while.

In the menu of the Mobile Testing Plugin you will also find the entry ''Close all Connections and Servers''. This is intended for cases where connections or servers cannot be terminated in any other way. If possible, always terminate connections in the GUI browser or by executing a corresponding block. Servers that you have started in the server overview should be terminated there; servers that were started with a connection are automatically terminated with this connection.

Note that only servers started and managed by expecco are listed in the overview. Possible other Appium servers that were started in a different way are not recognized.

== Recorder ==
If the GUI browser is connected to a device, the integrated recorder can be used to record a test section with that device. To start the recorder, select the appropriate connection in the GUI browser and click the Record button. A new window opens for the recorder. The recorded actions are created in the GUI browser work area. It is therefore possible to edit the recorded data in parallel.

[[Datei:MobileTestingRecorder.png|caption|]]

====Components of the Recorder Window====
#'''Continue/Pause Recording''': You can pause the recording by clicking the right icon. You will then see a large pause sign in the view. All actions that you perform now in the recorder are executed, but no blocks are recorded. You can switch back to normal recording mode by clicking the left icon.
#'''Stop Recording''': Stops the recording and closes the recorder window.
#'''Update''': Gets the current image and element tree from the device. This is necessary if the device takes longer to execute an action or if something changes without being triggered by the recorder. Since expecco 21.2, there is an additional submenu here that can be used to enable automatic update by checking for changes in the background (see also ''Automatic Update'' further below).
#'''Follow Mouse''': Select the element under the mouse pointer in the GUI browser.
#'''Element Highlighting''': The element under the mouse is outlined in red.
#'''Show Elements''': Show the borders of all elements in the view.
#'''Tools''': Selection, which tool is used for recording. The selected action is triggered with each click on the view. The following actions are available:
#*Element Actions:
#**Click: Short click on the element under cursor. To determine more precisely which element is used, use the Follow Mouse or Element Highlighting function.
#**Tap with Duration (Element): Similar to click, except that the duration of the click will be recorded as well. This allows the recording of long clicks.
#**Tap with Position (Element): Similar to click, but additionally records the position inside the element. The position can be recorded relative to the element size or, when pressing Ctrl while clicking, as absolute position from the upper left corner of the element.
#**Set Text: Allows to set the text of an input field.
#**Clear Text: Clears the text of an input field.
#*Device Actions:
#**Tap (Screen): Triggers a click at the screen position.
#**Tap with Duration (Screen): Triggers a click at the screen position, which also considers the duration.
#**Swipe: Swipe in a straight line from the point where you press the mouse button until you release it. The duration is also recorded.
#:Please note for this actions that the result may differ on different devices, e.g. with different screen resolutions.
#*Test Flow Blocks
#**Check Attribute: Compares the value of a specified attribute of the element with a predefined value. The result triggers the corresponding output.
#**Assert Attribut: Compares the value of a specified attribute of the element with a predefined value. If the values are not equal, the test fails.
#**Get Attribute: Gets the current value of a specified attribute of the element.
#*Auto
#:If the Auto tool is selected, you can use all actions by specific input methods: ''Click'', ''Tap Element'' and ''Swipe'' still work by clicking, but are distinguished by the duration and movement of the cursor. To trigger a ''Tap'', hold down Ctrl while clicking. The remaining actions are available in a context menu by right-clicking on the element.
#'''Context Actions''': Here you can record actions concerning contexts:
#*Switch to Context: Shows a list of all currently available contexts and you can select to which one you want to switch.
#*Get Current Context: Gets the handle of the current context.
#*Get Context Handles: Gets a list of all currently available contexts.
#'''Softkeys''': Only for Android. Simulates pressing the buttons Back, Home, Menu and Power.
#'''Home Button''': Only for iOS since expecco 2.11. Allows pressing the Home button.Prior to expecco 19.2, it only works if AssistiveTouch is activated and the menu is located in the middle of the upper screen border. From expecco 19.2 on, the function no longer uses AssistiveTouch.
#'''Help''': Opens this online documentation on the general page about [[GuiBrowser_Recorder/en|GUI Browser recorders]].
#'''View''': Shows a screenshot of the device. Actions are triggerd by mouse depending on the selected tool. If a new action can be recorded, the window has a green frame, else it is red.
#'''Resize Window to Image''': Resizes the recorder window so that the screenshot can be displayed completely.
#'''Resize Image to Window''': Scales the screenshot to a size that makes use of the full size of the window.
#'''Adjust Display''': Opens a dialog to adjust the displayed image, if expecco does not show it right. You can correct the scaling or rotate the image by 90°.
#'''Correct Orientation''': Corrects the image if it is upside down. Using the arrow to the right, the image can also be rotated by 90°, if this should ever be necessary. Since expecco 19.1 you find this functionality under ''Adjust Display''. The orientation of the image is irrelevant for the functionality of the recorder, it only works on the elements it receives.
#'''Scaling''': Changes the scaling of the screenshots.
#'''Messages''': Shows the path of the current selected element or other messages. It has a context menu to show a list of previous messages.

====Usage====
Each click in the window triggers an action and is recorded in the workspace of the GUI browser. There you can run, edit, or create a new block from what you have recorded. You find the actions to trigger softkeys directly in the menu bar (see above). To record actions on elements, either change the selection of the tool in the menu bar (see above) and then click on the element or select the corresponding action from the context menu by right-clicking on the corresponding element. For text input it is also possible to place the cursor over the element and enter the text. This opens the input dialog for this action. On how to use the recorder, see also step 2 in the tutorial ([[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_Block_with_the_Recorder|Android]] resp. [[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_block_with_the_Recorder_2|iOS]]).

====Hide elements====
Since expecco 21.2 it is also possible to hide the selected element in the recorder from the context menu. This means that this element cannot be selected from now on. This function is useful for ignoring elements that are in the foreground to be able to access elements below them. To undo this state, you have to find the corresponding element in the tree of the GUI browser, which also has such an entry in the context menu.

====Automatic Update====
The recorder doesn't show a live image of the device, but only a snapshot. Therefore an update is needed after changes to match what is displayed on the device. The recorder updates automatically after executing an action. Since expecco 20.2 there are further automatic updates possible. You can enable the, in the menu "View".

One option is, to check after an action has been executed, if there are further changes after the first update. If so, a second update is triggered. This shall fix the problem, that the recorder is not up to date after an action, because the update has been done too early.

The second option is to enable a periodical update. After a set interval the recorder is automatically updated if there are changes. Thereby the recorder view is mostly up to date, but this causes an overhead regarding the communication to the device.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid Apps and WebViews =
'''!!! IMPORTANT NOTICE - If you have problems switching to the webview, please set the "Default Application - Browser App" in Android Settings to "Chrome" !!!'''

Hybrid apps contain platform native elements as well as other elements that are integrated in a WebView. These elements can also be used, but you first have to switch to the corresponding context. With the block ''Get Current Context'' you get the current context. Initially this is ''NATIVE_APP'', i.e. the context of the native elements. With the block ''Get Context Handles'' you get a collection of all existing contexts. If there is a WebView context, it is called ''WEBVIEW_1'' or ''WEBVIEW_<package>'' with the package of the WebView. Several WebView contexts are also possible. For each WebView context, there is a corresponding WebView element in the native context. You can use the ''Switch to Context'' block to switch to such a context and from now on only have access to the elements in this context.

In the GUI browser, the existing contexts are displayed at the top of the tree as well as the tree of a context is inserted below the corresponding WebView element.

=Customizing XPath using the GUI Browser=
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen ''GTIN-13 (EAN-13)'' und ''Verify'', das Eingabefeld der Zahl ''4006381333986'' und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des GTIN-13-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch ''Pfad überprüfen'' (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit ''Verify Path: OK'' (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit * zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert ''GTIN-13 (EAN-13)'' besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer ''hierarchy'' (für iOS wäre es ''AppiumAUT''), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix ''android.widget.'', das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend ''XCUIElementType'' am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. ''FrameLayout'' ist ein Kindelement von ''hierarchy'', ''LinearLayout'' ist ein Kind von ''FrameLayout'' usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element ''hierarchy'' beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben ''TextView''-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ ''Button'' gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut ''resource-id''. Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut ''name'' verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem @ eingeleitet und der Wert mit einem = in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter ''Test'' eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf ''Lauf''. Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu ''Eigenschaften'', wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

=Problems and Solutions=
== Locators depend on the version or are variable ==
In this case consider to either store the locators (xPath) in a variable or to define a locator mapping inside a screenplay attachment. It is also possible to store just parts of an locator (e.g. locator path of a parent or attribute value) in a variable and add them in the freeze value of the locator pin by "''$(varName)''".

== Invisible UI Elements ==
Note that the [[#Recorder|Recorder]] also considers items that you cannot see on the screen. Therefore, turn on element highlighting or use the follow mouse function and the element tree in the GUI browser to determine if the correct element is used. It can happen, that invisible elements are in front of other elements and cover them, so that the desired element cannot be selected in the recorder. See section [[#Hide_elements|Hide elements]] for a solution to this.

== iOS: Cable not certified ==
In some cases, when connecting an iOS device via USB, a message appears indicating that the cable used is not certified. In this case, replacing the respective cable is the only solution.

== iOS: Alerts when connecting ==
Make sure that no alerts are open when connecting to an iOS device. Otherwise the connection will fail because the app cannot be brought to the foreground. See also [[#Preparing_an_iOS-Device_and_App|Preparing an iOS-Device and App]].

== iOS: .ipa cannot be installed ==
Note that on iOS simulators no ''.ipa'' files can be installed but only ''.app'' files.

==iOS: First Connect is not working==
If there is not already a signed build of the WebDriverAgent on your Mac, it has to be created during the first connect. Usually, this can take a little longer than one minute. Per default Appium uses a timeout of 60000 ms to wait for the WebDriverAgent to start on the device, so the connect will be canceled in that case. You can set this timeout with the capability ''wdaLaunchTimeout'', e.g. to ''120000''.

Moreover, the signing settings have to be correct. In our experience, the most reliable solution is to set automatic signing in the WebDriverAgent Xcode project an selecting the team there. See the explanation in section [[#Signing_WebDriverAgent|Signing WebDriverAgent]] for that. In this case you should '''not''' use the capabilities ''xcodeConfigFile'' resp. ''xcodeOrgId'' and ''xcodeSigningId'', as they could cause a conflict. Caution: If you have set a Team ID in the Mobile Testing settings, expecco will automatically set this as ''xcodeOrgId''!

Pay attention to your device during the first connect. You might have to agree to the installation by entering your password. On the Mac you might need to enter the password to allow access to the key chain for signing, often several times.

== Android: Device not visible in the connect editor ==
If an Android device connected via USB does not appear in the connection editor, try changing the USB connection type. Usually MTP or PTP should work. Check again, if "USB Debugging" is enabled in the developer options on the device (these options are disabled on some devices and have to be enabled first using a trick.) See also [[#Prepare_Android_Device|Prepare Android Device]].

== Android: Truncated Elements at Bottom ==
For Android devices that automatically show and hide the navigation bar/softkeys, the recorder may cut off elements in the lower area that would be hidden by the softkeys, even if they are not displayed at this time. In this case it is advisable to set the softkeys so that they are permanently displayed.

For newer Android versions there usually is no such option. Even if the controls are visible all the time, they don't have their own space, but are on top of the content of the app. Therefore, there is an area on the lower part of the screen, which cannot be automated, because it is not counted to the active area of the app. Appium will then truncate the elements there. This area can even be larger then the needed by the controls. This is a known issue for Samsung devices with Android 11. Since the information about the size of the app area is already provided on Android level, we cannot offer a solution for this, but can only hope that the problem will be fixed by the manufacturer. You may try to get better results by setting the control to gestures, but this bears the same issue.

== Android: Test Hangs While Finding an Element==
The block ''Find Element by XPath'' and all element blocks wait until an element is present for the given path. The timeout for this can be set either directly at the block or in the environment variables. However, if the element should already be present, but the test doesn't continue anyway, the reason could be in the UIAutomator/UIAutomator2. It waits for the app to go to the idle state before it even starts to search for the element. This may take longer, if the app e.g. runs an animation in the background or executes other kinds of actions. Fetching the page source, e.g. when updating in the GUI browser or in the recorder, can also take longer for this reason. There is a default timeout of 10 seconds after which it no longer waits for the idle state. This timeout can be set in Appium (waitForIdleTimeout). If you want to change the value of this timeout, you can do this since expecco 21.2 by executing the Smalltalk code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> before the test. The timeout is given in milliseconds, so the example sets it to 2 seconds.

==Android: Updating the Tree or Switching to Webview Context takes too long==
Especially with older devices it can happen that newer Chromedriver cannot be initialized. This makes it impossible to switch to the webview context. However, this is only detected over a timeout by Appium, which is 4 minutes by default. Since expecco also tries to switch to the webview context when building the tree in the GUI browser, this can lead to very long loading times. Since there is no way to decrease this timeout in Appium, we have added a corresponding capability to the version we provide in the MobileTestingSupplement. Starting with version 1.13.1.0 of the [[#Windows|MobileTestingSupplement]], ''chromedriverStartTimeout'' can be used to set the timeout in milliseconds. The switch still doesn't work then, but expecco doesn't take as long to update the tree and the context switch module fails faster. The connection dialog adds this capability automatically starting with expecco 22.1.

== No Action on Click ==
The block to click on an element is successful, but no action was performed on the device.
:This can happen if the element is hidden by another element and therefore clicking on the element is not possible. In this case, Appium does not throw an error, but simply nothing happens. If you would like to make a click at the position of the element anyways, even if it is hidden, use the block ''Tap'' instead and pass the location of the element to it (''Get Location''). If instead you want to check before a click whether the element is hidden at this moment, try whether the properties ''Is Displayed'' or ''Is Enabled'' might help you.

== No Update After Action ==
An action was triggered on the recorder and a block has been recorded, but the recorder still shows the old image.
:The recorder doesn't show a live image of the device, but only a snapshot. After an action has been executed, the recorder will update automatically. However, it can happen, that the image has already been updated before the effects of the action are fully completed on the device. In this case you should update the recorder by hand using the icon with the blue arrows. Since expecco 20.2 you can also enable automatic updates for this case. See also the description for the [[#Recorder|recorder]].

== Attribute "clickable" is wrong ==
An element has for the attribute/property "''clickable''" the value "''false''", but is actually clickable.
:The attribute "''clickable''" has to be set explicitly by the app developer and does not affect the behavior of the app. You should generally disregard this attribute in your tests. Unfortunately, many apps exist where the programmer was "lazy" about this.

==Connecting Fails==
If the connection to the Appium server fails, you will receive an error message in expecco similar to the one shown below.

[[File:MobileTestingVerbindungsfehler.png]]

Here you can see the type of error that has occurred. Click on "''Details''" to get more information. Possible errors are:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:The specified server is not running or is not reachable. Check the server address.
*''org.openqa.selenium.WebDriverException''
:Read the message after ''Original Error'' in the first line of the details:
:*''Unknown device or simulator UDID''
::Either the device is not connected properly or the udid is not correct.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::This error can have various causes. Either the WebDriverAgent could actually not be built because the signing settings are wrong or the appropriate provisioning profile is missing. Please read the section about [[#Signing|Signing]]. It is also possible that the WebDriverAgent cannot be started on the device, for example because an alert is in the foreground or you did not trust the developer.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::The specified app cannot be installed on the iOS device because it is not entered in the app's Provisioning Profile.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.''
::The path to the app is wrong. Make sure that the file is located in the specified path on your Mac.
:*''packageAndLaunchActivityFromManifest failed.''
::The specified ''apk'' file is probably broken.
:*''Could not find app apk at [...]''
::The path to the app is wrong. Make sure that the ''apk'' file is located in the specified path.

If the error is not due to one of the causes listed above, the automation applications on the device may no longer function properly. In this case it helps to uninstall them from the mobile device. They are then automatically reinstalled the next time a connection is established.

*For iOS devices, this is the WebDriverAgent, which you can simply uninstall from the home screen. This usually solves problems caused by changing the used Mac or the Xcode version.

*For Android devices, it is the UIAutomator2; here, a problem occurs sporadically on some devices, the cause is currently unknown to us. To uninstall, on the device, navigate to "''Settings''" > "''Applications''"* and search the list for the following entries:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Click on the respective application and then on "''Uninstall''".
*''The corresponding entry may have a slightly different name on some devices.''

If this doesn't help, check the output of the Appium server. For a server started by expecco, you can find the log in the list of [[#Running_Appium_Servers|Running Appium Servers]].

==I do not have a Mac==
Maybe this site will help you: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin

2023-12-22T09:37:37Z

Matilk: /* Windows */ new supplement version

'''Deutsche Version''' | [[Mobile_Testing_Plugin/en|English Version]]

= Einleitung =
Mit dem ''Mobile Testing Plugin'' können Anwendungen auf Android- und iOS-Geräten getestet werden. Dabei ist es egal, ob reale mobile Endgeräte oder emulierte Geräte verwendet werden. Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests unterstützt. Zudem ist damit das Aufzeichnen von Testabläufen möglich.

Zur Verbindung mit den Geräten wird [http://appium.io/ Appium] verwendet. Appium ist ein freies Open-Source-Framework zum Testen und Automatisieren von mobilen Anwendungen.

Zur Einarbeitung in das Mobile Plugin empfehlen wir das [[Mobile_Testing_Tutorial|Tutorial]] zu bearbeiten. Dieses führt anhand eines Beispiels Schritt für Schritt durch die Erstellung eines Testfalls und erklärt die nötigen Grundlagen.

= Installation und Aufbau =
Zur Verwendung des Mobile Testing Plugins müssen Sie expecco inkl. des Plugins Mobile Testing installiert haben und Sie benötigen die entsprechenden Lizenzen. expecco kommuniziert mit den Mobilgeräten über einen Appium-Server, der entweder auf demselben Rechner wie expecco läuft, oder auf einem zweiten Rechner. Dieser muss für expecco erreichbar sein.

==Installationsübersicht==

'''Rechner, auf dem expecco läuft:'''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem Android-Geräte angeschlossen sind:'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Android SDK'', dieses erhalten Sie ebenfalls mit dem Mobile Testing Supplement''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem iOS-Geräte angeschlossen sind2):'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement für Mac OS installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Xcode ''in einer Version, die die verwendete iOS-Version unterstützt, erhältlich über den Apple App Store''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
* Apple-Entwickler-Zertifikat mit zugehörigem privaten Schlüssel ''(zum Signieren des WebDriverAgents)''
* Provisioning Profile mit den verwendeten Mobilgeräten

Je nach Aufbau können die oben genannten Rechner auch das selbe Gerät sein. expecco kann sich sowohl über das Netzwerk mit einem entfernten Appium-Server und dort angeschlossenen Mobilgeräten verbinden, als auch lokal selbst einen Appium-Server starten und diesen mit lokalen Mobilgeräten verwenden. Einige Funktionen von expecco, die die Erstellung von Testfällen erleichtern, sind jedoch nur verfügbar, wenn die Mobilgeräte am selben Rechner angeschlossen sind, auf dem auch expecco läuft. Ein möglicher Aufbau kann daher wie in folgender Abbildung aussehen:

[[Datei:MobileTestingAufbau.png | 400px]]

Im Folgenden wird die Installation von Appium und anderer nötiger Programme für Windows und Mac OS erklärt.

1): Zum Zeitpunkt der Erstellung dieses Dokuments wurden Versionen bis 11 auf Funktion verifiziert. Neuere Versionen sollten - sofern nicht grundlegende Änderungen von Oracle vorgenommen wurden, ebenfalls funktionieren.

2): Beachten Sie, dass aufgrund der Voraussetzungen (keine Anbindung an nicht-Apple Geräte verfügbar) iOS-Geräte nur von einem Mac aus angesteuert werden können. Sie benötigen also einen Mac als "Vermittler" (siehe auch unten: [[#Ich habe keinen Mac | "Ich habe keinen Mac"]])

== Windows ==
Am einfachsten installieren Sie alles mit unserem Mobile Testing Supplement1. In neueren Versionen ist allerdings aufgrund geänderter Lizenzbedingungen seitens Oracle kein JDK mehr enthalten, sodass sie dieses zusätzlich installieren müssen. Sie können natürlich Appium auch direkt installieren, um die Version zu verwenden, die Sie möchten. Um dann einen Appium-Server mit expecco starten zu können, muss allerdings eine entsprechende Batchdatei vorhanden sein und in den [[Mobile_Testing_Plugin#Konfiguration_des_Plugins|Einstellungen]] angegeben werden. Verbindungen können aber auch zu anderen laufenden Appium-Servern aufgebaut werden.
*'''expecco 23.2''': [https://download.exept.de/transfer/h-expecco-23.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.2]
:Im Vergleich zum Vorgänger aktualisierte Chromedriver Versionen.
*expecco 23.1: [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Gleiche Versionen wie der Vorgänger, aber der Installer erlaubt nun, Appium zum Autostart hinzuzufügen.
*expecco 22.2 und 22.1: [https://download.exept.de/transfer/h-expecco-22.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 aus platform-tools 33.0.2
:''* Wir haben Appium um die Capability'' startChromedriverTimeout ''erweitert, um schneller einen Timeout zu bekommen, wenn der Chromedriver nicht gestartet werden kann. (siehe [[#startChromedriverTimeout|Probleme und Lösungen]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Enthält die Appium-Version 1.22.0, Node ist weiterhin in der Version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Nur kleine Änderungen im Vergleich zur vorigen Version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und node 12 verwendet.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:Dieses installiert Appium in der Version 1.12.0 und enthält nun zusätzlich build-tools der Version 28.0.3 im android-sdk. Ansonsten ist es gleich wie die vorige Version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:Dieses installiert Appium in der Version 1.8.1. Außerdem bietet das Supplement auch an, ''Android Debug Bridge'' und ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) zu installieren. Damit sind Treiber für ein breites Spektrum an Android-Geräten abgedeckt, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen. Ein '''JDK ist (aufgrund geänderter Lizenzbedingungen seitens Oracle) nicht mehr enthalten''', dieses müssen Sie selbst herunterladen, z.B. von [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: wie expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.6.4. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.4.16. Während der Installation wird die grafische Oberfläche von Appium gestartet, dieses Fenster können Sie sofort wieder schließen. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.

Wenn expecco Mobilgeräte verwenden soll, die an einem anderen Rechner angeschlossen sind, müssen Sie dort einen Appium-Server starten. Dies können Sie mit der Datei <code>appium_standalone.cmd</code> tun. Der Server wird dann mit dem Standard-Port 4723 gestartet. Falls Sie eine andere Portnummer verwenden wollen, starten Sie den Server mit

appium_standalone.cmd -p <portnummer>

Der Server ist bereit, sobald die Zeile
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
angezeigt wird, wobei Sie am Ende die verwendete Portnummer ablesen können.

Beim ersten Starten von Appium – sowohl im Standalone als auch gestartet von expecco – kann es vorkommen, dass die Windows-Firewall den Node-Server blockiert. Lassen Sie den Zugriff zu, sonst kann Appium nicht gestartet werden.

1) Sie können natürlich auch die Command Line Tools (adb, sdkmanager, avdmanager etc.) einer vorhandenen Android Studio Version verwenden, sowie Appium separat installieren.
Da sich diese Tools regelmäßig ändern, und es in der Vergangenheit zu Inkompatibilitäten und Fehlern nach Releasewechseln kam, empfehlen wir zu Beginn, das mitgelieferte Paket zu verwenden. Dies ist möglicherweise nicht das aktuellste, wurde aber auf Lauffähigkeit getestet.

Falls das Android Mobilgerät an einem entfernen Rechner angeschlossen ist,
können Sie den aktuellen Bildschirminhalt z.B. mit dem [https://github.com/Genymobile/scrcpy scrcpy] tool live mitverfolgen.

== Mac OS (nicht erforderlich für Android-Tests)==
Hinweis: Wenn Sie nicht vorhaben, iOS-Geräte (iPhone, iPad, etc.) zu testen, können Sie das Folgende ignorieren. '''Der Apple-Rechner sowie das Mac-Setup werden für Android-Geräte nicht benötigt'''.

=== Xcode ===
Zur Automatisierung mit iOS-Geräten wird [https://developer.apple.com/xcode/ Xcode] benötigt. Sie erhalten dieses über den App Store. Dabei ist darauf zu achten, dass die Version zu den getesteten iOS-Versionen passt.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
Diese Tabelle gibt nur eine vereinfachte Übersicht, lesen Sie besser unter [https://xcodereleases.com/ Xcode Releases] oder [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode-Versionen] welche Version Sie brauchen. Für neue iOS Minor-Versionen gibt es in der Regel auch ein Update für Xcode, z.B. brauchen Sie für iOS 10.2 mindestens Xcode 8.2, für iOS 10.3 mindestens Xcode 8.3 usw.
Wenn Sie also auf eine neuere iOS-Version wechseln, benötigen Sie in der Regel auch eine neuere Xcode-Version. Neuere Versionen von Xcode laufen möglicherweise nicht auf älteren Betriebssystemen, was wiederum eine Aktualisierung des Betriebssystems erforderlich machen kann. Falls Sie auch ältere iOS-Versionen testen wollen kann es sinnvoll sein, die entsprechenden Xcode-Versionen parallel zu installieren.

=== Appium ===
Der Appium-Server kann entweder als Kommandozeilen-Anwendung installiert werden oder über [https://github.com/appium/appium-desktop Appium Desktop] verwendet werden, welcher den Server über ein GUI zur Verfügung stellt. Mittlerweile gibt es auch Appium 2.0, was wir aber bisher noch nicht mit expecco getestet haben und daher nicht empfehlen.

==== Appium Desktop ====
Laden Sie die neueste Version von [https://github.com/appium/appium-desktop/releases/ Appium Desktop] herunter. Für den Mac nehmen Sie am besten die dmg-Datei und installieren sie in den Anwendungen. Beim Starten der Anwendung ''Appium Server GUI'' erhalten Sie wahrscheinlich eine Fehlermeldung, dass es aus Sicherheitsgründen nicht möglich ist. Öffnen Sie dann das Kontextmenü auf der Anwendungsdatei (Rechtsklick bzw. Strg + Klick) und wählen Sie dort ''Öffnen'' aus. Bestätigen Sie dann, dass Sie die Anwendung wirklich öffnen wollen. Fortan können Sie die Anwendung normal öffnen.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Ab Xcode 14 gibt es Probleme beim Signieren des WebDriverAgents, den Appium zur Automatisierung auf das Gerät spielt. Dadurch ist mit der Version 1.22.3-4 von Appium Desktop kein Verbindungsaufbau möglich. Das Problem ist in neueren Versionen des WebDriverAgents behoben, es gibt aber aktuell noch keine Version von Appium Desktop, die eine solche Version enthält (Stand November 2022). Sie können aber manuell eine neue Version herunterladen (z.B. 4.10.2) und die Dateien in Appium ersetzen. Laden Sie dazu von der [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent Download-Seite] eine der beiden Archivdateien (zip oder tar.gz) mit dem Source Code herunter. Öffnen und entpacken Sie dann diese Datei. Den Inhalt des Ordners WebDriverAgent-4.10.2 müssen Sie nun nach

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

kopieren. Wenn Sie über den Finder dorthin navigieren, machen Sie auf die Anwendung ''Appium Server GUI'' einen Kontextklick (Rechtsklick bzw. Strg + Klick) und wählen Sie im Menü ''Paketinhalt anzeigen''. Ersetzen Sie alle Dateien, die bereits mit gleichem Namen enthalten sind.

==== Appium über npm installieren ====
Sie können Appium auch über npm (Node Package Manager) installieren. Dazu müsen Sie erst node/npm installieren. Das geht mit [https://github.com/nvm-sh/nvm nvm] (Node Version Manager) was Sie von Github bekommen. Falls die folgende Installationsanleitung bei Ihnen nicht funktionieren sollte, finden Sie dort ausführlichere Informationen im [https://github.com/nvm-sh/nvm#readme Readme].

Öffnen Sie ein Terminal-Fenster. Klonen Sie dann das Github-Repository von nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
und laden Sie es
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Führen Sie danach
command -v nvm
aus, um zu testen, ob es funktioniert hat. Es sollte ''nvm'' ausgegeben werden. Kommt keine Antwort, führen Sie
touch ~/.zshrc
aus, und versuchen Sie es erneut.

Nun können Sie node mit dem folgenden Befehl installieren.
nvm install 16.15.1
Da es mit der aktuellen Version von node Probleme beim Installieren von Appium gibt, empfehlen wir diese Version.

Nachdem node installiert ist, können Sie Appium darüber installieren:
npm install -g appium

Den Appium-Server können Sie nun einfach über den Befehl
appium
starten. Die Ausgabe erfolgt dann direkt im Terminal.

Auch bei dieser Version gibt es das Problem bei der Signierung des WebDriverAgents, wie bei [[#Appium_Desktop | Appium Desktop]] beschrieben. Laden Sie also auch in diesem Fall eine neuere Version des WebDriverAgents herunter und ersetzen Sie die alten Dateien. Diese finden Sie unter
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
Ältere Appium-Versionen stellen wir Ihnen über das Mobile Testing Supplement für Mac OS zur Verfügung, mit dem Sie es einfach installieren können:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.2)]
:Enthält Appium Version 1.18.3 und verwendet node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.0)]
:Nur wenige Änderungen im Vergleich zur vorigen Version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.98)]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und es wird node 12 verwendet.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.96)]
:Diese Version enthält Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.94)]
:Diese Version enthält Appium 1.8.0.

* expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.0.94)]
:Diese Version enthält Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement für Mac OS]
:Diese Version entält Appium 1.4.16.

Nachdem Herunterladen des Supplements, können Sie es in ein Verzeichnis Ihrer Wahl (z. B. Ihr Home-Verzeichnis) verschieben und dort entpacken. Ein geeigneter Befehl in einer Shell könnte wie folgt aussehen, passen Sie dabei die Versionsnummer entsprechend an:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

Wenn Sie Ihre Standard-Xcode-Installation verwenden wollen, können Sie Appium direkt über die Datei im ''bin''-Verzeichnis mit der entsprechenden Versionsnummer starten:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Falls Sie ein anderes Xcode als das als Standard konfigurierte verwenden wollen, müssen Sie Appium den entsprechenden Pfad über die Umgebungsvariable ''DEVELOPER_DIR'' angeben.
Wenn Sie Xcode z. B. in ''/Applications/Xcode-11.3.app'' installiert haben, müssten Sie Appium so starten:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Was als Standard-Xcode-Installation gesetzt ist, zeigt der Befehl:

xcode-select -p

Wenn Appium Ihre Xcode-Installation nicht findet, erscheint beim Verbinden eine Fehlermeldung in der Art:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
Starten Sie in diesem Fall Appium erneut, unter Angabe eines gültigen ''DEVELOPER_DIR''.

==== WebDriverAgent-Signierung ====
Zur Automatisierung lädt Appium eine App namens WebDriverAgent auf das Gerät und muss sie dafür signieren können. Dazu brauchen Sie einen Apple-Account und ein entsprechendes Zertifikat. Zur Evaluierung können Sie einen kostenlosen Account verwenden. Dieser hat den Nachteil, dass erstellte Profile nur eine Woche gültig sind und danach neu erstellt werden müssen. Seien Sie auch vorsichtig, wenn Sie sich den Account teilen, da es vorkommen kann, dass Zertifikate widerrufen werden oder durch automatische Generierung ungültig werden. Als Folge können bereits signierte Apps nicht mehr verwendet werden.

Wenn Sie bereits ein entsprechendes Zertifikat mit dem zugehörigen privaten Schlüssel in Ihrer [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac haben, können Sie den WebDriverAgent automatisch signieren lassen. Ansonsten empfiehlt es sich, die Signierung über Xcode einzustellen und zu verwalten.

Schließen Sie zuerst das Gerät, das Sie verwenden möchten, über USB an den Mac an. Stellen Sie sicher, dass sich der Mac und das Gerät im selben Netzwerk befinden, ansonsten kann es beim Verbindungsaufbau mit Appium zu Problemen kommen. Starten Sie Xcode und öffnen Sie ''Preferences''. Wechseln Sie zur Seite der Accounts und legen Sie einen Eintrag mit Ihrem Account an. Anschließend können Sie auf ''Manage Certificates...'' klicken, um die Zertifikate zu sehen, die zu diesem Account gehören. Zum Ausführen von Tests benötigen Sie ein iOS-Development-Zertifikat und den dazugehörigen privaten Schlüssel. Wenn Sie noch keines besitzen, erstellen Sie eines. Wenn Sie bereits eines haben, aber es nicht in Ihrem Schlüsselbund vorhanden ist (erkennbar an dem Hinweis "Not in Keychain"), können Sie es importieren. Das können Sie über die [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac machen, wenn Sie es zuvor aus dem Schlüsselbund exportiert haben, in dem es sich befindet. Das Zertifikat mit dem zugehörigen Schlüssel sollte sich im Schlüsselbund ''Anmeldung'' befinden. Dort kann es als PKCS#12-Datei (Endung typischerweise .p12) exportiert werden. Um ein Zertifikat in Ihren Schlüsselbund zu importieren, wählen Sie im Menü ''Ablage'' die Option ''Objekte importieren''. Falls Sie nicht wissen, wo das Zertifikat gespeichert ist, können Sie es in Xcode auch widerrufen und in Ihrem Schlüsselbund neu anlegen. Machen Sie das jedoch nur, wenn Sie wissen, dass das alte Zertifikat nicht mehr in Verwendung ist, da es danach nicht mehr benutzt werden kann. Nun sollte Ihr Schlüsselbund ein iOS-Development-Zertifikat enthalten.


Öffnen Sie nun das WebDriverAgent-Projekt in Xcode. Wenn Sie das Mobile Testing Supplement installiert haben, finden Sie es in dessen Verzeichnis unter
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
Wenn Sie Appium Desktop installier haben, finden Sie es unter
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''
Sie können einfach im Finder zu der Xcode-Project-Datei navigieren und Sie über einen Doppelklick öffnen. Beachten Sie dabei, dass Sie dabei auf die Anwendung Appium Server GUI einen Kontextklick (Rechtsklick bzw. Strg + Klick) machen und im Menü ''Paketinhalt anzeigen'' auswählen müssen, um in deren Unterverzeichnis zu gelangen.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Wählen Sie ''WebDriverAgentLib'' und die Seite ''Signing & Capabilities'' aus. Setzen Sie dort im Abschnitt ''Signing'' die Option ''Automatically manage signing'' und wählen Sie dann ein Team aus. Wechseln Sie nun zu ''WebDriverAgentRunner'' und tun Sie dort dasselbe.

Durch das Setzen des Teams sollten die Fehler für den WebDriverAgentRunner verschwinden. Sollte Xcode kein passendes Provisioning Profile für die Bundle ID ''com.facebook.WebDriverAgentRunner'' erstellen können, können Sie diese anpassen, dass sie zu Ihrem Zertifikat passt. Danach können Sie Xcode beenden oder auch, wie weiter unten beschrieben, direkt den Build über Xcode starten, damit das Projekt bereits gebaut ist, wenn Appium es verwenden möchte.

Wenn Sie sich nun von expecco eine Verbindung zu Ihrem Gerät aufbauen, wird der WebDriverAgent darauf installiert und gestartet, um anschließend zur zu testenden App zu wechseln. Eventuell muss auf dem Gerät muss der Ausführung des WebDriverAgents vertraut noch werden. Ein Anzeichnen dafür kann sein, dass die App WebDriverAgent zwar auf dem Gerät erscheint und zu starten versucht, danach aber wieder deinstalliert wird. Öffnen Sie dazu während des Verbindungsaufbaus auf dem Gerät in die Einstellungen und dort unter ''Allgemein'' den Eintrag ''Geräteverwaltung''. Dieser Eintrag ist nur sichtbar, wenn eine Entwickler-App auf dem Gerät installiert ist. Sie müssen daher möglicherweise warten, bis der WebDriverAgent installiert ist, bevor der Eintrag erscheint. Wählen Sie dort den Eintrag Ihres Apple-Accounts und vertrauen Sie ihm. Da der WebDriverAgent wieder deinstalliert wird, wenn der Start nicht funktioniert hat, müssen Sie dies während des Verbindungsaufbaus tun. Falls Ihnen das zu hektisch ist, können Sie auch folgenden Code ausführen:

<nowiki>xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test</nowiki>
bzw.
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

Damit wird der WebDriverAgent auf dem Gerät installiert ohne dass er wieder gelöscht wird.

Wenn es Probleme beim Installieren des WebDriverAgents gibt, können Sie auch versuchen, den Build über Xcode zu starten. Stellen Sie sicher, dass das richtige Target ''WebDriverAgent'' ausgewählt ist. Fehlermeldungen in Xcode zeigen vielleicht einfacher, wo das Problem liegt. Manchmal hilft es auch, es ein zweites Mal zu versuchen, weil es möglicherweise beim ersten Mal zu lange gedauert hat und abgebrochen wurde. Es kann sein, dass Sie während des Builds mehrmals aufgefordert werden, das Passwort für Ihren Schlüsselbund anzugeben.

[[Datei:WebDriverAgentCodesign.png]]

Lesen Sie auch die Dokumentation von Appium zum [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Aufsetzen von Tests mit iOS-Geräten]. In der [https://support.apple.com/en-us/HT204460 Dokumentation von Apple] finden Sie nähere Informationen zum Installieren und Vertrauen von Apps.

Ist der WebDriverAgent einmal auf dem Gerät installiert, wird er für spätere Verbindungen wieder verwendet und der Verbindungsaufbau sollte schneller funktionieren. Ebenso liegt dann die signierte Version bereits auf Ihrem Mac und muss nicht erneut gebaut werden, was die Verbindung zu weiteren Geräten ebenfalls beschleunigt. Wenn Sie wissen, dass bei Ihrem Verbindungsaufbau der WebDriverAgent erst noch signiert und gebaut werden muss, ist es ratsam, die Capability ''wdaLaunchTimeout'' zu setzen. Dieser Timeout, wie lange auf den Start der WebDriverAgents auf dem Gerät gewartet werden soll, liegt standardmäßig bei 60000$nbsp;ms. Der Build dauert aber häufig über eine Minute, sodass der Versuch zum Verbindungsaufbau dann abgebrochen wird. Ein Wert von 120000 hat sich hier als besser erwiesen.

== Konfiguration des Plugins ==
Bevor Sie loslegen, sollten Sie die Einstellungen des Mobile Testing Plugins überprüfen und ggf. anpassen.

Öffnen Sie im Menü den Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" den Eintrag "''Mobile Testing''" (s. Abb.). Standardmäßig werden diese Pfade automatisch gefunden (1). Um einen Pfad manuell anzupassen, deaktivieren Sie den entsprechenden Haken rechts davon. Sie erhalten in einer Drop-down-Liste einige Pfade zur Auswahl. Ist ein eingetragener Pfad falsch oder kann er nicht gefunden werden, wird das Feld rot markiert und es erscheint ein diesbezüglicher Hinweis. Stellen Sie sicher, dass alle Pfade richtig angegeben sind.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Konfiguration des Plugins]]

*'''appium''': Geben Sie hier den Pfad zur ausführbaren Datei an mit der Appium in der Kommandozeile gestartet werden kann. Unter Windows wird diese Datei in der Regel "<code>appium.cmd</code>" heißen. Dieser Pfad wird benutzt, wenn expecco einen Appium-Server startet.
*'''node''': Geben Sie hier den Pfad zur ausführbaren Datei an, die Node (auch "Node.js") startet. Dieser Pfad wird beim Starten eines Servers an Appium weitergegeben, damit Appium ihn unabhängig von der PATH-Variablen findet. Unter Windows heißt diese Datei in der Regel "<code>node.exe</code>".
*'''JAVA_HOME''': Geben Sie hier den Pfad zu einem JDK an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden. Um einzustellen, welches Java von expecco verwendet werden soll, setzen Sie diesen Pfad in den Einstellungen für die Java Bridge.
*'''ANDROID_HOME''': Geben Sie hier den Pfad zu einem SDK von Android an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden.
*'''adb''': Hier steht der Pfad zum adb-Befehl. Unter Windows heißt die Datei adb.exe. Diese wird von expecco beispielsweise verwendet, um die Liste der angeschlossenen Geräte zu erhalten. Diesen Pfad sollten Sie automatisch wählen lassen, da dann der Befehl im ANDROID_HOME-Verzeichnis verwendet wird. Dieser wird auch von Appium verwendet. Falls expecco und Appium jedoch verschiedene Versionen von adb verwenden kann es zu Konflikten kommen.
*'''android.bat''': Diese Datei wird nur benötigt, um damit den AVD und den SDK Manager zu starten. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.
*'''aapt''': Geben Sie hier den Pfad zum aapt-Befehl an. Unter Windows heißt diese Datei ''aapt.exe''. expecco verwendet aapt nur im Verbindungseditor, um das Paket und die Activities einer apk-Datei zu lesen. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | Konfiguration des JDKs]]

Ab expecco 2.11 gibt es das Feld ''Team-ID''. Wenn Sie iOS-Tests ausführen, tragen Sie hier die Team-ID Ihres Zertifikats ein. Diese wird für jede iOS-Verbindung verwendet, außer Sie setzen den Wert im Einzelfall in den Verbindungseinstellungen um. Wie Sie die Team-ID erhalten, lesen Sie im Abschnitt zur [[#Signierung|Signierung]] ber der Installation auf Mac OS. Mit expecco 2.10 können Sie die Team-ID nur für jede Verbindungseinstellung extra als Capability eintragen. Dazu müssen Sie jedoch die [[#Erweiterte_Ansicht|erweiterte Ansicht]] verwenden. Geben Sie hier die Capability ''xcodeOrgId'' an und setzen Sie als Wert die Team-ID des Zertifikats.

Die Einstellung zur Serveradresse unten auf der Seite bezieht sich auf das Verhalten des Verbindungseditors. Dieser prüft am Ende, ob die Serveradresse auf ''/wd/hub'' endet, da dies die übliche Form ist. Falls nicht, wird in einem Dialog gefragt, wie darauf reagiert werden soll. Das festgelegte Verhalten kann hier eingesehen und verändert werden.

Wechseln Sie ebenfalls zum Eintrag ''Java Bridge'' (s. Abb.). Hier muss der Pfad zu Ihrer Java-Installation angegeben werden, die von expecco benutzt wird. Tragen Sie hier ein JDK ein. Falls Sie unter Windows das aus dem Mobile Testing Supplement verwenden möchten, lautet der Pfad
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
Sie können auch die Systemeinstellungen verwenden.

== Android-Gerät vorbereiten ==
Wenn Sie ein Android-Gerät unter Windows anschließen benötigen Sie möglicherweise noch einen adb-Treiber für das Gerät. Einen passenden Treiber finden Sie üblicherweise auf der jeweiligen Webseite des Herstellers. Haben Sie den Universal-Treiber aus dem Mobile Testing Supplement installiert, sollte für die meisten Geräte bereits alles funktionieren. In einigen Fällen versucht auch Windows automatisch einen Treiber zu installieren, wenn Sie das Gerät zum ersten mal anschließen.
 
===USB-Debugging Einschalten===
'''Achtung:'''
Bevor Sie ein Mobilgerät mit dem Appium-Plugin ansteuern können, müssen Sie für dieses Debugging erlauben!

Für Android-Geräte finden Sie diese Option in den Einstellungen unter ''[https://www.droidwiki.org/wiki/Entwickleroptionen Entwickleroptionen]'' mit dem Namen ''[https://www.droidwiki.org/USB-Debugging USB-Debugging]''. Falls die Entwickleroptionen nicht angezeigt werden, können Sie diese freischalten, indem Sie unter "''Über das Telefon''" siebenmal auf "''Build-Nummer''" tippen.

===Wach bleiben Aktivieren===
Aktivieren Sie auch die Funktion ''Wach bleiben'', damit das Gerät nicht während der Testerstellung oder -ausführung den Bildschirm abschaltet.

Aus Sicherheitsgründen muss USB-Debugging für jeden Computer einzeln zugelassen werden. Beim Verbinden des Geräts mit dem PC über USB müssen Sie dabei am Gerät der Verbindung zustimmen. Falls Sie dies für Ihren Computer noch nicht getan haben, aber auf dem Gerät kein entsprechender Dialog erscheint, kann es helfen, das Gerät aus- und wieder einzustecken. Das kann insbesondere dann passieren, wenn Sie den ADB-Treiber installiert haben während das Gerät bereits über USB angeschlossen war. Falls auch das nicht hilft, öffnen Sie die Benachrichtigungen, indem Sie sie vom oberen Bildschirmrand herunter ziehen. Dort finden Sie die USB-Verbindung und Sie können die Optionen dazu öffnen. Wählen Sie einen anderen Verbindungstypen aus; in der Regel sollten MTP oder PTP funktionieren.

Sie können auch auf einem Emulator testen. Dieser muss nicht gesondert vorbereitet werden, da er bereits für USB-Debugging ausgelegt ist. Es ist sogar möglich, einen Emulator bei Testbeginn zu starten.

Um zu überprüfen, ob ein Gerät, das Sie an Ihren Rechner angeschlossen haben, verwendet werden kann, öffnen Sie den [[#Verbindungseditor|Verbindungseditor]]. Das Gerät sollte dort angezeigt werden.

=== Verbindung über WLAN ===
Es ist auch möglich, Android-Geräte über WLAN zu verbinden. Für Geräte mit Android 11 oder neuer ist dies direkt über WLAN möglich, im anderen Fall müssen Sie das Gerät zuerst über USB verbinden. Ab expecco 22.1 können Sie eine WLAN-Verbindung über den [[Mobile Testing Plugin#Verbindungseditor|Verbindungseditor]] aufbauen. Ansonsten ist es auch über die Eingabeaufforderung möglich.
==== Drahtlos verbinden über die Eingabeaufforderung mit expecco Versionen vor 22.1 (ab Android 11) ====
Mit expecco ab Version 22.1 funktioniert das einfacher über den Verbindungseditor.

Erlauben Sie in den Entwickleroptionen des Geräts Debugging über WLAN und öffnen Sie dessen Optionen. Sie müssen zuerst das Gerät mit dem Rechner koppeln. Wählen Sie dazu "''Gerät mit einem Kopplungscode koppeln''", um einen Kopplungscode und eine IP-Adresse mit Port zu erhalten. Öffnen Sie dann auf dem Rechner die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb pair <IP-Adresse des Geräts>:<Kopplungsport></nowiki>
wobei Sie <tt><IP-Adresse des Geräts>:<Kopplungsport></tt> durch die auf dem Gerät angezeigte IP-Adresse & Port ersetzen. Danach werden Sie aufgefordert, den Kopplungscode einzugeben. Wenn alles geklappt hat, sollte sich das Popup auf dem Gerät schließen und der Rechner als gekoppeltes Gerät angezeigt werden. Geben Sie dann in der Eingabeaufforderung ein:
<nowiki>adb connect <IP-Adresse des Geräts>:<Debug-Port></nowiki>
Die IP-Adresse ist hier noch die gleiche wie beim Koppeln, aber der Port ist ein anderer. Beides wird als IP-Adresse & Port auf dem Gerät angezeigt. Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie entweder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden. Häufig wird beim Neustart des Geräts auch die Erlaubnis für das Debugging über WLAN wieder zurückgesetzt und der verwendete Port ändert sich. Die Kopplung bleibt aber bestehen und muss beim nächsten Verbinden nicht noch einmal durchgeführt werden.

==== WLAN Verbindung über USB starten (Android 10 und früher) ====
Verbinden Sie zunächst das Gerät über USB mit dem Rechner. Öffnen Sie dann die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb tcpip 5555</nowiki>
Damit lauscht das Gerät auf eine TCP/IP-Verbindung an Port 5555. Sollten Sie mehrere Geräte angeschlossen oder Emulatoren laufen haben, müssen Sie genauer angeben, welches Gerät Sie meinen. Geben Sie in diesem Fall ein:
<nowiki>adb devices -l</nowiki>
Sie erhalten eine Liste aller Geräte, wobei die erste Spalte deren Kennung ist. Schreiben Sie dann stattdessen
<nowiki>adb -s <Gerätekennung> tcpip 5555</nowiki>
mit der Gerätekennung des gewünschten Geräts. Sie können die USB-Verbindung nun trennen. Jetzt müssen Sie die IP-Adresse Ihres Gerätes in Erfahrung bringen. Sie finden diese üblicherweise irgendwo in den Einstellungen des Geräts, beispielsweise beim Status oder in den WLAN-Einstellungen. Geben Sie dann ein:
<nowiki>adb connect <IP-Adresse des Geräts></nowiki>
Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie wieder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden.

=== Verbindung zu einem Emulator ===
Sie benötigen dazu den Emulator selbst, sowie mindestens ein AVD (Android Virtual Device). Hinweise zu Installation finden Sie in der [https://developer.android.com/studio/run/emulator Android Studio Dokumentation].

Wenn Sie Android Studio bereits mit den Defaulteinstellungen installiert haben 1), sollte der Emulator bereits mitinstalliert sein. Falls nicht, wählen Sie in Android Studio "''Configure''" - "''SDK Manager''" - "''Android SDK''" - "''SDK Tools''" - ''Android Emulator''", sowie dort die "''Platform Tools''".
Alternativ geht das auch über die Kommandzeile mit dem "sdkmanager" Kommando.

Als nächstes benötigen Sie mindestens ein AVD; auch dies geht am einfachsten über den Dialog in Android Studio:
wählen sie "''Configure''" - "''AVD Manager''" und folgen den Anweisungen (Deviceauswahl, Platform und Android Version).

Auch wenn Sie den Emulator automatisieren benötigen sie Appium; installieren Sie dieses entweder mit dem Mobile Testing Supplement, oder direkt von der Appium homepage (https://github.com/appium/appium-desktop/releases).

1)Android Studio selbst wird nicht von expecco benötigt; es bietet aber kompfortable Dialoge zum Installieren von Paketen und AVDs.

== iOS-Gerät und App vorbereiten ==
Das Ansteuern von iOS-Geräten ist nur über einen Mac möglich. Lesen Sie daher auch den Abschnitt zur [[#Mac_OS|Installation unter Mac OS]].

Bevor Sie ein Mobilgerät mit dem Mobile Testing Plugin ansteuern können, müssen Sie für iOS-Geräte ab iOS 8 Debugging erlauben. Aktivieren Sie dazu die Option ''Enable UI Automation'' unter dem Menüpunkt ''Entwickler'' in den Einstellungen des Geräts. Falls Sie den Eintrag ''Entwickler'' in den Einstellungen nicht finden, gehen Sie wie folgt vor: Schließen Sie das Gerät über USB an den Mac an. Dabei müssen Sie ggf. am Gerät noch der Verbindung zustimmen. Starten Sie Xcode und wählen Sie dann in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie dort Ihr Gerät aus. Danach sollte der Eintrag ''Entwickler'' in den Einstellungen auf dem Gerät auftauchen. Dazu müssen Sie möglicherweise die Einstellungen beenden und neu starten.

[[Datei:Alert.png | thumb | 270px | Beispiel für einen Alert unter iOS]]
Ein Verbindungsaufbau zu dem Gerät ist nicht möglich solange es bestimmte Alerts zeigt. Ein solcher Alert kann z. B. erscheinen wenn FaceTime aktiviert ist, indem ein Hinweis auf anfallende SMS-Gebühren angezeigt wird (siehe Screenshot). Achten Sie darauf, das Gerät so zu konfigurieren, dass es im Leerlauf keine solchen Alerts zeigt.

=== expecco 2.11 und später ===
Sie können beliebige Apps testen, die auf dem verwendeten Gerät lauffähig oder bereits installiert sind. Wenn die App als Development-Build vorliegt, muss die UDID des Geräts in der App hinterlegt sein. In jedem Fall muss der WebDriverAgent für das Gerät signiert werden. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]] unter Mac OS.

Falls Sie in einem Test den Home-Button verwenden wollen, müssen Sie auf dem Gerät AssistiveTouch aktivieren. Sie finden diese Option in den Einstellungen unter ''Allgemein'' > ''Bedienungshilfen'' > ''AssistiveTouch''. Platzieren Sie dann das Menü in der Mitte des oberen Bildschirmrands. Sie können das Drücken des Home-Buttons dann mit dem entsprechenden Menüeintrag im Recorder aufzeichnen oder direkt den Baustein ''Press Home Button'' benutzen.

=== expecco 2.10 ===
Die App, die Sie verwenden wollen, muss als Development-Build vorliegen. Außerdem muss die UDID des Geräts in der App hinterlegt sein.

=== Development-Build signieren ===
Ein Development-Build einer App ist nur für eine begrenzte Zahl von Geräten zugelassen und kann auf anderen Geräten nicht gestartet werden. Es ist aber möglich, das Zertifikat und die verwendbaren Geräte in einem Development-Build auszutauschen.

* Evaluierung mit Demo-App von eXept:
:Gerne stellen wir Ihnen eine Demo-App zur Verfügung, die als Development-Build vorliegt und die wir für Ihr Gerät signieren können. Senden Sie dazu bitte Ihrem eXept-Ansprechpartner die UDID Ihres Gerätes zu. Wie Sie die UDID Ihres Gerätes ermitteln können, ist im folgenden Abschnitt beschrieben.

* Eigene App für Ihr Testgerät verwenden:
:Wenn Sie von den App-Entwicklern einen Development-Build (IPA-Datei) erhalten, der für Ihr Testgerät zugelassen ist, können Sie diesen direkt verwenden. Dazu müssen Sie den Entwicklern die UDID Ihres Geräts mitteilen, damit sie diese eintragen können. '''Sie können die UDID eines Gerätes mithilfe von Xcode auslesen'''. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie Ihr Gerät aus und suchen Sie in Eigenschaften den Eintrag ''Identifier''. Die UDID ist eine 40-stellige Hexadezimalzahl.

* Extern entwickelte App für Ihr Testgerät umsignieren:
:Es können auch Apps umsigniert werden, damit Sie auf anderen Geräten lauffähig sind. Dieser Vorgang ist jedoch kompliziert und setzt insbesondere einen Zugang zu einem Apple-Developer-Account voraus. Eine Dokumentation zur Vorgehensweise ist derzeit in Vorbereitung.

:Für die Evaluierung unterstützen wir Sie gerne beim Umsignieren Ihrer App.


Weitere Informationen zur Verwendung von iOS-Geräten finden Sie auch in der [http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Dokumentation von Appium].

=== Native iOS-Apps ===
Sie können auch Apps verwenden, die bereits nativ auf dem Gerät vorhanden sind. Dazu müssen Sie deren Bundle-ID kennen und diese dann in die Verbindungseinstellungen eintragen. Hier eine kleine Auswahl gängiger Apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

Weitere Bundle-IDs finden Sie [https://github.com/joeblau/apple-bundle-identifiers hier].

= Beispiele =
Bei den Demo-Testsuiten für expecco finden Sie auch Beispiele für Tests mit dem Mobile Testing Plugin. Wählen Sie dazu auf dem Startbildschirm die Option "''Beispiel aus Datei''" und öffnen Sie den Ordner "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
Die Testsuite enthält zwei einfache Testpläne: "''Simple CalculatorTest''" und "''Complex Calculator and Messaging Test''". Beide Tests verwenden einen Android-Emulator, den Sie vor Beginn starten müssen. Die Apps, die im Test verwendet werden, gehören zur Grundausstattung des Emulators und müssen daher nicht mehr installiert werden. Da sich die Apps unter jeder Android-Version unterscheiden können, ist es wichtig, dass Ihr Emulator unter Android 6.0 läuft. Außerdem muss die Sprache auf Englisch gestellt sein.

; Simple CalculatorTest
: Dieser Test verbindet sich mit dem Taschenrechner und gibt die Formel ''2+3'' ein. Das Ergebnis des Rechners wird mit dem erwarteten Wert ''5'' verglichen.

; Complex Calculator and Messaging Test
: Dieser Test verbindet sich mit dem Taschenrechner und öffnet anschließend den Nachrichtendienst. Dort wartet er auf eine einkommende Nachricht von der Nummer ''15555215556'', in der eine zu berechnende Formel gesendet wird. Die Nachricht wird zuvor über einen Socket beim Emulator erzeugt. Nach dem Eintreffen der Nachricht wird diese vom Test geöffnet und deren Inhalt gelesen. Danach wird wieder der Taschenrechner geöffnet, die erhaltene Formel eingegeben und das Ergebnis gelesen. Anschließend wechselt der Test wieder zum Nachrichtendienst und sendet das Ergebnis als Antwort.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
Diese sind Bestandteil des Tutorials zum Mobile Testing Plugin. Der jeweils enthaltene Testfall ist unvollständig und wird im Zuge des Tutorials ergänzt. Lesen Sie dazu den Abschnitt [[#Tutorial|Tutorial]].

= Tutorial =
Es gibt ein Tutorial, das das grundsätzliche Vorgehen zur Erstellung von Tests mit dem Mobile Testing Plugin beschreibt. Grundlage dafür ist ein mitgeliefertes Beispiel, bestehend aus einer einfachen App und einer expecco-Testsuite.

Sie finden es auf der Seite [[Mobile_Testing_Tutorial|Mobile Testing Tutorial]] in zwei Versionen für Android und für iOS.
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_Android|Erste Schritte mit Android]]
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_iOS|Erste Schritte mit iOS]]

= Dialoge des Mobile Testing Plugins =
== Verbindungseditor ==
Mithilfe des Verbindungseditors können Sie schnell Verbindungen definieren, ändern oder aufbauen. Je nach Aufgabe weist der Dialog kleine Unterschiede auf und wird unterschiedlich geöffnet:
*Um eine Verbindung aufzubauen, klicken Sie im GUI-Browser auf "''Verbinden'"' klicken und wählen dann "''Mobile Testing''".
*Um eine bestehende Verbindung im GUI-Browser zu ändern oder zu kopieren, wählen Sie diese aus, machen einen Rechtsklick und wählen im Kontextmenü "''Verbindung bearbeiten''" oder "''Verbindung kopieren''" aus.
*Wollen Sie Verbindungseinstellungen nicht für den GUI-Browser sondern zur Verwendung in einem Test erstellen, wählen Sie im Menü des Mobile Testing Plugins den Punkt "''Verbindungseinstellungen erstellen...''". Darüber können nur die Einstellungen für eine Verbindung erstellt werden, ohne dass eine Verbindung tatsächlich angelegt wird.

Einige der Schaltflächen sind nur beim Erstellen von Verbindungseinstellungen sichtbar:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#"''Einstellungen löschen''": Setzt alle Einträge zurück. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Einstellungen aus Datei laden''": Erlaubt das Öffnen einer gespeicherten Einstellungsdatei (*.csf). Deren Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen aus Anhang laden''": Erlaubt das Öffnen eines Anhangs mit Verbindungseinstellungen aus einem geöffneten Projekt. Diese Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen in Datei speichern''" sowie
#"''Einstellungen in Anhang speichern''": Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern oder als Anhang in einem geöffneten Projekt anlegen. Beide Optionen besitzen ein verzögertes Menü, in dem Sie auswählen können, nur einen bestimmten Teil der Einstellungen zu speichern. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Erweiterte Ansicht''": Damit können Sie in die erweiterte Ansicht wechseln, um zusätzliche Einstellungen vorzunehmen. Lesen Sie dazu mehr am Ende des Kapitels. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Hilfe''": An der rechten Seite wird ein Hilfetext zum jeweiligen Schritt ein- oder ausgeblendet.

Der Dialog ist in drei Schritte unterteilt. Im ersten Schritt wählen Sie das Gerät, das Sie verwenden möchten, im zweiten Schritt wählen Sie aus, welche App verwendet werden soll und im letzten Schritt erfolgen die Einstellungen zum Appium-Server.

===Schritt 1: Gerät auswählen===
Im oberen Teil erhalten Sie eine Liste aller angeschlossenen Appium-Geräte, die erkannt werden. Mit der Checkbox darunter können Sie die Geräte ausblenden, die zwar erkannt werden, aber nicht bereit sind. Falls Sie ein Gerät eintragen wollen, das nicht angeschlossen ist, können Sie dies mit dem entsprechenden Knopf "''Android-Gerät eingeben''" bzw. "''iOS-Gerät eingeben''" anlegen. Dazu müssen Sie jedoch die benötigten Eigenschaften Ihres Geräts kennen. Das Gerät wird dann in einer zweiten Geräteliste angelegt und kann dort ausgewählt werden. Wenn keine Liste mit angeschlossenen Elementen angezeigt werden kann, werden stattdessen verschiedene Meldungen angezeigt:
*Keine Geräte gefunden
*:expecco konnte kein Android-Geräte finden.
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*Keine verfügbaren Geräte gefunden
*:expecco konnte keine verfügbaren Android-Geräte finden. Es wurden aber nicht verfügbare gefunden, z.B. mit dem Status "unauthorized".
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*:Um nicht verfügbare Geräte anzuzeigen, aktivieren Sie unten diese Option.
*Verbindung verloren
*:expecco hat die Verbindung zum adb-Server verloren. Versuchen Sie die Verbindung wieder herzustellen, indem Sie auf den Button klicken.
*Verbindung fehlgeschlagen
*:expecco konnte sich nicht mit dem adb-Server verbinden. Möglicherweise läuft er nicht oder der angegebene Pfad stimmt nicht.
*:Überprüfen Sie die adb-Konfiguration in den Einstellungen und versuchen Sie den adb-Server zu starten und eine Verbindung herzustellen indem Sie auf den Knopf klicken.
*Verbinden ...
*:expecco verbindet sich mit dem adb-Server. Dies kann einige Sekunden dauern.
*adb-Server starten ...
*:expecco startet den adb-Server. Dies kann einige Sekunden dauern.

Mit "''Weiter''" gelangen Sie zum nächsten Schritt. Wenn Sie Einstellungen für den GUI-Browser eingeben, ist das erst möglich, wenn ein Gerät ausgewählt wurde.

Anmerkung zum Freischalten: In jüngeren Android Versionen werden die Entwickleroptionen zunächst nicht mehr in den Einstellungen angeboten. Falls ihr Android Gerät in den Einstellungen keinen Eintrag zu "''Entwickleroptionen''" zeigt, wählen Sie zunächst den Eintrag "''Telefoninfo''", dann "''SoftwareVersionsInfo''" und klicken darin mehrfach auf den Eintrag "''BuildVersion''".

==== Chromedriver verwalten ====
Wenn die App, die Sie bedienen wollen, WebViews mit Chrome benutzt, benötigt Appium Zugriff auf einen passenden Chromedriver. Wenn Sie ein Gerät in der Liste auswählen, können Sie über "''Chromedriver verwalten''" sehen, welche Chrome-Versionen auf dem Gerät vorhanden sind und welche Chromedriver-Versionen durch expecco zur Verfügung stehen. Über diesen Dialog können Sie auch benötigte Chromedriver-Versionen herunterladen. Beachten Sie, dass auf dem Gerät verschiedene Chrome-Versionen vorhanden sein können, da die Apps in ihren WebViews nicht die gleiche Chrome-Version verwenden müssen, wie die als Browser installierte. Damit alles funktioniert, sollte der verwendete Chromedriver zur entsprechenden App passen. Sie können den Pfad zum Chromedriver auch am Ende des Verbindungsdialogs in den erstellten Capabilities ändern.

==== WLAN-Android-Geräte verbinden ====
Sie können sich auch über WLAN zu Android-Geräten verbinden. Dazu muss das Gerät zunächst mit adb verbunden werden, siehe [[Mobile_Testing_Plugin#Verbindung_.C3.BCber_WLAN|Verbindung über WLAN]]. Ab expecco 22.1 bietet der Verbindungseditor hierfür einen Dialog, der Ihnen dabei hilft und den Sie anstatt der Eingabeaufforderung verwenden können. Für Geräte mit Android 11 oder höher können Sie hier das Gerät mit dem Rechner zu koppeln, indem Sie die entsprechenden Parameter angeben und anschließend die Verbindung unter Angabe von IP-Adresse und Port aufbauen. Sie können damit auch für Geräte, die über USB verbunden sind, eine WLAN-Verbindung aufbauen. Wenn Sie das entsprechende Gerät in der Liste auswählen, werden die benötigten Angaben automatisch ausgelesen.

Beachten Sie, dass der Aufbau einer WLAN-Verbindung nicht Teil der Verbindungseinstellungen ist. Wenn Sie mit den erzeugten Einstellungen eine neue Verbindung aufbauen wollen, müssen Sie sicherstellen, dass das Gerät über mit der angegebenen IP-Adresse und dem Port mit adb verbunden ist, damit es gefunden wird. Die ADB-Verbindung geht verloren, wenn der ADB-Server oder das Gerät neu gestartet werden. Die Erlaubnis für das WLAN-Debugging wird beim Neustart des Geräts auch häufig zurückgesetzt und der Debug-Port kann dann wechseln. Daher muss eine WLAN-Verbindung immer manuell hergestellt werden.

===Schritt 2: App auswählen===
Hier können Sie Angaben zur App machen, die getestet werden soll. Dabei können Sie entscheiden, ob Sie eine App verwenden wollen, die bereits auf dem Gerät installiert ist, oder ob für den Test eine App installiert werden soll. Wählen Sie oben den entsprechenden Reiter aus. Je nachdem, ob Sie im vorigen Schritt ein Android- oder ein iOS-Gerät ausgewählt haben, ändert sich die erforderte Eingabe.

*'''Android'''
**''App auf dem Gerät''
**:Wenn Sie im ersten Schritt ein angeschlossenes Gerät ausgewählt haben, werden die Pakete aller installierten Apps automatisch abgerufen und Sie können die Auswahl aus den Drop-down-Listen treffen. Die installierten Apps sind in Fremdpakete und Systempakete unterteilt; wählen Sie die entsprechende Paketliste aus. Diese Auswahl gehört nicht zu den Einstellungen, sondern stellt nur die entsprechende Paketliste zur Verfügung. Sie können den Filter benutzen, um die Liste weiter einzuschränken und dann das gewünschte Paket auswählen. Die Activities des ausgwählten Pakets werden ebenfalls automatisch abgerufen und als Drop-down-Liste zur Verfügung gestellt. Wählen Sie die Activity aus, die gestartet werden soll. In der Regel wird automatisch eine Activity aus der Liste eingetragen. Falls Sie kein verbundenes Gerät verwenden, müssen Sie die Eingabe des Pakets und der Activity von Hand vornehmen.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Benutzen Sie einen lokalen Appium-Server, können Sie den rechten Butten benutzen, um zu der Installationsdatei der App zu navigieren und diesen Pfad einzutragen. Wenn möglich werden dabei auch das entsprechende Paket und die Activity in den Feldern darunter eingetragen. Diese Angabe ist aber nicht notwendig.

*'''iOS'''
**''App auf dem Gerät''
**:Geben Sie die Bundle-ID einer installierten App an. Sie können die IDs der installierten Apps bspw. mithilfe von Xcode erfahren. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü "''Window''" den Eintrag "''Devices''". Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wenn Sie Ihr Gerät auswählen, sehen Sie in der Übersicht eine Auflistung der von Ihnen installierten Apps.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Zu den Vorraussetzungen an Apps für reale Geräte lesen Sie bitte den Abschnitt [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Geräte und App vorbereiten]].

Im unteren Teil können Sie festlegen, ob die App beim Verbindungsabbau zurückgesetzt bzw. deinstalliert werden soll, und ob sie initial zurückgesetzt werden soll. Auch hier wird die entsprechende Capability gar nicht gesetzt, wenn Sie "''(Default)''" auswählen. Mit "''Weiter''" gelangen Sie zum nächsten Schritt.

===Schritt 3: Servereinstellungen===
Im letzten Schritt befindet sich zunächst im oberen Teil eine Liste aller Capabilities, die sich aus Ihren Angaben der vorigen Schritte ergeben. Wenn Sie sich mit Appium auskennen und noch zusätzliche Capabilities setzen möchten, die der Verbindungseditor nicht abdeckt, können Sie durch Klicken auf "''Bearbeiten''" in die erweiterte Ansicht gelangen. Lesen Sie dazu den Abschnitt weiter unten.

Wenn Sie Einstellungen für den GUI-Browser eingeben, können Sie den ''Verbindungsnamen'' eintragen, mit dem die Verbindung angezeigt wird. Dies ist auch der Name unter dem Bausteine diese Verbindung verwenden können, wenn sie aufgebaut ist. Wenn Sie das Feld frei lassen, wird ein Name generiert. Wenn der Haken für "''Von expecco gesteuert''" gesetzt ist, wird expecco einen lokalen Appium-Server an einem freien Port starten, oder einen bereits gestarteten freien Server verwenden. Um einen eigenen Server zu verwenden, schalten Sie diese Funktion ab und geben Sie die entsprechende Adresse ein. Sie erhalten die lokale Standard-Adresse und bereits verwendete Adressen zur Auswahl.

In älteren expecco-Versionen ist der Haken mit "''Bei Bedarf starten''" beschriftet. In diesem Fall müssen Sie auch eine Adresse angeben, wenn expecco den Server starten soll. expecco versucht dann beim Verbinden einen Appium-Server an der angegebenen Adresse zu starten, wenn dort noch keiner läuft. Dieser Server wird dann beim Beenden der Verbindung ebenfalls heruntergefahren. Dies funktioniert nur für lokale Adressen. Achten Sie darauf, nur Portnummern zu verwenden, die auch frei sind. Verwenden Sie am besten nur ungerade Portnummern ab dem Standardport 4723. Beim Verbindungsaufbau wird ebenfalls die folgende Portnummer verwendet, wodurch es sonst zu Konflikten kommen könnte.

Je nachdem, wie Sie den Dialog geöffnet haben, gibt es nun verschiedene Schaltflächen um ihn abzuschließen. In jedem Fall haben Sie die Option zu speichern. Dabei öffnet sich ein Dialog, indem Sie entweder ein geöffnet Projekt auswählen können, um die Einstellungen dort als Anhang zu speichern, oder auswählen es in einer Datei zu speichern, die Sie anschließend angeben können. Durch das Speichern wird der Dialog nicht beendet, wodurch Sie anschließend noch eine andere Option auswählen könnten.

Wenn Sie den Editor zum Verbindungsaufbau geöffnet haben, können Sie abschließend auf "''Verbinden''" oder "''Server starten und verbinden''" klicken, je nachdem, ob der Haken für den Serverstart gesetzt ist. Für das Ändern oder Kopieren einer Verbindung im GUI-Brower heißt diese Option "''Übernehmen''", da in diesem Fall nur der Verbindungseintrag geändert bzw. neu angelegt wird, der Verbindungsaufbau aber nicht gestartet wird. Das können Sie bei Bedarf anschließend über das Kontextmenü tun. Falls Sie Capabilities einer bestehenden Verbindung geändert haben, fordert Sie anschließend ein Dialog auf zu entscheiden, ob diese Änderungen direkt übernommen werden sollen, indem die Verbindung abgebaut und mit den neuen Verbindungen aufgebaut wird, oder nicht. In diesem Fall werden die Änderungen erst wirksam, nachdem Sie die Verbindung neu aufbauen.

Zur Verwendung des Verbindungseditors lesen Sie auch den entsprechenden Abschnitt im jeweiligen Tutorial in Schritt 1 (Android: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren|Demo ausführen]], iOS: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren_.28iOS.29|Demo ausführen (iOS)]]).

===Erweiterte Ansicht===
Die erweiterte Ansicht des Verbindungseditors erhalten Sie entweder durch Klicken auf "''Bearbeiten''" im dritten Schritt oder jederzeit über den entsprechenden Menüeintrag, wenn Sie den Editor über das Plugin-Menü gestartet haben. In dieser Ansicht erhalten Sie eine Liste aller eingestellten Appium-Capabilities. Zu dieser können Sie weitere hinzufügen, Einträge ändern oder entfernen. Um eine Capability hinzuzufügen, wählen Sie diese aus der Drop-down-Liste des Eingabefelds aus. In dieser befinden sich alle bekannten Capabilities sortiert in die Kategorien ''Common'', ''Android'' und ''iOS''. Haben Sie eine Capability ausgewählt, wird ein kurzer Informationstext dazu angezeigt. Sie können in das Feld auch von Hand eine Capability eingeben. Klicken Sie dann auf "''Hinzufügen''", um die Capabilitiy in die Liste einzutragen. Dort können Sie in der rechten Spalte den Wert setzen. Um einen Entrag zu löschen, wählen Sie diesen aus und klicken Sie auf "''Entfernen''". Mit "''Zurück''" verlassen Sie die erweiterte Ansicht.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Laufende Appium-Server ==
Im Menü des Mobile Testing Plugins finden Sie den Eintrag "''Appium-Server...''". Mit diesem öffnen Sie ein Fenster mit einer Übersicht aller Appium-Server, die von expecco gestartet wurden und auf welchem Port diese laufen. Durch Klicken auf das Icon in der Spalte "''Log anzeigen''" können Sie das Logfile des entsprechenden Servers anschauen. Dieses wird beim Beenden des Servers wieder gelöscht. Mit den Icons in der Spalte "''Beenden''" kann der entsprechenden Server beendet werden. Allerdings wird dies verhindert, wenn expecco über diesen Server noch eine offene Verbindung hat. Für welche Verbindung ein Server verwendet wird, sehen Sie in der rechten Spalte. Steht dort ''<idle>'' wird er zur Zeit nicht von expecco verwendet.

[[Datei:MobileTestingAppiumServer.png]]

Beim Öffnen des Editors um eine Appium-Verbindung aufzubauen, wird direkt ein Appium-Server gestartet, um den folgenden Verbindungsaufbau zu beschleunigen. Zu diesem Zweck hält sich expecco auch immer einen freien Appium-Server offen. Weitere laufende Server, die nicht mehr verwendet werden, werden jedoch nach einiger Zeit automatisch beendet.

Im Menü des Mobile Testing Plugins finden Sie auch den Eintrag "''Alle Verbindungen und Server beenden''". Dies ist für den Fall gedacht, dass Verbindungen oder Server auf andere Weise nicht beendet werden können. Beenden Sie Verbindungen wenn möglich immer im GUI-Browser oder durch Ausführen eines entsprechenden Bausteins. Server, die Sie in der Server-Übersicht gestartet haben, beenden Sie dort; Server, die mit einer Verbindung gestartet wurden, werden automatisch mit dieser beendet.

Beachten Sie, dass in der Übersicht nur Server aufgelistet sind, die von expecco gestartet und verwaltet werden. Mögliche andere Appium-Server, die auf andere Art gestartet wurden, werden nicht erkannt.

== Recorder ==
Besteht im GUI-Browser eine Verbindung zu einem Gerät, kann der integrierte Recorder verwendet werden, um mit diesem Gerät einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

[[Datei:MobileTestingRecorder.png|caption|]]

====Komponenten des Recorderfensters====
#'''Aufnahme fortsetzen/pausieren''': Über das rechte Symbol können Sie die Aufnahme pausieren. Sie sehen dann ein großes Pause-Symbol in der Anzeige. Alle Aktionen, die Sie währenddessen im Recorder machen werden zwar ausgeführt, es werden aber keine Bausteine aufgezeichnet. Über das linke Symbol können Sie dann wieder in den normalen Aufnahmemodus wechseln.
#'''Aufnahme stoppen''': Stoppt die Aufnahme und schließt das Recorderfenster.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Gerät. Dies wird nötig, wenn das Gerät zur Ausführung einer Aktion länger braucht oder sich etwas ohne das Anstoßen durch den Recorder ändert. Seit expecco 21.2 gibt es hier zusätzlich ein Untermenü, mit dem automatisches Aktualisieren angeschaltet werden kann, indem im Hintergrund auf Änderungen geprüft wird (siehe auch ''Automatisches Aktualisieren'' weiter unten).
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Elemente einzeichnen''': Die Rahmen aller Elemente der Ansicht werden angezeigt.
#'''Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst. Dabei stehen folgende Aktionen zur Verfügung:
#*Aktionen auf Elemente:
#**Klicken: Kurzer Klick auf das Element, über dem der Cursor steht. Zur genaueren Bestimmung, welches Element verwendet wird, benutzen Sie die Funktion Follow-Mouse oder Element-Highlighting.
#**Antippen mit Dauer (Element): Ähnlich zum Klicken, nur dass zusätzlich die Dauer des Klicks aufgezeichnet wird. Dadurch sind auch längere Klicks möglich.
#**Antippen mit Position (Element): Ähnlich zum Klicken, aber zusätzlich wird die Position innerhalb des Elements aufgenommen. Die Position kann relativ zur Größe des Elements aufgenommen werden oder, wenn Sie dabei Strg gedrückt halten, absolut zur linken oberen Ecke des Elements.
#**Text setzen: Ermöglicht das Setzen eines Textes in Eingabefelder.
#**Text löschen: Löscht den Text eines Eingabefelds.
#*Aktionen auf das Gerät:
#**Antippen (Bildschirm): Löst einen Klick auf die Bildschirmposition aus.
#**Antippen mit Dauer (Bildschirm): Löst einen Klick auf die Bildschirmposition aus, bei dem auch die Dauer berücksichtigt wird.
#**Wischen: Wischen in einer geraden Linie vom Punkt des Drückens des Mausknopfes bis zum Loslassen. Die Dauer wird ebenfalls aufgezeichnet.
#:Beachten Sie bei diesen Aktionen, dass das Ergebnis sich auf verschiedenen Geräten unterscheiden kann, bspw. bei verschiedenen Bildschirmauflösungen.
#*Erstellen von Testablauf-Bausteinen
#**Attribut prüfen: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Das Ergebnis triggert den entsprechenden Ausgang.
#**Attribut zusichern: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Bei Ungleichheit schlägt der Test fehl.
#**Attribut holen: Liest den aktuellen Wert eines Attributs aus.
#*Automatisch
#:Ist das Auto-Werkzeug ausgewählt, können alle Aktionen durch spezifische Eingabeweise benutzt werden: ''Klicken'', ''Element antippen'' und ''Wischen'' funktionieren weiterhin durch Klicken, wobei sie anhand der Dauer und der Bewegung des Cursors unterschieden werden. Um ein ''Antippen'' auszulösen, halten Sie beim Klicken Strg gedrückt. Die übrigen Aktionen erhalten Sie durch einen Rechtsklick auf das Element in einem Kontextmenü.
#'''Kontext-Aktionen''': Hier können Sie Aktionen aufzeichnen, die Kontexte betreffen:
#*Zu Kontext wechseln: Bietet eine Liste der aktuell verfügbaren Kontexte und Sie können auswählen, zu welchem gewechselt werden soll.
#*Aktuellen Kontext holen: Holt den Handle des aktuellen Kontexts.
#*Kontext-Handles holen: Holt eine Liste aller aktuell verfügbaren Kontext-Handles.
#'''Softkeys''': Nur unter Android. Simuliert das Drücken der Knöpfe Zurück, Home, Fensterliste und Power.
#'''Home-Button''': Nur unter iOS ab expecco 2.11. Ermöglicht das Drücken des Home-Buttons. Vor expecco 19.2 funktioniert es nur, wenn AssistiveTouch aktiviert ist und sich das Menü in der Mitte des oberen Bildschirmrands befindet. Ab expecco 19.2 verwendet die Funktion kein AssistiveTouch mehr.
#'''Hilfe''': Öffnet diese Online-Dokumentation auf der allgemeinen Seite zu [[GuiBrowser_Recorder|GUI-Browser Recordern]].
#'''Anzeige''': Zeigt einen Screenshot des Geräts. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Ansicht anpassen''': Öffnet einen Dialog um die Ansicht anzupassen, falls expecco das Bild nicht richtig darstellt. Sie können die Skalierung anpassen oder das Bild um 90° drehen.
#'''Ausrichtung anpassen''': Korrigiert das Bild, falls dieses auf dem Kopf stehen sollte. Über den Pfeil rechts daneben kann das Bild auch um 90° gedreht werden, falls dies einmal nötig sein sollte. Ab expecco 19.1 finden Sie diese Funktion in ''Ansicht anpassen''. Die Ausrichtung des Bildes ist für die Funktion des Recorders unerheblich, dieser arbeitet ausschließlich auf den erhaltenen Elementen.
#'''Skalierung''': Ändert die Skalierung des Screenshots.
#'''Meldungen''': Zeigt den Pfad des ausgewählten Elements oder andere Meldungen an. Es gibt ein Kontextmenü, um eine Liste der vorigen Meldungen zu sehen.

====Verwendung====
Mit jedem Klick im Fenster wird eine Aktion ausgelöst und im Arbeitsbereich des GUI-Browsers aufgezeichnet. Dort können Sie das Aufgenommene abspielen, editieren oder daraus einen neuen Baustein erstellen.
Aktionen zum Auslösen von Sofkeys finden Sie direkt in der Menüleiste (s.o.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Werkzeugs in der Menüleiste (s.o.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion.
Zur Verwendung des Recorders lesen Sie auch Schritt 2 im Tutorial ([[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen|Android]] bzw. [[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen_.28iOS.29|iOS]]).

====Elemente verbergen====
Ab expecco 21.2 gibt es im Kontextmenü außerdem die Möglichkeit, das ausgewählte Element im Recorder zu verbergen. Das bedeutet, dass dieses Element fortan nicht mehr ausgewählt werden kann. Diese Funktion eignet sich dazu, Elemente zu ignorieren, die im Vordergrund liegen, um auf Elemente darunter zugreifen zu können. Um diesen Zustand wieder rückgängig zu machen, müssen Sie das entsprechende Element im Baum des GUI-Browsers finden, dort gibt es im Kontextmenü ebenfalls einen solchen Eintrag.

====Automatisches Aktualisieren====
Der Recorder zeigt kein Livebild des Geräts sondern nur eine Momentaufnahme. Um mit der Anzeige auf dem Gerät übereinzustimmen muss daher nach Änderungen aktualisiert werden. Der Recorder aktualisiert sich automatisch, nachdem er eine Aktion ausgeführt hat. Ab expecco 20.2 sind zudem weitere automatische Updates möglich. Sie können Sie im Menü ''Fenster'' aktivieren.

Zum einen kann kurze Zeit nach dem Ausführen einer Aktion überprüft werden, ob es noch Änderungen nach der ersten Aktualisierung gegeben hat, damit in diesem Fall eine zweite Aktualisierung stattfinden kann. Dies soll das Problem beheben, dass der Recorder nach einer Aktion nicht aktuell ist, weil die Aktualisierung zu früh stattgefunden hat.

Zum anderen kann eine periodische Aktualisierung eingeschaltet werden. Nach einem einstellbaren Interval wird der Recorder automatisch aktualisiert, sollte es Änderungen geben. Dadurch ist die Anzeige im Recorder immer weitgehend aktuell, allerdings entsteht dadurch auch ein Mehraufwand was die Kommunikation mit dem Gerät betrifft.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid-Apps und WebViews =

'''!!! WICHTIGER HINWEIS - Wenn Sie Probleme haben, auf den Webview zu wechseln, geben Sie bitte unter den Android Einstellungen - Apps -Standard Apps "Chrome" als "Browser-App" an !!!
'''

Hybrid-Apps enthalten neben den Plattform-nativen Elementen weitere Elemente, die in einen WebView eingebunden sind. Diese Elemente können ebenfalls bedient werden, allerdings muss zuvor in den entsprechenden Kontext gewechselt werden. Mit dem Baustein "''Get Current Context''" erhalten Sie den aktuellen Kontext. Zu Beginn ist dies "''NATIVE_APP''", also der Kontext der nativen Elemente. Mit dem Baustein "''Get Context Handles''" bekommen Sie eine Collection aller vorhandenen Kontexte. Gibt es einen WebView-Kontext, so heißt dieser "''WEBVIEW_1''" oder "''WEBVIEW_<package>''" mit dem Paket des WebViews. Es kann auch mehrere WebView-Kontexte geben. Zu jedem WebView-Kontext gibt es im nativen Kontext ein entsprechendes WebView-Element. Mit dem Baustein "''Switch to Context''" können Sie in einen solchen Kontext wechseln und haben fortan nur Zugriff auf die Elemente in diesem Kontext.

Im GUI-Browser werden zum einen oben im Baum die vorhandenen Kontexte angezeigt, zum anderen wird der Baum eines Kontexts unterhalb des entsprechenden WebView-Elements eingefügt.

= XPath anpassen mithilfe des GUI-Browsers =
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen "''GTIN-13 (EAN-13)''" und "''Verify''", das Eingabefeld der Zahl "''4006381333986''" und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des "''GTIN-13''"-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch "''Pfad überprüfen''" (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit "''Verify Path: OK''" (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit "*" zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert "''GTIN-13 (EAN-13)''" besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer "''hierarchy''" (für iOS wäre es "''AppiumAUT''"), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix "''android.widget.''", das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend "''XCUIElementType''" am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. "''FrameLayout''" ist ein Kindelement von "''hierarchy''", "''LinearLayout''" ist ein Kind von "''FrameLayout''" usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element "''hierarchy''" beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben "''TextView''"-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ "''Button''" gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut "''resource-id''". Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut "''name''" verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem "@" eingeleitet und der Wert mit einem "=" in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter "''Test''" eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf "''Lauf''". Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu "''Eigenschaften''", wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

== Weitere Locator-Strategien ==
Appium bietet neben XPath noch weitere Strategien zur Adressierung von Elementen an. Einige davon stehen Ihnen '''ab Version 20.1''' ebenfalls mit expecco zur Verfügung. Diese sind nicht ganz so mächtig wie XPath, dafür aber häufig schneller bei der Auflösung auf dem Gerät. Insbesondere bei der Verwendung mit iPhones, wo die Hierarchie bei jeder XPath-Auflösung erst aufgebaut werden muss, bieten alternative Strategien einen Vorteil für die Laufzeit.

XPath ist weiterhin der Standard, das heißt alle Locator ohne besondere Angabe werden als XPath interpretiert. Um eine der anderen Strategien zu verwenden, schreiben Sie diese mit einem Gleichzeichen vor den gewünschten Locator. Diese Technik können Sie sowohl an den Blöcken verwenden, als auch im GUI-Browser testen.

{|
|-
| style="vertical-align:top" | AccessibilityId || style="padding-bottom:0.5em" | Verwendet den Wert des Elements, der dazu dient, die App barrierefrei zu machen. Für iOS ist das das Attribut '''Accessibility-id''', für Android das Attribut '''content-descr'''. ''Beispiel: accessibilityId=Löschen''
|-
| style="vertical-align:top" | className || style="padding-bottom:0.5em" | Verwendet den Namen der Klasse des Elements. ''Beispiel: className=android.widget.FrameLayout''
|-
| style="vertical-align:top" | id || style="padding-bottom:0.5em" | Verwendet die Kennung des Elements. Für iOS ist das das Attribut '''name''', für Android das Attribut '''resource-id'''. ''Beispiel: id=android:id/text1''
|-
| style="vertical-align:top" | iOSClassChain1 || style="padding-bottom:0.5em" | Verwendet die Hierarchie der Elemente ähnlich wie bei XPath. Eine Erklärung zum Aufbau finden Sie [https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules hier]. ''Beispiel: iOSClassChain=XCUIElementTypeWindow/XCUIElementTypeButton[`label == "Ok"`]''
|-
| style="vertical-align:top; padding-right:1em" | iOSNsPredicateString1 || style="padding-bottom:0.5em" | Verwendet einfache Kriterien, wie Attribute, die auch kombiniert werden können. ''Beispiel: iOSNsPredicateString=type == 'XCUIElementTypeButton' AND name == 'Weiter'''
|-
| style="vertical-align:top" | name1 || style="padding-bottom:0.5em" | Verwendet den Namen des Elements. ''Beispiel: name=Bestätigen''
|-
|}

:1 ''nur für iOS''

Um eine direkte Beschleunigung mit iOS zu erzielen, ohne dass Sie Ihre bisherigen Pfade anpassen müssen, wandelt expecco zudem Pfade, die nur aus einem Element mit Klasse und name-Attribut bestehen, zur Laufzeit automatisch in einen entsprechenden Locator der Strategie iOSNsPredicateString um. Wenn Sie einen Pfad explizit als XPath markieren, wird diese Anpassung nicht vorgenommen.

=Probleme und Lösungen=
== Locator sind versionsabhängig oder variabel ==
Dann sollten Sie die Locator (xPath) entweder in einer Variablen halten oder ein Locator-Mapping in einem Screenplay Anhang definieren. Es ist auch möglich, lediglich Teile des Locators (z.B. Locator-Pfad eines Elternelements oder Attributwert) in einer Variable zu halten und im Freezevalue des Locator-Pins mit "''$(varName)''" einzufügen.

==Unsichtbare UI-Elemente==
Beachten Sie, dass im [[#Recorder|Recorder]] auch Elemente berücksichtigt werden, die Sie auf dem Bildschirm nicht sehen. Schalten Sie daher das Element-Highlighting an oder nutzen Sie die Follow-Mouse-Funktion und den Elementbaum im GUI-Browser, um festzustellen, ob das richtige Element verwendet wird. Es kann vorkommen, dass unsichtbare Elemente vor anderen Elementen liegen und diese verdecken, so dass die gewünschten Elemente im Recorder nicht ausgewählt werden können. Lesen Sie dazu den Abschnitt [[#Elemente_verbergen|Elemente verbergen]].

==iOS: Kabel nicht zertifiziert==
In manchen Fällen erscheint beim Verbinden eines iOS-Geräts über USB der Hinweis, das verwendete Kabel sei nicht zertifiziert. In diesem Fall hilft es nur, das entsprechende Kabel auszutauschen.
==iOS: Alerts beim Verbindungsaufbau==
Stellen Sie sicher, dass beim Verbindungsaufbau mit einem iOS-Gerät keine Alerts geöffnet sind. Der Aufbau schlägt sonst fehl, da die App nicht in den Vordergrund kommen kann. Siehe auch [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Gerät und App vorbereiten]].

==iOS: .ipa installieren nicht möglich==
Beachten Sie, dass auf iOS-Simulatoren keine ''.ipa''-Dateien sondern nur ''.app''-Dateien installiert werden können.

==iOS: Erster Verbindungsaufbau funktioniert nicht==
Wenn auf Ihrem Mac noch kein signierter Build des WebDriverAgents liegt, muss dieser beim ersten Verbindungsaufbau erst erzeugt werden. Das kann in der Regel etwas länger als eine Minute dauern. Standardmäßig verwendet Appium aber einen Timeout von 60000 ms um zu warten bis der WebDriverAgent auf dem Gerät startet, so dass der Aufbau in diesen Fällen abgebrochen wird. Sie können den Timeout mit der Capability ''wdaLaunchTimeout'' setzen, z.B. auf ''120000''.

Außerdem müssen die Einstellungen für die Signierung passen. Am zuverlässigsten funktioniert das nach unserer Erfahrung, wenn man im Xcode-Projekt des WebDriverAgents auf automatische Signierung stellt und das Team setzt. Siehe dazu die Erklärung im Abschnitt [[#WebDriverAgent-Signierung|WebDriverAgent-Signierung]]. In diesem Fall sollten Sie die Capabilities ''xcodeConfigFile'' bzw. ''xcodeOrgId'' und ''xcodeSigningId'' '''nicht''' verwenden, da es sonst zu Konflikten kommen kann. Achtung: Wenn Sie eine Team-ID in den Mobile-Testing-Einstellungen gesetzt haben, setzt expecco diese automatisch als ''xcodeOrgId''!

Achten Sie beim ersten Verbindungsaufbau außerdem auf Ihr Gerät, da Sie dort möglicherweise der Installation per Passwort zustimmen müssen. Auf dem Mac kann die Eingabe des Passworts zur Freigabe des Schlüsselbunds für die Signierung nötig werden, häufig auch mehrmals.

==Android: Gerät nicht im Verbindungsdialog==
Wenn ein über USB angeschlossenes Android-Gerät nicht im Verbindungsdialog auftaucht, versuchen Sie, den USB-Verbindungstyp zu ändern. In der Regel sollten MTP oder PTP funktionieren. Prüfen Sie nochmal, ob "USB Debugging" in den Entwicklereinstellungen des Geräts aktiviert ist (diese Einstellungen sind bei manchen Geräten zunächst unsichtbar, und müssen durch einen Trick zugänglich gemacht werden). Siehe auch [[#Android-Ger.C3.A4t_vorbereiten|Android-Gerät vorbereiten]].

==Android: Abgeschnittene Elemente unten==
Bei Android-Geräten, die die Steuerungsleiste bzw. Softkeys automatisch ein- und ausblenden, kann es vorkommen, dass der Recorder im unteren Bereich Elemente abschneidet, die durch die Softkeys verdeckt würden, auch wenn sie zu diesem Zeitpunkt gar nicht angezeigt werden. In diesem Fall hift es, die Softkeys so einzustellen, dass sie in einer permanenten Leiste angezeigt werden.

Bei neueren Android-Versionen gibt es eine solche Einstellung in der Regel nicht. Auch wenn die Steuerelemente permanent eingeblendet sind, liegen sie auf keiner extra Leiste, sondern vor dem Inhalt der App. Es gibt dann im unteren Teil einen Bereich, der nicht bedient werden kann, weil er nicht zum aktiven Bereich der App gezählt wird, weshalb die Elemente von Appium abgeschnitten werden. Dieser Bereich kann auch größer sein als von den Steuerungselementen beansprucht. Bekannt ist dies für Samsung-Geräte mit Android 11. Da die Information über die Größe des App-Bereichs bereits auf Android-Ebene so geliefert wird, können wir hierfür keine Lösung anbieten, sondern können nur hoffen, dass das Problem vom Hersteller behoben wird. Sie können versuchen, ob Sie mit der Einstellung von Gestensteuerung bessere Ergebnisse bekommen, allerdings gibt es hier das gleiche Problem.

== Android: Test hängt beim Suchen eines Elements==
Der Baustein ''Find Element by XPath'' und alle Element-Bausteine warten bis ein Element zum angegebenen Pfad auftaucht. Den Timeout dafür kann man entweder am Baustein direkt oder in den Umgebungsvariablen ändern. Wenn das Element aber bereits da sein sollte und es dennoch sehr lange dauert, bis der Test weitergeht, kann das am UIAutomator/UIAutomator2 liegen. Dieser wartet, bis die App in den Idle-Zustand geht, bevor er überhaupt nach Elementen sucht. Dies kann länger dauern, wenn die App z.B. im Hintergrund noch Animationen abspielt oder andere Aktionen ausführt. Auch das Holen des Page-Sources z.B. beim Aktualisieren im GUI-Browser oder im Recorder kann dadurch länger dauern. Standardmäßig gibt es hierfür einen Timeout von 10 Sekunden, nach dem nicht weiter auf den Idle-Zustand gewartet wird. Dieser Timeout lässt sich durch eine Einstellung in Appium anpassen (waitForIdleTimeout). Falls Sie einen anderen Wert für diesen Timeout setzen möchten, ist dies ab expecco 21.2 möglich, indem Sie vor dem Test den Smalltalk-Code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> ausführen. Der Timeout wird in Millisekunden angegeben, das Beispiel setzt ihn also auf 2 Sekunden.

==Android: Aktualisieren des Trees oder Wechseln zum Webview-Kontext braucht zu lange==
Speziell mit älteren Geräten kann es vorkommen, dass neuere Chromedriver nicht initialisiert werden können. Das führt dann dazu, dass nicht in den Webview-Kontext gewechselt werden kann. Dies wird von Appium allerdings nur über einen Timeout festgestellt, der standardmäßig bei 4 Minuten liegt. Da expecco auch beim Aufbauen des Trees im GUI-Browser versucht in den Webview-Kontext zu wechseln, kann das zu sehr langen Ladezeiten führen. Da es in Appium keine Möglichkeit gibt, diesen Timeout herunter zu setzen, haben wir die Version, die wir im MobileTestingSupplement bereitstellen, um eine entsprechende Capability erweitert. Ab der Version 1.13.1.0 des [[#Windows|MobileTestingSupplements]] kann mit ''chromedriverStartTimeout'' der Timeout in Millisekunden gesetzt werden. Der Wechsel funktioniert dadurch zwar trotzdem nicht, aber expecco braucht dann nicht mehr so lange beim Aktualisieren des Trees und der Baustein zum Wechseln des Kontextes schlägt schneller fehl. Der Verbindungsdialog fügt diese Capability ab expecco 22.1 automatisch hinzu.

==Keine Aktion bei Klick==
Der Baustein zum Klicken auf ein Element ist erfolgreich, aber auf dem Gerät wurde keine Aktion ausgeführt.
:Dies kann vorkommen, wenn das Element von einem anderen Element verdeckt ist und ein Klick auf das Element deshalb nicht möglich ist. In diesem Fall wird von Appium kein Fehler geworfen, sondern es passiert einfach nichts. Wenn Sie dennoch einen Klick an der Position des Elements machen möchten, auch wenn es verdeckt ist, benutzen Sie stattdessen den Baustein ''Tap'' und übergeben Sie diesem die Position des Elements (''Get Location''). Wenn Sie stattdessen vor einem Klick prüfen möchten, ob das Element zu diesem Zeitpunkt verdeckt ist, versuchen Sie, ob Ihnen die Eigenschaften ''Is Displayed'' oder ''Is Enabled'' weiterhelfen.

==Kein Update nach Aktion==
Über den Recorder wurde eine Aktion ausgeführt, für die auch ein Baustein aufgezeichnet wurde, der Recorder zeigt aber immer noch das alte Bild.
:Der Recorder zeigt kein Livebild des Geräts, sondern immer nur eine Momentaufnahme. Nachdem eine Aktion ausgeführt wurde, aktualisiert sich der Recorder automatisch. Es kann aber vorkommen, dass das Bild schon aktualisiert wurde, bevor die Auswirkungen der Aktion auf dem Gerät vollständig abgeschlossen sind. In diesem Fall sollten Sie den Recorder von Hand aktualisieren über das Symbol mit den blauen Pfeilen. Ab expecco 20.2 können Sie für diesen Fall auch automatisches Aktualisieren einstellen. Siehe auch Beschreibung zum [[#Recorder|Recorder]].

=="clickable" Attribut falsch==
Ein Element hat im "''clickable''" Attribut/Property den Wert "''false''", ist aber dennoch anklickbar.
:Das "''clickable''" Attribute muss explizit vom App-Programmierer gesetzt werden, und hat tatsächlich keine Relevanz für das tatsächliche Verhalten der App. Sie sollten dieses Attribut i.A. in Ihren Tests nicht beachten. Leider existieren viele Apps, bei denen der Programmierer hier "lazy" war.

==Verbindungsaufbau schlägt fehl==
Schlägt der Verbindungsaufbau mit dem Appium-Server fehl, erhalten Sie in expecco eine Fehlermeldung ähnlicher der unten abgebildeten.

[[Datei:MobileTestingVerbindungsfehler.png]]

Hier sehen Sie die Art des aufgetretenen Fehlers. Klicken Sie auf "''Details''" um nähere Informationen zu erhalten. Mögliche Fehler sind:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:Der angegebene Server läuft nicht oder ist nicht erreichbar. Überprüfen Sie die Serveradresse.
*''org.openqa.selenium.WebDriverException''
:Lesen Sie in den Details in der ersten Zeile die Meldung hinter ''Original Error'':
:*''Unknown device or simulator UDID''
::Entweder ist das Gerät nicht richtig angeschlossen oder die udid stimmt nicht.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::Dieser Fehler kann verschiedene Ursachen haben. Entweder konnte tatsächlich der WebDriverAgent nicht gebaut werden, weil die Signierungseinstellungen falsch sind oder das passende Provisioning Profile fehlt. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]]. Es kann auch sein, dass der WebDriverAgent auf dem Gerät nicht gestartet werden kann, weil sich beispielsweise ein Alert im Vordergrund befindet oder Sie dem Entwickler nicht vertraut haben.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::Die angegebene App kann nicht auf dem iOS-Gerät installiert werden, weil es nicht im Provisioning Profile der App eingetragen ist.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.'''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die Datei unter dem angegebenen Pfad auf dem Mac befindet.
:*''packageAndLaunchActivityFromManifest failed.''
::Die angegebene ''apk''-Datei ist vermutlich kaputt.
:*''Could not find app apk at [...]''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die ''apk''-Datei am angegebenen Pfad befindet.

Falls der Fehler nicht durch eine der oben gelisteten Ursachen bedingt ist, kann es sein, dass die auf dem Gerät befindlichen Automation-Anwendungen nicht mehr richtig funktionieren. Hier hilft es, diese vom Mobilgerät zu deinstallieren. Beim nächsten Verbindungsaufbau werden sie dann automatisch neu installiert.

*Für iOS-Geräte ist das der WebDriverAgent, den Sie einfach vom Home-Screen deinstallieren können. Dies behebt in der Regel Probleme durch den Wechsel des verwendeten Macs oder der Xcode-Version.

*Für Android-Geräte ist es der UIAutomator2; hier tritt auf einigen Geräten sporadisch ein Problem auf, die Ursache dafür ist uns z.Z. noch nicht bekannt. Zur Deinstallation navigieren Sie auf dem Gerät zu "''Einstellungen''" > "''Anwendungen''"* und suchen in der Liste nach folgenden Einträgen:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Klicken Sie auf die jeweilige Anwendung und dann auf "''Deinstallieren''".
*''Der entsprechende Eintrag heißt auf manchen Geräten möglicherweise etwas anders.''

Falls dies nicht hilft, kann eventuell die Ausgabe des Appium-Servers weiterhelfen. Für einen von expecco gestarteten Server finden Sie das Log in der Liste der [[#Laufende_Appium-Server|laufenden Appium-Server]].

==Ich habe keinen Mac==
Vielleicht hilft Ihnen diese Webseite weiter: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Timeline

2023-12-22T09:04:43Z

Matilk: /* Einleitung */ warning for large logs

= Einleitung =
[[Datei:Timeline.png|800px|thumb|Der Reiter "Zeitleiste"]]
Die Zeitleiste (Timeline) kann ein hilfreiches Werkzeug sein, um die zeitliche Abfolge Ihrer Testsequenzen zu verstehen, insbesondere, wenn Aktionen parallel laufen. Sie finden sie in der ''Lauf'' Anzeige entweder eines Testplans oder eines Aktionsblocks. Sie verwendet die gesammelten [[Glossary/en#Activity_Log|Logdaten]] um anzuzeigen wann und wie lange eine Aktion ausgeführt wurde.

Diese Funktionalität ist in expecco 23.2 noch experimentell und kann bei großen Logs oder während des Laufs an ihre Grenzen stoßen.

= Darstellung =
Die Zeitleiste zeigt die Unterblöcke des ausgewählten Blocks als Balken in der Farbe ihres Ausführungsstatus, wobei deren Länge und horizontale Position die Dauer und Startzeit der Ausführung widerspiegeln. Die Zeitskala oben passt sich der dargestellten Zeit an. Das aktuelle Zeitformat können Sie in der oberen rechten Ecke ablesen; z.B. bedeutet ''m:s'' eine Darstellung in Minuten und Sekunden, wobei die Sekunden noch Dezimalstellen aufweisen können, um die Millisekunden anzuzeigen.

Anfangs wird nur die oberste Ebene der Unterblöcke des ausgewählten Blocks angezeigt. Wenn Blöcke parallel ausgeführt werden, landen sie in verschiedenen Zeilen; nacheinander ausgeführte Blocke stehen in einer Zeile. Allerdings bedeutet es für zwei Blöcke, die hintereinander stehen NICHT generell, dass der zweiten vom ersten gestartet wurde.

Sie können Blöcke ausklappen, um deren Unterblöcke zu sehen. Ist ein Block breit genug, wird dies durch ein entsprechendes kleines Icon in der oberen linken Ecke angezeigt. Sie können Blöcke auf- und zuklappen, indem Sie auf dieses Icon klicken. Alternativ können Sie auf einen Block mit der rechten Maustaste klicken und erhalten im Kontextmenü die Möglichkeit, ihn auf- oder zuzuklappen. Die Unterblöcke werden unterhalb ihrer Eltern angezeigt, wobei sich etwaige parallele Blöcke weiter nach unten verschieben. Der Rahmen eines Blocks umfasst seine Unterblöcke um die Verschachtelung zu verdeutlichen. Sie können auch Strg gedrückt halten, um alle Kinder auszuklappen. Da die Zeitleiste nur die Informationen aus den Logdaten darstellt, werden auch nur Blöcke angezeigt, die einen Logeintrag haben. Blöcke, die im Log übersprungen wurden, werden nicht angezeigt.

Wenn Sie einen Block in der Zeitleiste anklicken, wird er ausgewählt, was durch einen roten Rahmen dargestellt wird. Die Hauptinformationen dieses Blocks werden zum Meldungsfenster in der unteren linken Ecke des expecco-Fensters hinzugefügt. Außerdem werden Sie als Tooltip angezeigt, wenn Sie mit der Maus über den Block fahren.

= Navigation =
Standardmäßig wird die gesamte Dauer des Laufs im Fenster angezeigt. Sie können aber heranzoomen, um bestimmte Abschnitte besser zu analysieren. Sie können die Menübuttons und die Maus verwenden, um sich auf der Zeitleiste zu bewegen.

== Menüzeile ==
[[Datei:Timeline_Menubar.png]]
# Höhe der Zeilen verringern
# Höhe der Zeilen vergrößern
# Zeitleiste auf verfügbaren Breite strecken Ein Umschaltknopf: wenn er aktiviert ist, wird die gesamte Laufdauer auf die Breite des Reiters gestreckt.
# Herauszoomen Die Breite der Zeitleiste verkleinern, sodass mehr Zeit auf weniger Platz dargestellt wird
# Hineinzoomen Die Breite der Zeitleiste vergrößern, sodass weniger Zeit auf mehr Platz dargestellt wird und besser analysiert werden kann
# Springe zum Start der ausgewählten Aktion
# Springe zum Ende der ausgewählten Aktion
# Relative Ausführungszeiten Die Block-Informationen bspw. im Tooltip zeigen die Startzeit relativ zum Beginn des dargestellten Blocks und die Dauer falls aktiviert, ansonsten absolute Start- und Endzeiten

== Mauseingabe ==
Normales Scrollen verschiebt das Diagram vertikal, bei gedrückter Shift-Taste horizontal. Durch Scrollen bei gedrückter Strg-Taste können Sie an der Cursorposition zoomen. Falls das Strecken der Zeitleiste deaktiviert ist, können Sie an einem Punkt in der Zeitskala klicken und zu einem anderen ziehen, um einen Zeitabschnitt auszuwählen. Dieser wird dabei gelb markiert. Wenn Sie die Maustaste loslassen, wird die Zeitleiste auf diesen Abschnitt herangezoomt.

[[Datei:Timeline_Select_Time.png]]

= Auswählen =
Wie bereits erwähnt, können Sie einen Block durch Klicken auswählen. Wenn Sie doppelklicken, wird der Block im Baum ausgewählt und die Zeitleiste wechselt zur Darstellung seiner Unterblöcke.

Sie können die Zeitleiste (und gleichzeitig das Netzwerk, die Logdaten und die Ein/Ausgänge) auch auf den ausgewählten Block fixieren, indem Sie den Toggle-Button [[Datei:Timeline_Lock_Button.png]] im Menü des Baums aktivieren. Dies wird durch ein kleines Schloss-Symbol neben dem Eintrag des fixierten Blocks im Baum angezeigt. Wenn Sie nun einen anderen Block im Baum auswählen, wird er in der Zeitleiste des fixierten Blocks ausgewählt. Genauso können Sie auf einen Block in der Zeitleiste doppelklicken und sein Eintrag wird im Baum ausgewählt ohne die angezeigte Zeitleiste zu ändern.

Timeline/en

2023-12-22T09:02:04Z

Matilk: /* Introduction */ warning for large logs

= Introduction =
[[Datei:Timeline.png|800px|thumb|Timeline Tab]]
The Timeline can be a useful tool, when you want to understand the chronology of your test sequence, especially when actions are running in parallel. It can be found in the ''Run'' section of either a testplan or an action block. It uses the information collected in the [[Glossary/en#Activity_Log|Activity Log]] to show when and for how long an action was executed.

This feature is still experimental in expecco 23.2 and may reach its limits with large logs or while running.

= Representation =
The timeline shows the subblocks of the selected block as bars in the color of their execution state, where their length and horizontal position represents the duration and start time of their execution. The timescale at the top adapts to the presented time. You see the current time format in the top right corner, e.g. ''m:s'' means minutes and seconds separated by a colon, where the seconds may have digits after the decimal point to show the milliseconds.

Initially only the top blocks of the selected blocks are shown. If blocks are executed in parallel, they go in different lines, consecutive blocks are in one line. However, if two blocks are one after the other in the same line, that does NOT indicate, that the first block triggered the second.

You can expand blocks, to see its subblocks. If a block is wide enough, it shows a little expand icon in its left corner. You can expand or collapse the block by clicking on this icon. Alternatively, you can right click on a block and select expand or collapse from its context menu. The subblocks are displayed below their parent block, pushing any parallel block further down in the diagram. The frame of a block includes its subblocks, visualizing the nesting. If you hold Ctrl when expanding a block, it will expand all of its children. As the timeline only displays the information from the Activity Log, you can only see the blocks, that have an log entry. You cannot see blocks, that are skipped in the log.

If you click on a block in the timeline it gets selected, which is indicated by a red frame. The main information of that block is added to the messages in the lower left corner of the expecco window. You also get this information as tooltip when hovering over a block.

= Navigation =
As default the whole duration is displayed in the panel, but you can zoom in, to better see a certain section. You can use the buttons of the menu bar to navigate through the timeline and use the mouse.

== Menu bar ==
[[Datei:Timeline_Menubar.png]]
# Decrease the height of lines
# Increase the height of lines
# Stretch the timeline to the available width This is a toggle, if it is on, the whole run time is stretched to the width of the panel.
# Zoom out Decrease the width of the timeline, so that more time is shown in less space.
# Zoom in Increase the width of the timeline, so that less time is shown in more space and can be analyzed better.
# Jump to the start of the selected action
# Jump to the end of the selected action
# Relative execution times The block information e.g. in the tooltip shows the start time relative to the start time of the displayed block and the duration if on, or the absolute start and end time if off.

== Mouse Input ==
Normal scrolling moves the diagram vertically, scrolling with the Shift key held down moves it horizontally. You can zoom in and out on the cursor position by scrolling while holding down the Ctrl key. If stretch is disabled, you can click at a point in the timescale and drag to another to select a time period, which is highlighted in yellow. When you release the mouse button, the timeline zooms to that period.

[[Datei:Timeline_Select_Time.png]]

= Selecting =
As earlier already mentioned, you can select a block by clicking on it. When double clicking on it, it gets selected in the tree and so the timeline will switch to only display the subblocks of this block.

You can also lock the timeline (and as well the network, log and pin entries) to the block selected in the tree, by activating the toggle [[Datei:Timeline_Lock_Button.png]] in the menu of the tree. This will be indicated by a little lock icon next to the tree icon of the locked block. If you now select another block in the tree, it gets selected in the timeline of the locked block. Similar you can double click on a block in the timeline and its entry in the tree will be selected without changing the displayed timeline.

Release Notes 23.x

2023-12-22T08:54:38Z

Matilk:

See also: [[Release Notes 22.x]]
 

== Release 23.2 (December 2023) ==
*Feature: [[Environment_Editor/en#Fields|Static (Step-) Variables]]
*Feature: DOM inspector (try an XML attachment) generates better xpath suggestions (alternatives in [[Attachment_Editor/en#XML_Inspector | attachment editor]])
*Feature: [[Testplan_Editor/en#Log_Processor_Action|log processors]] are now configurable both for individual test cases and for the overall result of a testplan
*Feature: [[Testplan_Editor/en#Log_Processor_Action|log processor]] activities are shown in a testplan's activity log (but not in a report)
*Feature: Qt-Library: New Action ''QButton::Click'': direct click, not being delegated to a thread
*Feature: Qt-Testing: ExpeccoTestService library and Inject-Tool for QT5.15.0 and VS2022: [[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]]
*Feature: [[Timeline/en|Timeline view]] for the activity log (Still experimental, might reach its limits with too large logs or while running)
*Feature: more [[Testplan_Editor/en#Execution_Settings | pathname options]] for testplan when generating ELF-per-run result files (in loops)
*Feature: a new [[Testplan_Editor/en#Execution_Settings | option]] in testplan to skip successful tests when looping
*Feature: enhanced manual test wizard with the option to execute the manual tests with a mobile device (Android, Apple IOS or Web-Browser)
*Feature: [[Expecco_API/en#Bridged_Ruby_Elementary_Blocks |bridged Ruby elementary actions]]
*Feature: Improvements in the XML inspector (tree popup menu & string search)
*Feature: [[Expecco_API/en#Bridged_Python_Elementary_Blocks |bridged Python elementary actions]] can now be cancelled and terminated
*Feature: Python settings: Reorganize Python paths, export Python bridge code for debugging in external IDE ([[Installing additional Frameworks/en#Python_Installation|Python_Installation]])
*Feature: improved [[Tools_TestSuiteDifferenceBrowser|difference viewer]] (project and version compare UI)
*Feature: environment: current value (possibly changed from initial value) is saved in .elf log file
*Feature: StandardLibrary: additional optional pins for encoding (e.g. #utf8) in "FileStream [ Open For xxxx ]" blocks
*Feature: Values that cannot be saved in a .elf log file (e.g. web elements) are now saved and restored as UnrestoreableDate instead of nil
*New Python Version: Delivered installation package for Python 3.11.6
*Change in the format of .elf log files to store handled error states. Older expecco versions cannot handle this and might have problems to open such a file.
*Bug Fix: log processor actions were themself added to the log, possibly leading to problems when executed again
*Bug Fix: time-limited actions with the ''timeLimitOK'' flag set did not trigger the enable output pin.
*Bug Fix: zip archive view generated wrong name-list if language setting was EN-US (AM/PM from timestamp was interpreted as part of filename)
*Bug Fix: unicode strings in environment variables could not be stored to CSV files
*Bug Fix: a cancelled compound action did write to an output pin in certain situations

== Release 23.1 ==
*Feature: Continue an interrupted test plan (i.e. even in a new expecco session and/or on another machine)
*Feature: Webtest (Selenium WebDriver): Support of [[Selenium_WebDriver_Plugin/en#Compound_Paths|compound paths]] for embedded elements.
*Feature: Webtest (Selenium WebDriver): [[Selenium_WebDriver_Plugin/en#Recorder|Recorder]] shows available windows and the current frame context.
*Feature: Webtest (Selenium WebDriver): Support of [[Selenium_WebDriver_Plugin/en#Shadow_Elements|shadow elements]] in the GUI browser and recorder, accessible by compound paths.
*Feature: Qt-Plugin supports Qt6 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Qt-Versions]])
*Feature: Expecco Remote Control & Monitoring Service with Web Front-End (App for Android or Apple IOS is available on request) ([[Expecco_Remote_Control_App/en|expecco Mobile Remote App]])
*Feature: Diagram Editor: default style for new connections (e.g. hidden)
*Feature: Diagram Editor: shortcut keys for environment-freeze and others
*Feature: Diagram Editor: connections can be named
*Feature: User defined menu operations: Activity-Log in case of an error
*Feature: Zip-Archive viewer/extractor/inspector in [[Attachment_Editor/en#Zip_Archive_Inspector | attachment editor]]
*Feature: ManualTest actions are now part of the base system; the extra plugin licence is only needed to import Excel test descriptions
*Feature: Logging with microsecond resolution timestamps now works in Windows (if enabled in the settings)
*Feature: Support XML report file fetching via the REST interface
*Feature: PCAN (USB Can-Bus Adapter) is now supported in 64-bit expecco
*Feature: Folders can pass Tags to new sub-elements (inherit)
*Feature: Menu entry to set Test Groups for Tree Elements
*Standard Library: Warning Dialog with Opt-out option (show only once)
*FMU/CBridge: [[Functional Mockup Interface | support FMI2 API; partial support for FMI3]]
*FMU/CBridge: download resources to CBridge (eg. unifmu generated python FMUs work)
*Fix: nth-root: lost precision when applied to higher than 64bit floats.
*Fix: LargeFloats rounding was broken
*Fix: WSDL import with namespace redefinitions
*New [[Mobile_Testing_Plugin/en#Windows|Mobile Testing Supplement]] for Windows with an option in the installer to add Appium to the Autostart.

Release Notes 23.x

2023-12-15T17:10:42Z

Matilk: /* Release 23.2 (upcoming) */

See also: [[Release Notes 22.x]]
 

== Release 23.2 (upcoming) ==
*Feature: [[Environment_Editor/en#Fields|Static (Step-) Variables]]
*Feature: DOM inspector (try an XML attachment) generates better xpath suggestions (alternatives in [[Attachment_Editor/en#XML_Inspector | attachment editor]])
*Feature: [[Testplan_Editor/en#Log_Processor_Action|log processors]] are now configurable both for individual test cases and for the overall result of a testplan
*Feature: [[Testplan_Editor/en#Log_Processor_Action|log processor]] activities are shown in a testplan's activity log (but not in a report)
*Feature: Qt-Library: New Action ''QButton::Click'': direct click, not being delegated to a thread
*Feature: Qt-Testing: ExpeccoTestService library and Inject-Tool for QT5.15.0 and VS2022: [[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]]
*Feature: [[Timeline/en|Timeline view]] for the activity log
*Feature: more [[Testplan_Editor/en#Execution_Settings | pathname options]] for testplan when generating ELF-per-run result files (in loops)
*Feature: a new [[Testplan_Editor/en#Execution_Settings | option]] in testplan to skip successful tests when looping
*Feature: enhanced manual test wizard with the option to execute the manual tests with a mobile device (Android, Apple IOS or Web-Browser)
*Feature: [[Expecco_API/en#Bridged_Ruby_Elementary_Blocks |bridged Ruby elementary actions]]
*Feature: Improvements in the XML inspector (tree popup menu & string search)
*Feature: [[Expecco_API/en#Bridged_Python_Elementary_Blocks |bridged Python elementary actions]] can now be cancelled and terminated
*Feature: improved [[Tools_TestSuiteDifferenceBrowser|difference viewer]] (project and version compare UI)
*Feature: environment: current value (possibly changed from initial value) is saved in .elf log file
*Feature: StandardLibrary: additional optional pins for encoding (e.g. #utf8) in "FileStream [ Open For xxxx ]" blocks
*Feature: Values that cannot be saved in a .elf log file (e.g. web elements) are now saved and restored as UnrestoreableDate instead of nil
*New Python Version: Delivered installation package for Python 3.11.6
*Change in the format of .elf log files to store handled error states. Older expecco versions cannot handle this and might have problems to open such a file.
*Bug Fix: log processor actions were themself added to the log, possibly leading to problems when executed again
*Bug Fix: time-limited actions with the ''timeLimitOK'' flag set did not trigger the enable output pin.
*Bug Fix: zip archive view generated wrong name-list if language setting was EN-US (AM/PM from timestamp was interpreted as part of filename)
*Bug Fix: unicode strings in environment variables could not be stored to CSV files
*Bug Fix: a cancelled compound action did write to an output pin in certain situations

== Release 23.1 ==
*Feature: Continue an interrupted test plan (i.e. even in a new expecco session and/or on another machine)
*Feature: Webtest (Selenium WebDriver): Support of [[Selenium_WebDriver_Plugin/en#Compound_Paths|compound paths]] for embedded elements.
*Feature: Webtest (Selenium WebDriver): [[Selenium_WebDriver_Plugin/en#Recorder|Recorder]] shows available windows and the current frame context.
*Feature: Webtest (Selenium WebDriver): Support of [[Selenium_WebDriver_Plugin/en#Shadow_Elements|shadow elements]] in the GUI browser and recorder, accessible by compound paths.
*Feature: Qt-Plugin supports Qt6 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Qt-Versions]])
*Feature: Expecco Remote Control & Monitoring Service with Web Front-End (App for Android or Apple IOS is available on request) ([[Expecco_Remote_Control_App/en|expecco Mobile Remote App]])
*Feature: Diagram Editor: default style for new connections (e.g. hidden)
*Feature: Diagram Editor: shortcut keys for environment-freeze and others
*Feature: Diagram Editor: connections can be named
*Feature: User defined menu operations: Activity-Log in case of an error
*Feature: Zip-Archive viewer/extractor/inspector in [[Attachment_Editor/en#Zip_Archive_Inspector | attachment editor]]
*Feature: ManualTest actions are now part of the base system; the extra plugin licence is only needed to import Excel test descriptions
*Feature: Logging with microsecond resolution timestamps now works in Windows (if enabled in the settings)
*Feature: Support XML report file fetching via the REST interface
*Feature: PCAN (USB Can-Bus Adapter) is now supported in 64-bit expecco
*Feature: Folders can pass Tags to new sub-elements (inherit)
*Feature: Menu entry to set Test Groups for Tree Elements
*Standard Library: Warning Dialog with Opt-out option (show only once)
*FMU/CBridge: [[Functional Mockup Interface | support FMI2 API; partial support for FMI3]]
*FMU/CBridge: download resources to CBridge (eg. unifmu generated python FMUs work)
*Fix: nth-root: lost precision when applied to higher than 64bit floats.
*Fix: LargeFloats rounding was broken
*Fix: WSDL import with namespace redefinitions
*New [[Mobile_Testing_Plugin/en#Windows|Mobile Testing Supplement]] for Windows with an option in the installer to add Appium to the Autostart.

Release Notes 23.x

2023-12-14T13:57:18Z

Matilk: /* Release 23.2 (upcoming) */

See also: [[Release Notes 22.x]]
 

== Release 23.2 (upcoming) ==
*Feature: [[Environment_Editor/en#Fields|Static (Step-) Variables]]
*Feature: DOM inspector (try an XML attachment) generates better xpath suggestions (alternatives in [[Attachment_Editor/en#XML_Inspector | attachment editor]])
*Feature: [[Testplan_Editor/en#Log_Processor_Action|log processors]] are now configurable both for individual test cases and for the overall result of a testplan
*Feature: [[Testplan_Editor/en#Log_Processor_Action|log processor]] activities are shown in a testplan's activity log (but not in a report)
*Feature: Qt-Library: New Action ''QButton::Click'': direct click, not being delegated to a thread
*Feature: Qt-Testing: ExpeccoTestService library and Inject-Tool for QT5.15.0 and VS2022: [[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Delivered versions for QT and build environment]]
*Feature: [[Timeline/en|Timeline view]] for the activity log
*Feature: more [[Testplan_Editor/en#Execution_Settings | pathname options]] for testplan when generating ELF-per-run result files (in loops)
*Feature: a new [[Testplan_Editor/en#Execution_Settings | option]] in testplan to skip successful tests when looping
*Feature: enhanced manual test wizard with the option to execute the manual tests with a mobile device (Android, Apple IOS or Web-Browser)
*Feature: [[Expecco_API/en#Bridged_Ruby_Elementary_Blocks |bridged Ruby elementary actions]]
*Feature: Improvements in the XML inspector (tree popup menu & string search)
*Feature: [[Expecco_API/en#Bridged_Python_Elementary_Blocks |bridged Python elementary actions]] can now be cancelled and terminated
*Feature: improved [[Tools_TestSuiteDifferenceBrowser|difference viewer]] (project and version compare UI)
*Feature: environment: current value (possibly changed from initial value) is saved in .elf log file
*Feature: StandardLibrary: additional optional pins for encoding (e.g. #utf8) in "FileStream [ Open For xxxx ]" blocks
*Feature: Values that cannot be saved in a .elf log file (e.g. web elements) are now saved and restored as UnrestoreableDate instead of nil
*New Python Version: Delivered installation package for Python 3.11.6
*Bug Fix: log processor actions were themself added to the log, possibly leading to problems when executed again
*Bug Fix: time-limited actions with the ''timeLimitOK'' flag set did not trigger the enable output pin.
*Bug Fix: zip archive view generated wrong name-list if language setting was EN-US (AM/PM from timestamp was interpreted as part of filename)
*Bug Fix: unicode strings in environment variables could not be stored to CSV files
*Bug Fix: a cancelled compound action did write to an output pin in certain situations

== Release 23.1 ==
*Feature: Continue an interrupted test plan (i.e. even in a new expecco session and/or on another machine)
*Feature: Webtest (Selenium WebDriver): Support of [[Selenium_WebDriver_Plugin/en#Compound_Paths|compound paths]] for embedded elements.
*Feature: Webtest (Selenium WebDriver): [[Selenium_WebDriver_Plugin/en#Recorder|Recorder]] shows available windows and the current frame context.
*Feature: Webtest (Selenium WebDriver): Support of [[Selenium_WebDriver_Plugin/en#Shadow_Elements|shadow elements]] in the GUI browser and recorder, accessible by compound paths.
*Feature: Qt-Plugin supports Qt6 ([[QT_Testing/en#ExpeccoTestService_Library%3A_Delivery_in_Expecco_Versions|Qt-Versions]])
*Feature: Expecco Remote Control & Monitoring Service with Web Front-End (App for Android or Apple IOS is available on request) ([[Expecco_Remote_Control_App/en|expecco Mobile Remote App]])
*Feature: Diagram Editor: default style for new connections (e.g. hidden)
*Feature: Diagram Editor: shortcut keys for environment-freeze and others
*Feature: Diagram Editor: connections can be named
*Feature: User defined menu operations: Activity-Log in case of an error
*Feature: Zip-Archive viewer/extractor/inspector in [[Attachment_Editor/en#Zip_Archive_Inspector | attachment editor]]
*Feature: ManualTest actions are now part of the base system; the extra plugin licence is only needed to import Excel test descriptions
*Feature: Logging with microsecond resolution timestamps now works in Windows (if enabled in the settings)
*Feature: Support XML report file fetching via the REST interface
*Feature: PCAN (USB Can-Bus Adapter) is now supported in 64-bit expecco
*Feature: Folders can pass Tags to new sub-elements (inherit)
*Feature: Menu entry to set Test Groups for Tree Elements
*Standard Library: Warning Dialog with Opt-out option (show only once)
*FMU/CBridge: [[Functional Mockup Interface | support FMI2 API; partial support for FMI3]]
*FMU/CBridge: download resources to CBridge (eg. unifmu generated python FMUs work)
*Fix: nth-root: lost precision when applied to higher than 64bit floats.
*Fix: LargeFloats rounding was broken
*Fix: WSDL import with namespace redefinitions
*New [[Mobile_Testing_Plugin/en#Windows|Mobile Testing Supplement]] for Windows with an option in the installer to add Appium to the Autostart.

Mobile Testing Plugin

2023-11-30T14:55:59Z

Matilk: /* WebDriverAgent-Signierung */

'''Deutsche Version''' | [[Mobile_Testing_Plugin/en|English Version]]

= Einleitung =
Mit dem ''Mobile Testing Plugin'' können Anwendungen auf Android- und iOS-Geräten getestet werden. Dabei ist es egal, ob reale mobile Endgeräte oder emulierte Geräte verwendet werden. Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests unterstützt. Zudem ist damit das Aufzeichnen von Testabläufen möglich.

Zur Verbindung mit den Geräten wird [http://appium.io/ Appium] verwendet. Appium ist ein freies Open-Source-Framework zum Testen und Automatisieren von mobilen Anwendungen.

Zur Einarbeitung in das Mobile Plugin empfehlen wir das [[Mobile_Testing_Tutorial|Tutorial]] zu bearbeiten. Dieses führt anhand eines Beispiels Schritt für Schritt durch die Erstellung eines Testfalls und erklärt die nötigen Grundlagen.

= Installation und Aufbau =
Zur Verwendung des Mobile Testing Plugins müssen Sie expecco inkl. des Plugins Mobile Testing installiert haben und Sie benötigen die entsprechenden Lizenzen. expecco kommuniziert mit den Mobilgeräten über einen Appium-Server, der entweder auf demselben Rechner wie expecco läuft, oder auf einem zweiten Rechner. Dieser muss für expecco erreichbar sein.

==Installationsübersicht==

'''Rechner, auf dem expecco läuft:'''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem Android-Geräte angeschlossen sind:'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Android SDK'', dieses erhalten Sie ebenfalls mit dem Mobile Testing Supplement''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem iOS-Geräte angeschlossen sind2):'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement für Mac OS installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Xcode ''in einer Version, die die verwendete iOS-Version unterstützt, erhältlich über den Apple App Store''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
* Apple-Entwickler-Zertifikat mit zugehörigem privaten Schlüssel ''(zum Signieren des WebDriverAgents)''
* Provisioning Profile mit den verwendeten Mobilgeräten

Je nach Aufbau können die oben genannten Rechner auch das selbe Gerät sein. expecco kann sich sowohl über das Netzwerk mit einem entfernten Appium-Server und dort angeschlossenen Mobilgeräten verbinden, als auch lokal selbst einen Appium-Server starten und diesen mit lokalen Mobilgeräten verwenden. Einige Funktionen von expecco, die die Erstellung von Testfällen erleichtern, sind jedoch nur verfügbar, wenn die Mobilgeräte am selben Rechner angeschlossen sind, auf dem auch expecco läuft. Ein möglicher Aufbau kann daher wie in folgender Abbildung aussehen:

[[Datei:MobileTestingAufbau.png | 400px]]

Im Folgenden wird die Installation von Appium und anderer nötiger Programme für Windows und Mac OS erklärt.

1): Zum Zeitpunkt der Erstellung dieses Dokuments wurden Versionen bis 11 auf Funktion verifiziert. Neuere Versionen sollten - sofern nicht grundlegende Änderungen von Oracle vorgenommen wurden, ebenfalls funktionieren.

2): Beachten Sie, dass aufgrund der Voraussetzungen (keine Anbindung an nicht-Apple Geräte verfügbar) iOS-Geräte nur von einem Mac aus angesteuert werden können. Sie benötigen also einen Mac als "Vermittler" (siehe auch unten: [[#Ich habe keinen Mac | "Ich habe keinen Mac"]])

== Windows ==
Am einfachsten installieren Sie alles mit unserem Mobile Testing Supplement1. In neueren Versionen ist allerdings aufgrund geänderter Lizenzbedingungen seitens Oracle kein JDK mehr enthalten, sodass sie dieses zusätzlich installieren müssen. Sie können natürlich Appium auch direkt installieren, um die Version zu verwenden, die Sie möchten. Um dann einen Appium-Server mit expecco starten zu können, muss allerdings eine entsprechende Batchdatei vorhanden sein und in den [[Mobile_Testing_Plugin#Konfiguration_des_Plugins|Einstellungen]] angegeben werden. Verbindungen können aber auch zu anderen laufenden Appium-Servern aufgebaut werden.
*'''expecco 23.1''': [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Gleiche Versionen wie der Vorgänger, aber der Installer erlaubt nun, Appium zum Autostart hinzuzufügen.
*expecco 22.2 und 22.1: [https://download.exept.de/transfer/h-expecco-22.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 aus platform-tools 33.0.2
:''* Wir haben Appium um die Capability'' startChromedriverTimeout ''erweitert, um schneller einen Timeout zu bekommen, wenn der Chromedriver nicht gestartet werden kann. (siehe [[#startChromedriverTimeout|Probleme und Lösungen]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Enthält die Appium-Version 1.22.0, Node ist weiterhin in der Version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Nur kleine Änderungen im Vergleich zur vorigen Version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und node 12 verwendet.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:Dieses installiert Appium in der Version 1.12.0 und enthält nun zusätzlich build-tools der Version 28.0.3 im android-sdk. Ansonsten ist es gleich wie die vorige Version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:Dieses installiert Appium in der Version 1.8.1. Außerdem bietet das Supplement auch an, ''Android Debug Bridge'' und ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) zu installieren. Damit sind Treiber für ein breites Spektrum an Android-Geräten abgedeckt, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen. Ein '''JDK ist (aufgrund geänderter Lizenzbedingungen seitens Oracle) nicht mehr enthalten''', dieses müssen Sie selbst herunterladen, z.B. von [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: wie expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.6.4. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.4.16. Während der Installation wird die grafische Oberfläche von Appium gestartet, dieses Fenster können Sie sofort wieder schließen. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.

Wenn expecco Mobilgeräte verwenden soll, die an einem anderen Rechner angeschlossen sind, müssen Sie dort einen Appium-Server starten. Dies können Sie mit der Datei <code>appium_standalone.cmd</code> tun. Der Server wird dann mit dem Standard-Port 4723 gestartet. Falls Sie eine andere Portnummer verwenden wollen, starten Sie den Server mit

appium_standalone.cmd -p <portnummer>

Der Server ist bereit, sobald die Zeile
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
angezeigt wird, wobei Sie am Ende die verwendete Portnummer ablesen können.

Beim ersten Starten von Appium – sowohl im Standalone als auch gestartet von expecco – kann es vorkommen, dass die Windows-Firewall den Node-Server blockiert. Lassen Sie den Zugriff zu, sonst kann Appium nicht gestartet werden.

1) Sie können natürlich auch die Command Line Tools (adb, sdkmanager, avdmanager etc.) einer vorhandenen Android Studio Version verwenden, sowie Appium separat installieren.
Da sich diese Tools regelmäßig ändern, und es in der Vergangenheit zu Inkompatibilitäten und Fehlern nach Releasewechseln kam, empfehlen wir zu Beginn, das mitgelieferte Paket zu verwenden. Dies ist möglicherweise nicht das aktuellste, wurde aber auf Lauffähigkeit getestet.

Falls das Android Mobilgerät an einem entfernen Rechner angeschlossen ist,
können Sie den aktuellen Bildschirminhalt z.B. mit dem [https://github.com/Genymobile/scrcpy scrcpy] tool live mitverfolgen.

== Mac OS (nicht erforderlich für Android-Tests)==
Hinweis: Wenn Sie nicht vorhaben, iOS-Geräte (iPhone, iPad, etc.) zu testen, können Sie das Folgende ignorieren. '''Der Apple-Rechner sowie das Mac-Setup werden für Android-Geräte nicht benötigt'''.

=== Xcode ===
Zur Automatisierung mit iOS-Geräten wird [https://developer.apple.com/xcode/ Xcode] benötigt. Sie erhalten dieses über den App Store. Dabei ist darauf zu achten, dass die Version zu den getesteten iOS-Versionen passt.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
Diese Tabelle gibt nur eine vereinfachte Übersicht, lesen Sie besser unter [https://xcodereleases.com/ Xcode Releases] oder [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode-Versionen] welche Version Sie brauchen. Für neue iOS Minor-Versionen gibt es in der Regel auch ein Update für Xcode, z.B. brauchen Sie für iOS 10.2 mindestens Xcode 8.2, für iOS 10.3 mindestens Xcode 8.3 usw.
Wenn Sie also auf eine neuere iOS-Version wechseln, benötigen Sie in der Regel auch eine neuere Xcode-Version. Neuere Versionen von Xcode laufen möglicherweise nicht auf älteren Betriebssystemen, was wiederum eine Aktualisierung des Betriebssystems erforderlich machen kann. Falls Sie auch ältere iOS-Versionen testen wollen kann es sinnvoll sein, die entsprechenden Xcode-Versionen parallel zu installieren.

=== Appium ===
Der Appium-Server kann entweder als Kommandozeilen-Anwendung installiert werden oder über [https://github.com/appium/appium-desktop Appium Desktop] verwendet werden, welcher den Server über ein GUI zur Verfügung stellt. Mittlerweile gibt es auch Appium 2.0, was wir aber bisher noch nicht mit expecco getestet haben und daher nicht empfehlen.

==== Appium Desktop ====
Laden Sie die neueste Version von [https://github.com/appium/appium-desktop/releases/ Appium Desktop] herunter. Für den Mac nehmen Sie am besten die dmg-Datei und installieren sie in den Anwendungen. Beim Starten der Anwendung ''Appium Server GUI'' erhalten Sie wahrscheinlich eine Fehlermeldung, dass es aus Sicherheitsgründen nicht möglich ist. Öffnen Sie dann das Kontextmenü auf der Anwendungsdatei (Rechtsklick bzw. Strg + Klick) und wählen Sie dort ''Öffnen'' aus. Bestätigen Sie dann, dass Sie die Anwendung wirklich öffnen wollen. Fortan können Sie die Anwendung normal öffnen.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Ab Xcode 14 gibt es Probleme beim Signieren des WebDriverAgents, den Appium zur Automatisierung auf das Gerät spielt. Dadurch ist mit der Version 1.22.3-4 von Appium Desktop kein Verbindungsaufbau möglich. Das Problem ist in neueren Versionen des WebDriverAgents behoben, es gibt aber aktuell noch keine Version von Appium Desktop, die eine solche Version enthält (Stand November 2022). Sie können aber manuell eine neue Version herunterladen (z.B. 4.10.2) und die Dateien in Appium ersetzen. Laden Sie dazu von der [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent Download-Seite] eine der beiden Archivdateien (zip oder tar.gz) mit dem Source Code herunter. Öffnen und entpacken Sie dann diese Datei. Den Inhalt des Ordners WebDriverAgent-4.10.2 müssen Sie nun nach

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

kopieren. Wenn Sie über den Finder dorthin navigieren, machen Sie auf die Anwendung ''Appium Server GUI'' einen Kontextklick (Rechtsklick bzw. Strg + Klick) und wählen Sie im Menü ''Paketinhalt anzeigen''. Ersetzen Sie alle Dateien, die bereits mit gleichem Namen enthalten sind.

==== Appium über npm installieren ====
Sie können Appium auch über npm (Node Package Manager) installieren. Dazu müsen Sie erst node/npm installieren. Das geht mit [https://github.com/nvm-sh/nvm nvm] (Node Version Manager) was Sie von Github bekommen. Falls die folgende Installationsanleitung bei Ihnen nicht funktionieren sollte, finden Sie dort ausführlichere Informationen im [https://github.com/nvm-sh/nvm#readme Readme].

Öffnen Sie ein Terminal-Fenster. Klonen Sie dann das Github-Repository von nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
und laden Sie es
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Führen Sie danach
command -v nvm
aus, um zu testen, ob es funktioniert hat. Es sollte ''nvm'' ausgegeben werden. Kommt keine Antwort, führen Sie
touch ~/.zshrc
aus, und versuchen Sie es erneut.

Nun können Sie node mit dem folgenden Befehl installieren.
nvm install 16.15.1
Da es mit der aktuellen Version von node Probleme beim Installieren von Appium gibt, empfehlen wir diese Version.

Nachdem node installiert ist, können Sie Appium darüber installieren:
npm install -g appium

Den Appium-Server können Sie nun einfach über den Befehl
appium
starten. Die Ausgabe erfolgt dann direkt im Terminal.

Auch bei dieser Version gibt es das Problem bei der Signierung des WebDriverAgents, wie bei [[#Appium_Desktop | Appium Desktop]] beschrieben. Laden Sie also auch in diesem Fall eine neuere Version des WebDriverAgents herunter und ersetzen Sie die alten Dateien. Diese finden Sie unter
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
Ältere Appium-Versionen stellen wir Ihnen über das Mobile Testing Supplement für Mac OS zur Verfügung, mit dem Sie es einfach installieren können:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.2)]
:Enthält Appium Version 1.18.3 und verwendet node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.0)]
:Nur wenige Änderungen im Vergleich zur vorigen Version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.98)]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und es wird node 12 verwendet.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.96)]
:Diese Version enthält Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.94)]
:Diese Version enthält Appium 1.8.0.

* expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.0.94)]
:Diese Version enthält Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement für Mac OS]
:Diese Version entält Appium 1.4.16.

Nachdem Herunterladen des Supplements, können Sie es in ein Verzeichnis Ihrer Wahl (z. B. Ihr Home-Verzeichnis) verschieben und dort entpacken. Ein geeigneter Befehl in einer Shell könnte wie folgt aussehen, passen Sie dabei die Versionsnummer entsprechend an:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

Wenn Sie Ihre Standard-Xcode-Installation verwenden wollen, können Sie Appium direkt über die Datei im ''bin''-Verzeichnis mit der entsprechenden Versionsnummer starten:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Falls Sie ein anderes Xcode als das als Standard konfigurierte verwenden wollen, müssen Sie Appium den entsprechenden Pfad über die Umgebungsvariable ''DEVELOPER_DIR'' angeben.
Wenn Sie Xcode z. B. in ''/Applications/Xcode-11.3.app'' installiert haben, müssten Sie Appium so starten:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Was als Standard-Xcode-Installation gesetzt ist, zeigt der Befehl:

xcode-select -p

Wenn Appium Ihre Xcode-Installation nicht findet, erscheint beim Verbinden eine Fehlermeldung in der Art:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
Starten Sie in diesem Fall Appium erneut, unter Angabe eines gültigen ''DEVELOPER_DIR''.

==== WebDriverAgent-Signierung ====
Zur Automatisierung lädt Appium eine App namens WebDriverAgent auf das Gerät und muss sie dafür signieren können. Dazu brauchen Sie einen Apple-Account und ein entsprechendes Zertifikat. Zur Evaluierung können Sie einen kostenlosen Account verwenden. Dieser hat den Nachteil, dass erstellte Profile nur eine Woche gültig sind und danach neu erstellt werden müssen. Seien Sie auch vorsichtig, wenn Sie sich den Account teilen, da es vorkommen kann, dass Zertifikate widerrufen werden oder durch automatische Generierung ungültig werden. Als Folge können bereits signierte Apps nicht mehr verwendet werden.

Wenn Sie bereits ein entsprechendes Zertifikat mit dem zugehörigen privaten Schlüssel in Ihrer [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac haben, können Sie den WebDriverAgent automatisch signieren lassen. Ansonsten empfiehlt es sich, die Signierung über Xcode einzustellen und zu verwalten.

Schließen Sie zuerst das Gerät, das Sie verwenden möchten, über USB an den Mac an. Stellen Sie sicher, dass sich der Mac und das Gerät im selben Netzwerk befinden, ansonsten kann es beim Verbindungsaufbau mit Appium zu Problemen kommen. Starten Sie Xcode und öffnen Sie ''Preferences''. Wechseln Sie zur Seite der Accounts und legen Sie einen Eintrag mit Ihrem Account an. Anschließend können Sie auf ''Manage Certificates...'' klicken, um die Zertifikate zu sehen, die zu diesem Account gehören. Zum Ausführen von Tests benötigen Sie ein iOS-Development-Zertifikat und den dazugehörigen privaten Schlüssel. Wenn Sie noch keines besitzen, erstellen Sie eines. Wenn Sie bereits eines haben, aber es nicht in Ihrem Schlüsselbund vorhanden ist (erkennbar an dem Hinweis "Not in Keychain"), können Sie es importieren. Das können Sie über die [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac machen, wenn Sie es zuvor aus dem Schlüsselbund exportiert haben, in dem es sich befindet. Das Zertifikat mit dem zugehörigen Schlüssel sollte sich im Schlüsselbund ''Anmeldung'' befinden. Dort kann es als PKCS#12-Datei (Endung typischerweise .p12) exportiert werden. Um ein Zertifikat in Ihren Schlüsselbund zu importieren, wählen Sie im Menü ''Ablage'' die Option ''Objekte importieren''. Falls Sie nicht wissen, wo das Zertifikat gespeichert ist, können Sie es in Xcode auch widerrufen und in Ihrem Schlüsselbund neu anlegen. Machen Sie das jedoch nur, wenn Sie wissen, dass das alte Zertifikat nicht mehr in Verwendung ist, da es danach nicht mehr benutzt werden kann. Nun sollte Ihr Schlüsselbund ein iOS-Development-Zertifikat enthalten.


Öffnen Sie nun das WebDriverAgent-Projekt in Xcode. Wenn Sie das Mobile Testing Supplement installiert haben, finden Sie es in dessen Verzeichnis unter
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
Wenn Sie Appium Desktop installier haben, finden Sie es unter
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''
Sie können einfach im Finder zu der Xcode-Project-Datei navigieren und Sie über einen Doppelklick öffnen. Beachten Sie dabei, dass Sie dabei auf die Anwendung Appium Server GUI einen Kontextklick (Rechtsklick bzw. Strg + Klick) machen und im Menü ''Paketinhalt anzeigen'' auswählen müssen, um in deren Unterverzeichnis zu gelangen.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Wählen Sie ''WebDriverAgentLib'' und die Seite ''Signing & Capabilities'' aus. Setzen Sie dort im Abschnitt ''Signing'' die Option ''Automatically manage signing'' und wählen Sie dann ein Team aus. Wechseln Sie nun zu ''WebDriverAgentRunner'' und tun Sie dort dasselbe.

Durch das Setzen des Teams sollten die Fehler für den WebDriverAgentRunner verschwinden. Sollte Xcode kein passendes Provisioning Profile für die Bundle ID ''com.facebook.WebDriverAgentRunner'' erstellen können, können Sie diese anpassen, dass sie zu Ihrem Zertifikat passt. Danach können Sie Xcode beenden oder auch, wie weiter unten beschrieben, direkt den Build über Xcode starten, damit das Projekt bereits gebaut ist, wenn Appium es verwenden möchte.

Wenn Sie sich nun von expecco eine Verbindung zu Ihrem Gerät aufbauen, wird der WebDriverAgent darauf installiert und gestartet, um anschließend zur zu testenden App zu wechseln. Eventuell muss auf dem Gerät muss der Ausführung des WebDriverAgents vertraut noch werden. Ein Anzeichnen dafür kann sein, dass die App WebDriverAgent zwar auf dem Gerät erscheint und zu starten versucht, danach aber wieder deinstalliert wird. Öffnen Sie dazu während des Verbindungsaufbaus auf dem Gerät in die Einstellungen und dort unter ''Allgemein'' den Eintrag ''Geräteverwaltung''. Dieser Eintrag ist nur sichtbar, wenn eine Entwickler-App auf dem Gerät installiert ist. Sie müssen daher möglicherweise warten, bis der WebDriverAgent installiert ist, bevor der Eintrag erscheint. Wählen Sie dort den Eintrag Ihres Apple-Accounts und vertrauen Sie ihm. Da der WebDriverAgent wieder deinstalliert wird, wenn der Start nicht funktioniert hat, müssen Sie dies während des Verbindungsaufbaus tun. Falls Ihnen das zu hektisch ist, können Sie auch folgenden Code ausführen:

<nowiki>xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test</nowiki>
bzw.
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

Damit wird der WebDriverAgent auf dem Gerät installiert ohne dass er wieder gelöscht wird.

Wenn es Probleme beim Installieren des WebDriverAgents gibt, können Sie auch versuchen, den Build über Xcode zu starten. Stellen Sie sicher, dass das richtige Target ''WebDriverAgent'' ausgewählt ist. Fehlermeldungen in Xcode zeigen vielleicht einfacher, wo das Problem liegt. Manchmal hilft es auch, es ein zweites Mal zu versuchen, weil es möglicherweise beim ersten Mal zu lange gedauert hat und abgebrochen wurde. Es kann sein, dass Sie während des Builds mehrmals aufgefordert werden, das Passwort für Ihren Schlüsselbund anzugeben.

[[Datei:WebDriverAgentCodesign.png]]

Lesen Sie auch die Dokumentation von Appium zum [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Aufsetzen von Tests mit iOS-Geräten]. In der [https://support.apple.com/en-us/HT204460 Dokumentation von Apple] finden Sie nähere Informationen zum Installieren und Vertrauen von Apps.

Ist der WebDriverAgent einmal auf dem Gerät installiert, wird er für spätere Verbindungen wieder verwendet und der Verbindungsaufbau sollte schneller funktionieren. Ebenso liegt dann die signierte Version bereits auf Ihrem Mac und muss nicht erneut gebaut werden, was die Verbindung zu weiteren Geräten ebenfalls beschleunigt. Wenn Sie wissen, dass bei Ihrem Verbindungsaufbau der WebDriverAgent erst noch signiert und gebaut werden muss, ist es ratsam, die Capability ''wdaLaunchTimeout'' zu setzen. Dieser Timeout, wie lange auf den Start der WebDriverAgents auf dem Gerät gewartet werden soll, liegt standardmäßig bei 60000$nbsp;ms. Der Build dauert aber häufig über eine Minute, sodass der Versuch zum Verbindungsaufbau dann abgebrochen wird. Ein Wert von 120000 hat sich hier als besser erwiesen.

== Konfiguration des Plugins ==
Bevor Sie loslegen, sollten Sie die Einstellungen des Mobile Testing Plugins überprüfen und ggf. anpassen.

Öffnen Sie im Menü den Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" den Eintrag "''Mobile Testing''" (s. Abb.). Standardmäßig werden diese Pfade automatisch gefunden (1). Um einen Pfad manuell anzupassen, deaktivieren Sie den entsprechenden Haken rechts davon. Sie erhalten in einer Drop-down-Liste einige Pfade zur Auswahl. Ist ein eingetragener Pfad falsch oder kann er nicht gefunden werden, wird das Feld rot markiert und es erscheint ein diesbezüglicher Hinweis. Stellen Sie sicher, dass alle Pfade richtig angegeben sind.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Konfiguration des Plugins]]

*'''appium''': Geben Sie hier den Pfad zur ausführbaren Datei an mit der Appium in der Kommandozeile gestartet werden kann. Unter Windows wird diese Datei in der Regel "<code>appium.cmd</code>" heißen. Dieser Pfad wird benutzt, wenn expecco einen Appium-Server startet.
*'''node''': Geben Sie hier den Pfad zur ausführbaren Datei an, die Node (auch "Node.js") startet. Dieser Pfad wird beim Starten eines Servers an Appium weitergegeben, damit Appium ihn unabhängig von der PATH-Variablen findet. Unter Windows heißt diese Datei in der Regel "<code>node.exe</code>".
*'''JAVA_HOME''': Geben Sie hier den Pfad zu einem JDK an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden. Um einzustellen, welches Java von expecco verwendet werden soll, setzen Sie diesen Pfad in den Einstellungen für die Java Bridge.
*'''ANDROID_HOME''': Geben Sie hier den Pfad zu einem SDK von Android an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden.
*'''adb''': Hier steht der Pfad zum adb-Befehl. Unter Windows heißt die Datei adb.exe. Diese wird von expecco beispielsweise verwendet, um die Liste der angeschlossenen Geräte zu erhalten. Diesen Pfad sollten Sie automatisch wählen lassen, da dann der Befehl im ANDROID_HOME-Verzeichnis verwendet wird. Dieser wird auch von Appium verwendet. Falls expecco und Appium jedoch verschiedene Versionen von adb verwenden kann es zu Konflikten kommen.
*'''android.bat''': Diese Datei wird nur benötigt, um damit den AVD und den SDK Manager zu starten. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.
*'''aapt''': Geben Sie hier den Pfad zum aapt-Befehl an. Unter Windows heißt diese Datei ''aapt.exe''. expecco verwendet aapt nur im Verbindungseditor, um das Paket und die Activities einer apk-Datei zu lesen. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | Konfiguration des JDKs]]

Ab expecco 2.11 gibt es das Feld ''Team-ID''. Wenn Sie iOS-Tests ausführen, tragen Sie hier die Team-ID Ihres Zertifikats ein. Diese wird für jede iOS-Verbindung verwendet, außer Sie setzen den Wert im Einzelfall in den Verbindungseinstellungen um. Wie Sie die Team-ID erhalten, lesen Sie im Abschnitt zur [[#Signierung|Signierung]] ber der Installation auf Mac OS. Mit expecco 2.10 können Sie die Team-ID nur für jede Verbindungseinstellung extra als Capability eintragen. Dazu müssen Sie jedoch die [[#Erweiterte_Ansicht|erweiterte Ansicht]] verwenden. Geben Sie hier die Capability ''xcodeOrgId'' an und setzen Sie als Wert die Team-ID des Zertifikats.

Die Einstellung zur Serveradresse unten auf der Seite bezieht sich auf das Verhalten des Verbindungseditors. Dieser prüft am Ende, ob die Serveradresse auf ''/wd/hub'' endet, da dies die übliche Form ist. Falls nicht, wird in einem Dialog gefragt, wie darauf reagiert werden soll. Das festgelegte Verhalten kann hier eingesehen und verändert werden.

Wechseln Sie ebenfalls zum Eintrag ''Java Bridge'' (s. Abb.). Hier muss der Pfad zu Ihrer Java-Installation angegeben werden, die von expecco benutzt wird. Tragen Sie hier ein JDK ein. Falls Sie unter Windows das aus dem Mobile Testing Supplement verwenden möchten, lautet der Pfad
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
Sie können auch die Systemeinstellungen verwenden.

== Android-Gerät vorbereiten ==
Wenn Sie ein Android-Gerät unter Windows anschließen benötigen Sie möglicherweise noch einen adb-Treiber für das Gerät. Einen passenden Treiber finden Sie üblicherweise auf der jeweiligen Webseite des Herstellers. Haben Sie den Universal-Treiber aus dem Mobile Testing Supplement installiert, sollte für die meisten Geräte bereits alles funktionieren. In einigen Fällen versucht auch Windows automatisch einen Treiber zu installieren, wenn Sie das Gerät zum ersten mal anschließen.
 
===USB-Debugging Einschalten===
'''Achtung:'''
Bevor Sie ein Mobilgerät mit dem Appium-Plugin ansteuern können, müssen Sie für dieses Debugging erlauben!

Für Android-Geräte finden Sie diese Option in den Einstellungen unter ''[https://www.droidwiki.org/wiki/Entwickleroptionen Entwickleroptionen]'' mit dem Namen ''[https://www.droidwiki.org/USB-Debugging USB-Debugging]''. Falls die Entwickleroptionen nicht angezeigt werden, können Sie diese freischalten, indem Sie unter "''Über das Telefon''" siebenmal auf "''Build-Nummer''" tippen.

===Wach bleiben Aktivieren===
Aktivieren Sie auch die Funktion ''Wach bleiben'', damit das Gerät nicht während der Testerstellung oder -ausführung den Bildschirm abschaltet.

Aus Sicherheitsgründen muss USB-Debugging für jeden Computer einzeln zugelassen werden. Beim Verbinden des Geräts mit dem PC über USB müssen Sie dabei am Gerät der Verbindung zustimmen. Falls Sie dies für Ihren Computer noch nicht getan haben, aber auf dem Gerät kein entsprechender Dialog erscheint, kann es helfen, das Gerät aus- und wieder einzustecken. Das kann insbesondere dann passieren, wenn Sie den ADB-Treiber installiert haben während das Gerät bereits über USB angeschlossen war. Falls auch das nicht hilft, öffnen Sie die Benachrichtigungen, indem Sie sie vom oberen Bildschirmrand herunter ziehen. Dort finden Sie die USB-Verbindung und Sie können die Optionen dazu öffnen. Wählen Sie einen anderen Verbindungstypen aus; in der Regel sollten MTP oder PTP funktionieren.

Sie können auch auf einem Emulator testen. Dieser muss nicht gesondert vorbereitet werden, da er bereits für USB-Debugging ausgelegt ist. Es ist sogar möglich, einen Emulator bei Testbeginn zu starten.

Um zu überprüfen, ob ein Gerät, das Sie an Ihren Rechner angeschlossen haben, verwendet werden kann, öffnen Sie den [[#Verbindungseditor|Verbindungseditor]]. Das Gerät sollte dort angezeigt werden.

=== Verbindung über WLAN ===
Es ist auch möglich, Android-Geräte über WLAN zu verbinden. Für Geräte mit Android 11 oder neuer ist dies direkt über WLAN möglich, im anderen Fall müssen Sie das Gerät zuerst über USB verbinden. Ab expecco 22.1 können Sie eine WLAN-Verbindung über den [[Mobile Testing Plugin#Verbindungseditor|Verbindungseditor]] aufbauen. Ansonsten ist es auch über die Eingabeaufforderung möglich.
==== Drahtlos verbinden über die Eingabeaufforderung mit expecco Versionen vor 22.1 (ab Android 11) ====
Mit expecco ab Version 22.1 funktioniert das einfacher über den Verbindungseditor.

Erlauben Sie in den Entwickleroptionen des Geräts Debugging über WLAN und öffnen Sie dessen Optionen. Sie müssen zuerst das Gerät mit dem Rechner koppeln. Wählen Sie dazu "''Gerät mit einem Kopplungscode koppeln''", um einen Kopplungscode und eine IP-Adresse mit Port zu erhalten. Öffnen Sie dann auf dem Rechner die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb pair <IP-Adresse des Geräts>:<Kopplungsport></nowiki>
wobei Sie <tt><IP-Adresse des Geräts>:<Kopplungsport></tt> durch die auf dem Gerät angezeigte IP-Adresse & Port ersetzen. Danach werden Sie aufgefordert, den Kopplungscode einzugeben. Wenn alles geklappt hat, sollte sich das Popup auf dem Gerät schließen und der Rechner als gekoppeltes Gerät angezeigt werden. Geben Sie dann in der Eingabeaufforderung ein:
<nowiki>adb connect <IP-Adresse des Geräts>:<Debug-Port></nowiki>
Die IP-Adresse ist hier noch die gleiche wie beim Koppeln, aber der Port ist ein anderer. Beides wird als IP-Adresse & Port auf dem Gerät angezeigt. Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie entweder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden. Häufig wird beim Neustart des Geräts auch die Erlaubnis für das Debugging über WLAN wieder zurückgesetzt und der verwendete Port ändert sich. Die Kopplung bleibt aber bestehen und muss beim nächsten Verbinden nicht noch einmal durchgeführt werden.

==== WLAN Verbindung über USB starten (Android 10 und früher) ====
Verbinden Sie zunächst das Gerät über USB mit dem Rechner. Öffnen Sie dann die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb tcpip 5555</nowiki>
Damit lauscht das Gerät auf eine TCP/IP-Verbindung an Port 5555. Sollten Sie mehrere Geräte angeschlossen oder Emulatoren laufen haben, müssen Sie genauer angeben, welches Gerät Sie meinen. Geben Sie in diesem Fall ein:
<nowiki>adb devices -l</nowiki>
Sie erhalten eine Liste aller Geräte, wobei die erste Spalte deren Kennung ist. Schreiben Sie dann stattdessen
<nowiki>adb -s <Gerätekennung> tcpip 5555</nowiki>
mit der Gerätekennung des gewünschten Geräts. Sie können die USB-Verbindung nun trennen. Jetzt müssen Sie die IP-Adresse Ihres Gerätes in Erfahrung bringen. Sie finden diese üblicherweise irgendwo in den Einstellungen des Geräts, beispielsweise beim Status oder in den WLAN-Einstellungen. Geben Sie dann ein:
<nowiki>adb connect <IP-Adresse des Geräts></nowiki>
Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie wieder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden.

=== Verbindung zu einem Emulator ===
Sie benötigen dazu den Emulator selbst, sowie mindestens ein AVD (Android Virtual Device). Hinweise zu Installation finden Sie in der [https://developer.android.com/studio/run/emulator Android Studio Dokumentation].

Wenn Sie Android Studio bereits mit den Defaulteinstellungen installiert haben 1), sollte der Emulator bereits mitinstalliert sein. Falls nicht, wählen Sie in Android Studio "''Configure''" - "''SDK Manager''" - "''Android SDK''" - "''SDK Tools''" - ''Android Emulator''", sowie dort die "''Platform Tools''".
Alternativ geht das auch über die Kommandzeile mit dem "sdkmanager" Kommando.

Als nächstes benötigen Sie mindestens ein AVD; auch dies geht am einfachsten über den Dialog in Android Studio:
wählen sie "''Configure''" - "''AVD Manager''" und folgen den Anweisungen (Deviceauswahl, Platform und Android Version).

Auch wenn Sie den Emulator automatisieren benötigen sie Appium; installieren Sie dieses entweder mit dem Mobile Testing Supplement, oder direkt von der Appium homepage (https://github.com/appium/appium-desktop/releases).

1)Android Studio selbst wird nicht von expecco benötigt; es bietet aber kompfortable Dialoge zum Installieren von Paketen und AVDs.

== iOS-Gerät und App vorbereiten ==
Das Ansteuern von iOS-Geräten ist nur über einen Mac möglich. Lesen Sie daher auch den Abschnitt zur [[#Mac_OS|Installation unter Mac OS]].

Bevor Sie ein Mobilgerät mit dem Mobile Testing Plugin ansteuern können, müssen Sie für iOS-Geräte ab iOS 8 Debugging erlauben. Aktivieren Sie dazu die Option ''Enable UI Automation'' unter dem Menüpunkt ''Entwickler'' in den Einstellungen des Geräts. Falls Sie den Eintrag ''Entwickler'' in den Einstellungen nicht finden, gehen Sie wie folgt vor: Schließen Sie das Gerät über USB an den Mac an. Dabei müssen Sie ggf. am Gerät noch der Verbindung zustimmen. Starten Sie Xcode und wählen Sie dann in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie dort Ihr Gerät aus. Danach sollte der Eintrag ''Entwickler'' in den Einstellungen auf dem Gerät auftauchen. Dazu müssen Sie möglicherweise die Einstellungen beenden und neu starten.

[[Datei:Alert.png | thumb | 270px | Beispiel für einen Alert unter iOS]]
Ein Verbindungsaufbau zu dem Gerät ist nicht möglich solange es bestimmte Alerts zeigt. Ein solcher Alert kann z. B. erscheinen wenn FaceTime aktiviert ist, indem ein Hinweis auf anfallende SMS-Gebühren angezeigt wird (siehe Screenshot). Achten Sie darauf, das Gerät so zu konfigurieren, dass es im Leerlauf keine solchen Alerts zeigt.

=== expecco 2.11 und später ===
Sie können beliebige Apps testen, die auf dem verwendeten Gerät lauffähig oder bereits installiert sind. Wenn die App als Development-Build vorliegt, muss die UDID des Geräts in der App hinterlegt sein. In jedem Fall muss der WebDriverAgent für das Gerät signiert werden. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]] unter Mac OS.

Falls Sie in einem Test den Home-Button verwenden wollen, müssen Sie auf dem Gerät AssistiveTouch aktivieren. Sie finden diese Option in den Einstellungen unter ''Allgemein'' > ''Bedienungshilfen'' > ''AssistiveTouch''. Platzieren Sie dann das Menü in der Mitte des oberen Bildschirmrands. Sie können das Drücken des Home-Buttons dann mit dem entsprechenden Menüeintrag im Recorder aufzeichnen oder direkt den Baustein ''Press Home Button'' benutzen.

=== expecco 2.10 ===
Die App, die Sie verwenden wollen, muss als Development-Build vorliegen. Außerdem muss die UDID des Geräts in der App hinterlegt sein.

=== Development-Build signieren ===
Ein Development-Build einer App ist nur für eine begrenzte Zahl von Geräten zugelassen und kann auf anderen Geräten nicht gestartet werden. Es ist aber möglich, das Zertifikat und die verwendbaren Geräte in einem Development-Build auszutauschen.

* Evaluierung mit Demo-App von eXept:
:Gerne stellen wir Ihnen eine Demo-App zur Verfügung, die als Development-Build vorliegt und die wir für Ihr Gerät signieren können. Senden Sie dazu bitte Ihrem eXept-Ansprechpartner die UDID Ihres Gerätes zu. Wie Sie die UDID Ihres Gerätes ermitteln können, ist im folgenden Abschnitt beschrieben.

* Eigene App für Ihr Testgerät verwenden:
:Wenn Sie von den App-Entwicklern einen Development-Build (IPA-Datei) erhalten, der für Ihr Testgerät zugelassen ist, können Sie diesen direkt verwenden. Dazu müssen Sie den Entwicklern die UDID Ihres Geräts mitteilen, damit sie diese eintragen können. '''Sie können die UDID eines Gerätes mithilfe von Xcode auslesen'''. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie Ihr Gerät aus und suchen Sie in Eigenschaften den Eintrag ''Identifier''. Die UDID ist eine 40-stellige Hexadezimalzahl.

* Extern entwickelte App für Ihr Testgerät umsignieren:
:Es können auch Apps umsigniert werden, damit Sie auf anderen Geräten lauffähig sind. Dieser Vorgang ist jedoch kompliziert und setzt insbesondere einen Zugang zu einem Apple-Developer-Account voraus. Eine Dokumentation zur Vorgehensweise ist derzeit in Vorbereitung.

:Für die Evaluierung unterstützen wir Sie gerne beim Umsignieren Ihrer App.


Weitere Informationen zur Verwendung von iOS-Geräten finden Sie auch in der [http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Dokumentation von Appium].

=== Native iOS-Apps ===
Sie können auch Apps verwenden, die bereits nativ auf dem Gerät vorhanden sind. Dazu müssen Sie deren Bundle-ID kennen und diese dann in die Verbindungseinstellungen eintragen. Hier eine kleine Auswahl gängiger Apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

Weitere Bundle-IDs finden Sie [https://github.com/joeblau/apple-bundle-identifiers hier].

= Beispiele =
Bei den Demo-Testsuiten für expecco finden Sie auch Beispiele für Tests mit dem Mobile Testing Plugin. Wählen Sie dazu auf dem Startbildschirm die Option "''Beispiel aus Datei''" und öffnen Sie den Ordner "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
Die Testsuite enthält zwei einfache Testpläne: "''Simple CalculatorTest''" und "''Complex Calculator and Messaging Test''". Beide Tests verwenden einen Android-Emulator, den Sie vor Beginn starten müssen. Die Apps, die im Test verwendet werden, gehören zur Grundausstattung des Emulators und müssen daher nicht mehr installiert werden. Da sich die Apps unter jeder Android-Version unterscheiden können, ist es wichtig, dass Ihr Emulator unter Android 6.0 läuft. Außerdem muss die Sprache auf Englisch gestellt sein.

; Simple CalculatorTest
: Dieser Test verbindet sich mit dem Taschenrechner und gibt die Formel ''2+3'' ein. Das Ergebnis des Rechners wird mit dem erwarteten Wert ''5'' verglichen.

; Complex Calculator and Messaging Test
: Dieser Test verbindet sich mit dem Taschenrechner und öffnet anschließend den Nachrichtendienst. Dort wartet er auf eine einkommende Nachricht von der Nummer ''15555215556'', in der eine zu berechnende Formel gesendet wird. Die Nachricht wird zuvor über einen Socket beim Emulator erzeugt. Nach dem Eintreffen der Nachricht wird diese vom Test geöffnet und deren Inhalt gelesen. Danach wird wieder der Taschenrechner geöffnet, die erhaltene Formel eingegeben und das Ergebnis gelesen. Anschließend wechselt der Test wieder zum Nachrichtendienst und sendet das Ergebnis als Antwort.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
Diese sind Bestandteil des Tutorials zum Mobile Testing Plugin. Der jeweils enthaltene Testfall ist unvollständig und wird im Zuge des Tutorials ergänzt. Lesen Sie dazu den Abschnitt [[#Tutorial|Tutorial]].

= Tutorial =
Es gibt ein Tutorial, das das grundsätzliche Vorgehen zur Erstellung von Tests mit dem Mobile Testing Plugin beschreibt. Grundlage dafür ist ein mitgeliefertes Beispiel, bestehend aus einer einfachen App und einer expecco-Testsuite.

Sie finden es auf der Seite [[Mobile_Testing_Tutorial|Mobile Testing Tutorial]] in zwei Versionen für Android und für iOS.
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_Android|Erste Schritte mit Android]]
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_iOS|Erste Schritte mit iOS]]

= Dialoge des Mobile Testing Plugins =
== Verbindungseditor ==
Mithilfe des Verbindungseditors können Sie schnell Verbindungen definieren, ändern oder aufbauen. Je nach Aufgabe weist der Dialog kleine Unterschiede auf und wird unterschiedlich geöffnet:
*Um eine Verbindung aufzubauen, klicken Sie im GUI-Browser auf "''Verbinden'"' klicken und wählen dann "''Mobile Testing''".
*Um eine bestehende Verbindung im GUI-Browser zu ändern oder zu kopieren, wählen Sie diese aus, machen einen Rechtsklick und wählen im Kontextmenü "''Verbindung bearbeiten''" oder "''Verbindung kopieren''" aus.
*Wollen Sie Verbindungseinstellungen nicht für den GUI-Browser sondern zur Verwendung in einem Test erstellen, wählen Sie im Menü des Mobile Testing Plugins den Punkt "''Verbindungseinstellungen erstellen...''". Darüber können nur die Einstellungen für eine Verbindung erstellt werden, ohne dass eine Verbindung tatsächlich angelegt wird.

Einige der Schaltflächen sind nur beim Erstellen von Verbindungseinstellungen sichtbar:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#"''Einstellungen löschen''": Setzt alle Einträge zurück. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Einstellungen aus Datei laden''": Erlaubt das Öffnen einer gespeicherten Einstellungsdatei (*.csf). Deren Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen aus Anhang laden''": Erlaubt das Öffnen eines Anhangs mit Verbindungseinstellungen aus einem geöffneten Projekt. Diese Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen in Datei speichern''" sowie
#"''Einstellungen in Anhang speichern''": Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern oder als Anhang in einem geöffneten Projekt anlegen. Beide Optionen besitzen ein verzögertes Menü, in dem Sie auswählen können, nur einen bestimmten Teil der Einstellungen zu speichern. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Erweiterte Ansicht''": Damit können Sie in die erweiterte Ansicht wechseln, um zusätzliche Einstellungen vorzunehmen. Lesen Sie dazu mehr am Ende des Kapitels. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Hilfe''": An der rechten Seite wird ein Hilfetext zum jeweiligen Schritt ein- oder ausgeblendet.

Der Dialog ist in drei Schritte unterteilt. Im ersten Schritt wählen Sie das Gerät, das Sie verwenden möchten, im zweiten Schritt wählen Sie aus, welche App verwendet werden soll und im letzten Schritt erfolgen die Einstellungen zum Appium-Server.

===Schritt 1: Gerät auswählen===
Im oberen Teil erhalten Sie eine Liste aller angeschlossenen Appium-Geräte, die erkannt werden. Mit der Checkbox darunter können Sie die Geräte ausblenden, die zwar erkannt werden, aber nicht bereit sind. Falls Sie ein Gerät eintragen wollen, das nicht angeschlossen ist, können Sie dies mit dem entsprechenden Knopf "''Android-Gerät eingeben''" bzw. "''iOS-Gerät eingeben''" anlegen. Dazu müssen Sie jedoch die benötigten Eigenschaften Ihres Geräts kennen. Das Gerät wird dann in einer zweiten Geräteliste angelegt und kann dort ausgewählt werden. Wenn keine Liste mit angeschlossenen Elementen angezeigt werden kann, werden stattdessen verschiedene Meldungen angezeigt:
*Keine Geräte gefunden
*:expecco konnte kein Android-Geräte finden.
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*Keine verfügbaren Geräte gefunden
*:expecco konnte keine verfügbaren Android-Geräte finden. Es wurden aber nicht verfügbare gefunden, z.B. mit dem Status "unauthorized".
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*:Um nicht verfügbare Geräte anzuzeigen, aktivieren Sie unten diese Option.
*Verbindung verloren
*:expecco hat die Verbindung zum adb-Server verloren. Versuchen Sie die Verbindung wieder herzustellen, indem Sie auf den Button klicken.
*Verbindung fehlgeschlagen
*:expecco konnte sich nicht mit dem adb-Server verbinden. Möglicherweise läuft er nicht oder der angegebene Pfad stimmt nicht.
*:Überprüfen Sie die adb-Konfiguration in den Einstellungen und versuchen Sie den adb-Server zu starten und eine Verbindung herzustellen indem Sie auf den Knopf klicken.
*Verbinden ...
*:expecco verbindet sich mit dem adb-Server. Dies kann einige Sekunden dauern.
*adb-Server starten ...
*:expecco startet den adb-Server. Dies kann einige Sekunden dauern.

Mit "''Weiter''" gelangen Sie zum nächsten Schritt. Wenn Sie Einstellungen für den GUI-Browser eingeben, ist das erst möglich, wenn ein Gerät ausgewählt wurde.

Anmerkung zum Freischalten: In jüngeren Android Versionen werden die Entwickleroptionen zunächst nicht mehr in den Einstellungen angeboten. Falls ihr Android Gerät in den Einstellungen keinen Eintrag zu "''Entwickleroptionen''" zeigt, wählen Sie zunächst den Eintrag "''Telefoninfo''", dann "''SoftwareVersionsInfo''" und klicken darin mehrfach auf den Eintrag "''BuildVersion''".

==== Chromedriver verwalten ====
Wenn die App, die Sie bedienen wollen, WebViews mit Chrome benutzt, benötigt Appium Zugriff auf einen passenden Chromedriver. Wenn Sie ein Gerät in der Liste auswählen, können Sie über "''Chromedriver verwalten''" sehen, welche Chrome-Versionen auf dem Gerät vorhanden sind und welche Chromedriver-Versionen durch expecco zur Verfügung stehen. Über diesen Dialog können Sie auch benötigte Chromedriver-Versionen herunterladen. Beachten Sie, dass auf dem Gerät verschiedene Chrome-Versionen vorhanden sein können, da die Apps in ihren WebViews nicht die gleiche Chrome-Version verwenden müssen, wie die als Browser installierte. Damit alles funktioniert, sollte der verwendete Chromedriver zur entsprechenden App passen. Sie können den Pfad zum Chromedriver auch am Ende des Verbindungsdialogs in den erstellten Capabilities ändern.

==== WLAN-Android-Geräte verbinden ====
Sie können sich auch über WLAN zu Android-Geräten verbinden. Dazu muss das Gerät zunächst mit adb verbunden werden, siehe [[Mobile_Testing_Plugin#Verbindung_.C3.BCber_WLAN|Verbindung über WLAN]]. Ab expecco 22.1 bietet der Verbindungseditor hierfür einen Dialog, der Ihnen dabei hilft und den Sie anstatt der Eingabeaufforderung verwenden können. Für Geräte mit Android 11 oder höher können Sie hier das Gerät mit dem Rechner zu koppeln, indem Sie die entsprechenden Parameter angeben und anschließend die Verbindung unter Angabe von IP-Adresse und Port aufbauen. Sie können damit auch für Geräte, die über USB verbunden sind, eine WLAN-Verbindung aufbauen. Wenn Sie das entsprechende Gerät in der Liste auswählen, werden die benötigten Angaben automatisch ausgelesen.

Beachten Sie, dass der Aufbau einer WLAN-Verbindung nicht Teil der Verbindungseinstellungen ist. Wenn Sie mit den erzeugten Einstellungen eine neue Verbindung aufbauen wollen, müssen Sie sicherstellen, dass das Gerät über mit der angegebenen IP-Adresse und dem Port mit adb verbunden ist, damit es gefunden wird. Die ADB-Verbindung geht verloren, wenn der ADB-Server oder das Gerät neu gestartet werden. Die Erlaubnis für das WLAN-Debugging wird beim Neustart des Geräts auch häufig zurückgesetzt und der Debug-Port kann dann wechseln. Daher muss eine WLAN-Verbindung immer manuell hergestellt werden.

===Schritt 2: App auswählen===
Hier können Sie Angaben zur App machen, die getestet werden soll. Dabei können Sie entscheiden, ob Sie eine App verwenden wollen, die bereits auf dem Gerät installiert ist, oder ob für den Test eine App installiert werden soll. Wählen Sie oben den entsprechenden Reiter aus. Je nachdem, ob Sie im vorigen Schritt ein Android- oder ein iOS-Gerät ausgewählt haben, ändert sich die erforderte Eingabe.

*'''Android'''
**''App auf dem Gerät''
**:Wenn Sie im ersten Schritt ein angeschlossenes Gerät ausgewählt haben, werden die Pakete aller installierten Apps automatisch abgerufen und Sie können die Auswahl aus den Drop-down-Listen treffen. Die installierten Apps sind in Fremdpakete und Systempakete unterteilt; wählen Sie die entsprechende Paketliste aus. Diese Auswahl gehört nicht zu den Einstellungen, sondern stellt nur die entsprechende Paketliste zur Verfügung. Sie können den Filter benutzen, um die Liste weiter einzuschränken und dann das gewünschte Paket auswählen. Die Activities des ausgwählten Pakets werden ebenfalls automatisch abgerufen und als Drop-down-Liste zur Verfügung gestellt. Wählen Sie die Activity aus, die gestartet werden soll. In der Regel wird automatisch eine Activity aus der Liste eingetragen. Falls Sie kein verbundenes Gerät verwenden, müssen Sie die Eingabe des Pakets und der Activity von Hand vornehmen.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Benutzen Sie einen lokalen Appium-Server, können Sie den rechten Butten benutzen, um zu der Installationsdatei der App zu navigieren und diesen Pfad einzutragen. Wenn möglich werden dabei auch das entsprechende Paket und die Activity in den Feldern darunter eingetragen. Diese Angabe ist aber nicht notwendig.

*'''iOS'''
**''App auf dem Gerät''
**:Geben Sie die Bundle-ID einer installierten App an. Sie können die IDs der installierten Apps bspw. mithilfe von Xcode erfahren. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü "''Window''" den Eintrag "''Devices''". Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wenn Sie Ihr Gerät auswählen, sehen Sie in der Übersicht eine Auflistung der von Ihnen installierten Apps.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Zu den Vorraussetzungen an Apps für reale Geräte lesen Sie bitte den Abschnitt [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Geräte und App vorbereiten]].

Im unteren Teil können Sie festlegen, ob die App beim Verbindungsabbau zurückgesetzt bzw. deinstalliert werden soll, und ob sie initial zurückgesetzt werden soll. Auch hier wird die entsprechende Capability gar nicht gesetzt, wenn Sie "''(Default)''" auswählen. Mit "''Weiter''" gelangen Sie zum nächsten Schritt.

===Schritt 3: Servereinstellungen===
Im letzten Schritt befindet sich zunächst im oberen Teil eine Liste aller Capabilities, die sich aus Ihren Angaben der vorigen Schritte ergeben. Wenn Sie sich mit Appium auskennen und noch zusätzliche Capabilities setzen möchten, die der Verbindungseditor nicht abdeckt, können Sie durch Klicken auf "''Bearbeiten''" in die erweiterte Ansicht gelangen. Lesen Sie dazu den Abschnitt weiter unten.

Wenn Sie Einstellungen für den GUI-Browser eingeben, können Sie den ''Verbindungsnamen'' eintragen, mit dem die Verbindung angezeigt wird. Dies ist auch der Name unter dem Bausteine diese Verbindung verwenden können, wenn sie aufgebaut ist. Wenn Sie das Feld frei lassen, wird ein Name generiert. Wenn der Haken für "''Von expecco gesteuert''" gesetzt ist, wird expecco einen lokalen Appium-Server an einem freien Port starten, oder einen bereits gestarteten freien Server verwenden. Um einen eigenen Server zu verwenden, schalten Sie diese Funktion ab und geben Sie die entsprechende Adresse ein. Sie erhalten die lokale Standard-Adresse und bereits verwendete Adressen zur Auswahl.

In älteren expecco-Versionen ist der Haken mit "''Bei Bedarf starten''" beschriftet. In diesem Fall müssen Sie auch eine Adresse angeben, wenn expecco den Server starten soll. expecco versucht dann beim Verbinden einen Appium-Server an der angegebenen Adresse zu starten, wenn dort noch keiner läuft. Dieser Server wird dann beim Beenden der Verbindung ebenfalls heruntergefahren. Dies funktioniert nur für lokale Adressen. Achten Sie darauf, nur Portnummern zu verwenden, die auch frei sind. Verwenden Sie am besten nur ungerade Portnummern ab dem Standardport 4723. Beim Verbindungsaufbau wird ebenfalls die folgende Portnummer verwendet, wodurch es sonst zu Konflikten kommen könnte.

Je nachdem, wie Sie den Dialog geöffnet haben, gibt es nun verschiedene Schaltflächen um ihn abzuschließen. In jedem Fall haben Sie die Option zu speichern. Dabei öffnet sich ein Dialog, indem Sie entweder ein geöffnet Projekt auswählen können, um die Einstellungen dort als Anhang zu speichern, oder auswählen es in einer Datei zu speichern, die Sie anschließend angeben können. Durch das Speichern wird der Dialog nicht beendet, wodurch Sie anschließend noch eine andere Option auswählen könnten.

Wenn Sie den Editor zum Verbindungsaufbau geöffnet haben, können Sie abschließend auf "''Verbinden''" oder "''Server starten und verbinden''" klicken, je nachdem, ob der Haken für den Serverstart gesetzt ist. Für das Ändern oder Kopieren einer Verbindung im GUI-Brower heißt diese Option "''Übernehmen''", da in diesem Fall nur der Verbindungseintrag geändert bzw. neu angelegt wird, der Verbindungsaufbau aber nicht gestartet wird. Das können Sie bei Bedarf anschließend über das Kontextmenü tun. Falls Sie Capabilities einer bestehenden Verbindung geändert haben, fordert Sie anschließend ein Dialog auf zu entscheiden, ob diese Änderungen direkt übernommen werden sollen, indem die Verbindung abgebaut und mit den neuen Verbindungen aufgebaut wird, oder nicht. In diesem Fall werden die Änderungen erst wirksam, nachdem Sie die Verbindung neu aufbauen.

Zur Verwendung des Verbindungseditors lesen Sie auch den entsprechenden Abschnitt im jeweiligen Tutorial in Schritt 1 (Android: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren|Demo ausführen]], iOS: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren_.28iOS.29|Demo ausführen (iOS)]]).

===Erweiterte Ansicht===
Die erweiterte Ansicht des Verbindungseditors erhalten Sie entweder durch Klicken auf "''Bearbeiten''" im dritten Schritt oder jederzeit über den entsprechenden Menüeintrag, wenn Sie den Editor über das Plugin-Menü gestartet haben. In dieser Ansicht erhalten Sie eine Liste aller eingestellten Appium-Capabilities. Zu dieser können Sie weitere hinzufügen, Einträge ändern oder entfernen. Um eine Capability hinzuzufügen, wählen Sie diese aus der Drop-down-Liste des Eingabefelds aus. In dieser befinden sich alle bekannten Capabilities sortiert in die Kategorien ''Common'', ''Android'' und ''iOS''. Haben Sie eine Capability ausgewählt, wird ein kurzer Informationstext dazu angezeigt. Sie können in das Feld auch von Hand eine Capability eingeben. Klicken Sie dann auf "''Hinzufügen''", um die Capabilitiy in die Liste einzutragen. Dort können Sie in der rechten Spalte den Wert setzen. Um einen Entrag zu löschen, wählen Sie diesen aus und klicken Sie auf "''Entfernen''". Mit "''Zurück''" verlassen Sie die erweiterte Ansicht.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Laufende Appium-Server ==
Im Menü des Mobile Testing Plugins finden Sie den Eintrag "''Appium-Server...''". Mit diesem öffnen Sie ein Fenster mit einer Übersicht aller Appium-Server, die von expecco gestartet wurden und auf welchem Port diese laufen. Durch Klicken auf das Icon in der Spalte "''Log anzeigen''" können Sie das Logfile des entsprechenden Servers anschauen. Dieses wird beim Beenden des Servers wieder gelöscht. Mit den Icons in der Spalte "''Beenden''" kann der entsprechenden Server beendet werden. Allerdings wird dies verhindert, wenn expecco über diesen Server noch eine offene Verbindung hat. Für welche Verbindung ein Server verwendet wird, sehen Sie in der rechten Spalte. Steht dort ''<idle>'' wird er zur Zeit nicht von expecco verwendet.

[[Datei:MobileTestingAppiumServer.png]]

Beim Öffnen des Editors um eine Appium-Verbindung aufzubauen, wird direkt ein Appium-Server gestartet, um den folgenden Verbindungsaufbau zu beschleunigen. Zu diesem Zweck hält sich expecco auch immer einen freien Appium-Server offen. Weitere laufende Server, die nicht mehr verwendet werden, werden jedoch nach einiger Zeit automatisch beendet.

Im Menü des Mobile Testing Plugins finden Sie auch den Eintrag "''Alle Verbindungen und Server beenden''". Dies ist für den Fall gedacht, dass Verbindungen oder Server auf andere Weise nicht beendet werden können. Beenden Sie Verbindungen wenn möglich immer im GUI-Browser oder durch Ausführen eines entsprechenden Bausteins. Server, die Sie in der Server-Übersicht gestartet haben, beenden Sie dort; Server, die mit einer Verbindung gestartet wurden, werden automatisch mit dieser beendet.

Beachten Sie, dass in der Übersicht nur Server aufgelistet sind, die von expecco gestartet und verwaltet werden. Mögliche andere Appium-Server, die auf andere Art gestartet wurden, werden nicht erkannt.

== Recorder ==
Besteht im GUI-Browser eine Verbindung zu einem Gerät, kann der integrierte Recorder verwendet werden, um mit diesem Gerät einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

[[Datei:MobileTestingRecorder.png|caption|]]

====Komponenten des Recorderfensters====
#'''Aufnahme fortsetzen/pausieren''': Über das rechte Symbol können Sie die Aufnahme pausieren. Sie sehen dann ein großes Pause-Symbol in der Anzeige. Alle Aktionen, die Sie währenddessen im Recorder machen werden zwar ausgeführt, es werden aber keine Bausteine aufgezeichnet. Über das linke Symbol können Sie dann wieder in den normalen Aufnahmemodus wechseln.
#'''Aufnahme stoppen''': Stoppt die Aufnahme und schließt das Recorderfenster.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Gerät. Dies wird nötig, wenn das Gerät zur Ausführung einer Aktion länger braucht oder sich etwas ohne das Anstoßen durch den Recorder ändert. Seit expecco 21.2 gibt es hier zusätzlich ein Untermenü, mit dem automatisches Aktualisieren angeschaltet werden kann, indem im Hintergrund auf Änderungen geprüft wird (siehe auch ''Automatisches Aktualisieren'' weiter unten).
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Elemente einzeichnen''': Die Rahmen aller Elemente der Ansicht werden angezeigt.
#'''Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst. Dabei stehen folgende Aktionen zur Verfügung:
#*Aktionen auf Elemente:
#**Klicken: Kurzer Klick auf das Element, über dem der Cursor steht. Zur genaueren Bestimmung, welches Element verwendet wird, benutzen Sie die Funktion Follow-Mouse oder Element-Highlighting.
#**Antippen mit Dauer (Element): Ähnlich zum Klicken, nur dass zusätzlich die Dauer des Klicks aufgezeichnet wird. Dadurch sind auch längere Klicks möglich.
#**Antippen mit Position (Element): Ähnlich zum Klicken, aber zusätzlich wird die Position innerhalb des Elements aufgenommen. Die Position kann relativ zur Größe des Elements aufgenommen werden oder, wenn Sie dabei Strg gedrückt halten, absolut zur linken oberen Ecke des Elements.
#**Text setzen: Ermöglicht das Setzen eines Textes in Eingabefelder.
#**Text löschen: Löscht den Text eines Eingabefelds.
#*Aktionen auf das Gerät:
#**Antippen (Bildschirm): Löst einen Klick auf die Bildschirmposition aus.
#**Antippen mit Dauer (Bildschirm): Löst einen Klick auf die Bildschirmposition aus, bei dem auch die Dauer berücksichtigt wird.
#**Wischen: Wischen in einer geraden Linie vom Punkt des Drückens des Mausknopfes bis zum Loslassen. Die Dauer wird ebenfalls aufgezeichnet.
#:Beachten Sie bei diesen Aktionen, dass das Ergebnis sich auf verschiedenen Geräten unterscheiden kann, bspw. bei verschiedenen Bildschirmauflösungen.
#*Erstellen von Testablauf-Bausteinen
#**Attribut prüfen: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Das Ergebnis triggert den entsprechenden Ausgang.
#**Attribut zusichern: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Bei Ungleichheit schlägt der Test fehl.
#**Attribut holen: Liest den aktuellen Wert eines Attributs aus.
#*Automatisch
#:Ist das Auto-Werkzeug ausgewählt, können alle Aktionen durch spezifische Eingabeweise benutzt werden: ''Klicken'', ''Element antippen'' und ''Wischen'' funktionieren weiterhin durch Klicken, wobei sie anhand der Dauer und der Bewegung des Cursors unterschieden werden. Um ein ''Antippen'' auszulösen, halten Sie beim Klicken Strg gedrückt. Die übrigen Aktionen erhalten Sie durch einen Rechtsklick auf das Element in einem Kontextmenü.
#'''Kontext-Aktionen''': Hier können Sie Aktionen aufzeichnen, die Kontexte betreffen:
#*Zu Kontext wechseln: Bietet eine Liste der aktuell verfügbaren Kontexte und Sie können auswählen, zu welchem gewechselt werden soll.
#*Aktuellen Kontext holen: Holt den Handle des aktuellen Kontexts.
#*Kontext-Handles holen: Holt eine Liste aller aktuell verfügbaren Kontext-Handles.
#'''Softkeys''': Nur unter Android. Simuliert das Drücken der Knöpfe Zurück, Home, Fensterliste und Power.
#'''Home-Button''': Nur unter iOS ab expecco 2.11. Ermöglicht das Drücken des Home-Buttons. Vor expecco 19.2 funktioniert es nur, wenn AssistiveTouch aktiviert ist und sich das Menü in der Mitte des oberen Bildschirmrands befindet. Ab expecco 19.2 verwendet die Funktion kein AssistiveTouch mehr.
#'''Hilfe''': Öffnet diese Online-Dokumentation auf der allgemeinen Seite zu [[GuiBrowser_Recorder|GUI-Browser Recordern]].
#'''Anzeige''': Zeigt einen Screenshot des Geräts. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Ansicht anpassen''': Öffnet einen Dialog um die Ansicht anzupassen, falls expecco das Bild nicht richtig darstellt. Sie können die Skalierung anpassen oder das Bild um 90° drehen.
#'''Ausrichtung anpassen''': Korrigiert das Bild, falls dieses auf dem Kopf stehen sollte. Über den Pfeil rechts daneben kann das Bild auch um 90° gedreht werden, falls dies einmal nötig sein sollte. Ab expecco 19.1 finden Sie diese Funktion in ''Ansicht anpassen''. Die Ausrichtung des Bildes ist für die Funktion des Recorders unerheblich, dieser arbeitet ausschließlich auf den erhaltenen Elementen.
#'''Skalierung''': Ändert die Skalierung des Screenshots.
#'''Meldungen''': Zeigt den Pfad des ausgewählten Elements oder andere Meldungen an. Es gibt ein Kontextmenü, um eine Liste der vorigen Meldungen zu sehen.

====Verwendung====
Mit jedem Klick im Fenster wird eine Aktion ausgelöst und im Arbeitsbereich des GUI-Browsers aufgezeichnet. Dort können Sie das Aufgenommene abspielen, editieren oder daraus einen neuen Baustein erstellen.
Aktionen zum Auslösen von Sofkeys finden Sie direkt in der Menüleiste (s.o.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Werkzeugs in der Menüleiste (s.o.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion.
Zur Verwendung des Recorders lesen Sie auch Schritt 2 im Tutorial ([[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen|Android]] bzw. [[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen_.28iOS.29|iOS]]).

====Elemente verbergen====
Ab expecco 21.2 gibt es im Kontextmenü außerdem die Möglichkeit, das ausgewählte Element im Recorder zu verbergen. Das bedeutet, dass dieses Element fortan nicht mehr ausgewählt werden kann. Diese Funktion eignet sich dazu, Elemente zu ignorieren, die im Vordergrund liegen, um auf Elemente darunter zugreifen zu können. Um diesen Zustand wieder rückgängig zu machen, müssen Sie das entsprechende Element im Baum des GUI-Browsers finden, dort gibt es im Kontextmenü ebenfalls einen solchen Eintrag.

====Automatisches Aktualisieren====
Der Recorder zeigt kein Livebild des Geräts sondern nur eine Momentaufnahme. Um mit der Anzeige auf dem Gerät übereinzustimmen muss daher nach Änderungen aktualisiert werden. Der Recorder aktualisiert sich automatisch, nachdem er eine Aktion ausgeführt hat. Ab expecco 20.2 sind zudem weitere automatische Updates möglich. Sie können Sie im Menü ''Fenster'' aktivieren.

Zum einen kann kurze Zeit nach dem Ausführen einer Aktion überprüft werden, ob es noch Änderungen nach der ersten Aktualisierung gegeben hat, damit in diesem Fall eine zweite Aktualisierung stattfinden kann. Dies soll das Problem beheben, dass der Recorder nach einer Aktion nicht aktuell ist, weil die Aktualisierung zu früh stattgefunden hat.

Zum anderen kann eine periodische Aktualisierung eingeschaltet werden. Nach einem einstellbaren Interval wird der Recorder automatisch aktualisiert, sollte es Änderungen geben. Dadurch ist die Anzeige im Recorder immer weitgehend aktuell, allerdings entsteht dadurch auch ein Mehraufwand was die Kommunikation mit dem Gerät betrifft.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid-Apps und WebViews =

'''!!! WICHTIGER HINWEIS - Wenn Sie Probleme haben, auf den Webview zu wechseln, geben Sie bitte unter den Android Einstellungen - Apps -Standard Apps "Chrome" als "Browser-App" an !!!
'''

Hybrid-Apps enthalten neben den Plattform-nativen Elementen weitere Elemente, die in einen WebView eingebunden sind. Diese Elemente können ebenfalls bedient werden, allerdings muss zuvor in den entsprechenden Kontext gewechselt werden. Mit dem Baustein "''Get Current Context''" erhalten Sie den aktuellen Kontext. Zu Beginn ist dies "''NATIVE_APP''", also der Kontext der nativen Elemente. Mit dem Baustein "''Get Context Handles''" bekommen Sie eine Collection aller vorhandenen Kontexte. Gibt es einen WebView-Kontext, so heißt dieser "''WEBVIEW_1''" oder "''WEBVIEW_<package>''" mit dem Paket des WebViews. Es kann auch mehrere WebView-Kontexte geben. Zu jedem WebView-Kontext gibt es im nativen Kontext ein entsprechendes WebView-Element. Mit dem Baustein "''Switch to Context''" können Sie in einen solchen Kontext wechseln und haben fortan nur Zugriff auf die Elemente in diesem Kontext.

Im GUI-Browser werden zum einen oben im Baum die vorhandenen Kontexte angezeigt, zum anderen wird der Baum eines Kontexts unterhalb des entsprechenden WebView-Elements eingefügt.

= XPath anpassen mithilfe des GUI-Browsers =
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen "''GTIN-13 (EAN-13)''" und "''Verify''", das Eingabefeld der Zahl "''4006381333986''" und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des "''GTIN-13''"-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch "''Pfad überprüfen''" (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit "''Verify Path: OK''" (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit "*" zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert "''GTIN-13 (EAN-13)''" besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer "''hierarchy''" (für iOS wäre es "''AppiumAUT''"), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix "''android.widget.''", das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend "''XCUIElementType''" am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. "''FrameLayout''" ist ein Kindelement von "''hierarchy''", "''LinearLayout''" ist ein Kind von "''FrameLayout''" usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element "''hierarchy''" beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben "''TextView''"-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ "''Button''" gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut "''resource-id''". Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut "''name''" verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem "@" eingeleitet und der Wert mit einem "=" in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter "''Test''" eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf "''Lauf''". Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu "''Eigenschaften''", wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

== Weitere Locator-Strategien ==
Appium bietet neben XPath noch weitere Strategien zur Adressierung von Elementen an. Einige davon stehen Ihnen '''ab Version 20.1''' ebenfalls mit expecco zur Verfügung. Diese sind nicht ganz so mächtig wie XPath, dafür aber häufig schneller bei der Auflösung auf dem Gerät. Insbesondere bei der Verwendung mit iPhones, wo die Hierarchie bei jeder XPath-Auflösung erst aufgebaut werden muss, bieten alternative Strategien einen Vorteil für die Laufzeit.

XPath ist weiterhin der Standard, das heißt alle Locator ohne besondere Angabe werden als XPath interpretiert. Um eine der anderen Strategien zu verwenden, schreiben Sie diese mit einem Gleichzeichen vor den gewünschten Locator. Diese Technik können Sie sowohl an den Blöcken verwenden, als auch im GUI-Browser testen.

{|
|-
| style="vertical-align:top" | AccessibilityId || style="padding-bottom:0.5em" | Verwendet den Wert des Elements, der dazu dient, die App barrierefrei zu machen. Für iOS ist das das Attribut '''Accessibility-id''', für Android das Attribut '''content-descr'''. ''Beispiel: accessibilityId=Löschen''
|-
| style="vertical-align:top" | className || style="padding-bottom:0.5em" | Verwendet den Namen der Klasse des Elements. ''Beispiel: className=android.widget.FrameLayout''
|-
| style="vertical-align:top" | id || style="padding-bottom:0.5em" | Verwendet die Kennung des Elements. Für iOS ist das das Attribut '''name''', für Android das Attribut '''resource-id'''. ''Beispiel: id=android:id/text1''
|-
| style="vertical-align:top" | iOSClassChain1 || style="padding-bottom:0.5em" | Verwendet die Hierarchie der Elemente ähnlich wie bei XPath. Eine Erklärung zum Aufbau finden Sie [https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules hier]. ''Beispiel: iOSClassChain=XCUIElementTypeWindow/XCUIElementTypeButton[`label == "Ok"`]''
|-
| style="vertical-align:top; padding-right:1em" | iOSNsPredicateString1 || style="padding-bottom:0.5em" | Verwendet einfache Kriterien, wie Attribute, die auch kombiniert werden können. ''Beispiel: iOSNsPredicateString=type == 'XCUIElementTypeButton' AND name == 'Weiter'''
|-
| style="vertical-align:top" | name1 || style="padding-bottom:0.5em" | Verwendet den Namen des Elements. ''Beispiel: name=Bestätigen''
|-
|}

:1 ''nur für iOS''

Um eine direkte Beschleunigung mit iOS zu erzielen, ohne dass Sie Ihre bisherigen Pfade anpassen müssen, wandelt expecco zudem Pfade, die nur aus einem Element mit Klasse und name-Attribut bestehen, zur Laufzeit automatisch in einen entsprechenden Locator der Strategie iOSNsPredicateString um. Wenn Sie einen Pfad explizit als XPath markieren, wird diese Anpassung nicht vorgenommen.

=Probleme und Lösungen=
== Locator sind versionsabhängig oder variabel ==
Dann sollten Sie die Locator (xPath) entweder in einer Variablen halten oder ein Locator-Mapping in einem Screenplay Anhang definieren. Es ist auch möglich, lediglich Teile des Locators (z.B. Locator-Pfad eines Elternelements oder Attributwert) in einer Variable zu halten und im Freezevalue des Locator-Pins mit "''$(varName)''" einzufügen.

==Unsichtbare UI-Elemente==
Beachten Sie, dass im [[#Recorder|Recorder]] auch Elemente berücksichtigt werden, die Sie auf dem Bildschirm nicht sehen. Schalten Sie daher das Element-Highlighting an oder nutzen Sie die Follow-Mouse-Funktion und den Elementbaum im GUI-Browser, um festzustellen, ob das richtige Element verwendet wird. Es kann vorkommen, dass unsichtbare Elemente vor anderen Elementen liegen und diese verdecken, so dass die gewünschten Elemente im Recorder nicht ausgewählt werden können. Lesen Sie dazu den Abschnitt [[#Elemente_verbergen|Elemente verbergen]].

==iOS: Kabel nicht zertifiziert==
In manchen Fällen erscheint beim Verbinden eines iOS-Geräts über USB der Hinweis, das verwendete Kabel sei nicht zertifiziert. In diesem Fall hilft es nur, das entsprechende Kabel auszutauschen.
==iOS: Alerts beim Verbindungsaufbau==
Stellen Sie sicher, dass beim Verbindungsaufbau mit einem iOS-Gerät keine Alerts geöffnet sind. Der Aufbau schlägt sonst fehl, da die App nicht in den Vordergrund kommen kann. Siehe auch [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Gerät und App vorbereiten]].

==iOS: .ipa installieren nicht möglich==
Beachten Sie, dass auf iOS-Simulatoren keine ''.ipa''-Dateien sondern nur ''.app''-Dateien installiert werden können.

==iOS: Erster Verbindungsaufbau funktioniert nicht==
Wenn auf Ihrem Mac noch kein signierter Build des WebDriverAgents liegt, muss dieser beim ersten Verbindungsaufbau erst erzeugt werden. Das kann in der Regel etwas länger als eine Minute dauern. Standardmäßig verwendet Appium aber einen Timeout von 60000 ms um zu warten bis der WebDriverAgent auf dem Gerät startet, so dass der Aufbau in diesen Fällen abgebrochen wird. Sie können den Timeout mit der Capability ''wdaLaunchTimeout'' setzen, z.B. auf ''120000''.

Außerdem müssen die Einstellungen für die Signierung passen. Am zuverlässigsten funktioniert das nach unserer Erfahrung, wenn man im Xcode-Projekt des WebDriverAgents auf automatische Signierung stellt und das Team setzt. Siehe dazu die Erklärung im Abschnitt [[#WebDriverAgent-Signierung|WebDriverAgent-Signierung]]. In diesem Fall sollten Sie die Capabilities ''xcodeConfigFile'' bzw. ''xcodeOrgId'' und ''xcodeSigningId'' '''nicht''' verwenden, da es sonst zu Konflikten kommen kann. Achtung: Wenn Sie eine Team-ID in den Mobile-Testing-Einstellungen gesetzt haben, setzt expecco diese automatisch als ''xcodeOrgId''!

Achten Sie beim ersten Verbindungsaufbau außerdem auf Ihr Gerät, da Sie dort möglicherweise der Installation per Passwort zustimmen müssen. Auf dem Mac kann die Eingabe des Passworts zur Freigabe des Schlüsselbunds für die Signierung nötig werden, häufig auch mehrmals.

==Android: Gerät nicht im Verbindungsdialog==
Wenn ein über USB angeschlossenes Android-Gerät nicht im Verbindungsdialog auftaucht, versuchen Sie, den USB-Verbindungstyp zu ändern. In der Regel sollten MTP oder PTP funktionieren. Prüfen Sie nochmal, ob "USB Debugging" in den Entwicklereinstellungen des Geräts aktiviert ist (diese Einstellungen sind bei manchen Geräten zunächst unsichtbar, und müssen durch einen Trick zugänglich gemacht werden). Siehe auch [[#Android-Ger.C3.A4t_vorbereiten|Android-Gerät vorbereiten]].

==Android: Abgeschnittene Elemente unten==
Bei Android-Geräten, die die Steuerungsleiste bzw. Softkeys automatisch ein- und ausblenden, kann es vorkommen, dass der Recorder im unteren Bereich Elemente abschneidet, die durch die Softkeys verdeckt würden, auch wenn sie zu diesem Zeitpunkt gar nicht angezeigt werden. In diesem Fall hift es, die Softkeys so einzustellen, dass sie in einer permanenten Leiste angezeigt werden.

Bei neueren Android-Versionen gibt es eine solche Einstellung in der Regel nicht. Auch wenn die Steuerelemente permanent eingeblendet sind, liegen sie auf keiner extra Leiste, sondern vor dem Inhalt der App. Es gibt dann im unteren Teil einen Bereich, der nicht bedient werden kann, weil er nicht zum aktiven Bereich der App gezählt wird, weshalb die Elemente von Appium abgeschnitten werden. Dieser Bereich kann auch größer sein als von den Steuerungselementen beansprucht. Bekannt ist dies für Samsung-Geräte mit Android 11. Da die Information über die Größe des App-Bereichs bereits auf Android-Ebene so geliefert wird, können wir hierfür keine Lösung anbieten, sondern können nur hoffen, dass das Problem vom Hersteller behoben wird. Sie können versuchen, ob Sie mit der Einstellung von Gestensteuerung bessere Ergebnisse bekommen, allerdings gibt es hier das gleiche Problem.

== Android: Test hängt beim Suchen eines Elements==
Der Baustein ''Find Element by XPath'' und alle Element-Bausteine warten bis ein Element zum angegebenen Pfad auftaucht. Den Timeout dafür kann man entweder am Baustein direkt oder in den Umgebungsvariablen ändern. Wenn das Element aber bereits da sein sollte und es dennoch sehr lange dauert, bis der Test weitergeht, kann das am UIAutomator/UIAutomator2 liegen. Dieser wartet, bis die App in den Idle-Zustand geht, bevor er überhaupt nach Elementen sucht. Dies kann länger dauern, wenn die App z.B. im Hintergrund noch Animationen abspielt oder andere Aktionen ausführt. Auch das Holen des Page-Sources z.B. beim Aktualisieren im GUI-Browser oder im Recorder kann dadurch länger dauern. Standardmäßig gibt es hierfür einen Timeout von 10 Sekunden, nach dem nicht weiter auf den Idle-Zustand gewartet wird. Dieser Timeout lässt sich durch eine Einstellung in Appium anpassen (waitForIdleTimeout). Falls Sie einen anderen Wert für diesen Timeout setzen möchten, ist dies ab expecco 21.2 möglich, indem Sie vor dem Test den Smalltalk-Code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> ausführen. Der Timeout wird in Millisekunden angegeben, das Beispiel setzt ihn also auf 2 Sekunden.

==Android: Aktualisieren des Trees oder Wechseln zum Webview-Kontext braucht zu lange==
Speziell mit älteren Geräten kann es vorkommen, dass neuere Chromedriver nicht initialisiert werden können. Das führt dann dazu, dass nicht in den Webview-Kontext gewechselt werden kann. Dies wird von Appium allerdings nur über einen Timeout festgestellt, der standardmäßig bei 4 Minuten liegt. Da expecco auch beim Aufbauen des Trees im GUI-Browser versucht in den Webview-Kontext zu wechseln, kann das zu sehr langen Ladezeiten führen. Da es in Appium keine Möglichkeit gibt, diesen Timeout herunter zu setzen, haben wir die Version, die wir im MobileTestingSupplement bereitstellen, um eine entsprechende Capability erweitert. Ab der Version 1.13.1.0 des [[#Windows|MobileTestingSupplements]] kann mit ''chromedriverStartTimeout'' der Timeout in Millisekunden gesetzt werden. Der Wechsel funktioniert dadurch zwar trotzdem nicht, aber expecco braucht dann nicht mehr so lange beim Aktualisieren des Trees und der Baustein zum Wechseln des Kontextes schlägt schneller fehl. Der Verbindungsdialog fügt diese Capability ab expecco 22.1 automatisch hinzu.

==Keine Aktion bei Klick==
Der Baustein zum Klicken auf ein Element ist erfolgreich, aber auf dem Gerät wurde keine Aktion ausgeführt.
:Dies kann vorkommen, wenn das Element von einem anderen Element verdeckt ist und ein Klick auf das Element deshalb nicht möglich ist. In diesem Fall wird von Appium kein Fehler geworfen, sondern es passiert einfach nichts. Wenn Sie dennoch einen Klick an der Position des Elements machen möchten, auch wenn es verdeckt ist, benutzen Sie stattdessen den Baustein ''Tap'' und übergeben Sie diesem die Position des Elements (''Get Location''). Wenn Sie stattdessen vor einem Klick prüfen möchten, ob das Element zu diesem Zeitpunkt verdeckt ist, versuchen Sie, ob Ihnen die Eigenschaften ''Is Displayed'' oder ''Is Enabled'' weiterhelfen.

==Kein Update nach Aktion==
Über den Recorder wurde eine Aktion ausgeführt, für die auch ein Baustein aufgezeichnet wurde, der Recorder zeigt aber immer noch das alte Bild.
:Der Recorder zeigt kein Livebild des Geräts, sondern immer nur eine Momentaufnahme. Nachdem eine Aktion ausgeführt wurde, aktualisiert sich der Recorder automatisch. Es kann aber vorkommen, dass das Bild schon aktualisiert wurde, bevor die Auswirkungen der Aktion auf dem Gerät vollständig abgeschlossen sind. In diesem Fall sollten Sie den Recorder von Hand aktualisieren über das Symbol mit den blauen Pfeilen. Ab expecco 20.2 können Sie für diesen Fall auch automatisches Aktualisieren einstellen. Siehe auch Beschreibung zum [[#Recorder|Recorder]].

=="clickable" Attribut falsch==
Ein Element hat im "''clickable''" Attribut/Property den Wert "''false''", ist aber dennoch anklickbar.
:Das "''clickable''" Attribute muss explizit vom App-Programmierer gesetzt werden, und hat tatsächlich keine Relevanz für das tatsächliche Verhalten der App. Sie sollten dieses Attribut i.A. in Ihren Tests nicht beachten. Leider existieren viele Apps, bei denen der Programmierer hier "lazy" war.

==Verbindungsaufbau schlägt fehl==
Schlägt der Verbindungsaufbau mit dem Appium-Server fehl, erhalten Sie in expecco eine Fehlermeldung ähnlicher der unten abgebildeten.

[[Datei:MobileTestingVerbindungsfehler.png]]

Hier sehen Sie die Art des aufgetretenen Fehlers. Klicken Sie auf "''Details''" um nähere Informationen zu erhalten. Mögliche Fehler sind:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:Der angegebene Server läuft nicht oder ist nicht erreichbar. Überprüfen Sie die Serveradresse.
*''org.openqa.selenium.WebDriverException''
:Lesen Sie in den Details in der ersten Zeile die Meldung hinter ''Original Error'':
:*''Unknown device or simulator UDID''
::Entweder ist das Gerät nicht richtig angeschlossen oder die udid stimmt nicht.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::Dieser Fehler kann verschiedene Ursachen haben. Entweder konnte tatsächlich der WebDriverAgent nicht gebaut werden, weil die Signierungseinstellungen falsch sind oder das passende Provisioning Profile fehlt. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]]. Es kann auch sein, dass der WebDriverAgent auf dem Gerät nicht gestartet werden kann, weil sich beispielsweise ein Alert im Vordergrund befindet oder Sie dem Entwickler nicht vertraut haben.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::Die angegebene App kann nicht auf dem iOS-Gerät installiert werden, weil es nicht im Provisioning Profile der App eingetragen ist.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.'''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die Datei unter dem angegebenen Pfad auf dem Mac befindet.
:*''packageAndLaunchActivityFromManifest failed.''
::Die angegebene ''apk''-Datei ist vermutlich kaputt.
:*''Could not find app apk at [...]''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die ''apk''-Datei am angegebenen Pfad befindet.

Falls der Fehler nicht durch eine der oben gelisteten Ursachen bedingt ist, kann es sein, dass die auf dem Gerät befindlichen Automation-Anwendungen nicht mehr richtig funktionieren. Hier hilft es, diese vom Mobilgerät zu deinstallieren. Beim nächsten Verbindungsaufbau werden sie dann automatisch neu installiert.

*Für iOS-Geräte ist das der WebDriverAgent, den Sie einfach vom Home-Screen deinstallieren können. Dies behebt in der Regel Probleme durch den Wechsel des verwendeten Macs oder der Xcode-Version.

*Für Android-Geräte ist es der UIAutomator2; hier tritt auf einigen Geräten sporadisch ein Problem auf, die Ursache dafür ist uns z.Z. noch nicht bekannt. Zur Deinstallation navigieren Sie auf dem Gerät zu "''Einstellungen''" > "''Anwendungen''"* und suchen in der Liste nach folgenden Einträgen:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Klicken Sie auf die jeweilige Anwendung und dann auf "''Deinstallieren''".
*''Der entsprechende Eintrag heißt auf manchen Geräten möglicherweise etwas anders.''

Falls dies nicht hilft, kann eventuell die Ausgabe des Appium-Servers weiterhelfen. Für einen von expecco gestarteten Server finden Sie das Log in der Liste der [[#Laufende_Appium-Server|laufenden Appium-Server]].

==Ich habe keinen Mac==
Vielleicht hilft Ihnen diese Webseite weiter: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin/en

2023-11-30T11:57:56Z

Matilk: /* Signing WebDriverAgent */ wdaLaunchTimeout

[[Mobile_Testing_Plugin|Deutsche Version]] | '''English Version'''

= Introduction =
With the ''Mobile Testing Plugin'' applications can be tested on Android and iOS devices. This includes both real and emulated devices. It does not matter whether real mobile devices or emulated devices are used. The plugin can (and usually is) used in conjunction with the [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]], which supports the creation of tests. It can also be used to record test procedures.

[http://appium.io/ Appium] is used to connect to the devices. Appium is a free open source framework for testing and automating mobile applications.

We recommend to go through the [[Mobile_Testing_Tutorial/en|Tutorial]] to familiarize yourself with the Mobile Plugin. This tutorial leads step by step through the creation of a test case using an example and explains the necessary basics.

= Installation and Setup =
To use the ''Mobile Testing Plugin'', you must have installed expecco together with the corresponding plugin, and you need the appropriate licenses. expecco communicates with the mobile devices via an Appium server, which either runs on the same computer as expecco, or on a second computer. This must be accessible for expecco.

== Installation Overview ==
'''Computer running expecco:'''
* Java JDK version 8, 9, 10 or 11
'''Computer connected to Android devices :'''
* Appium Server, you can install it via the Mobile Testing Supplement (see below), of which we regularly provide a new version
* Android SDK, you can also get it with the Mobile Testing Supplement
* Java JDK version 8, 9, 10 or 11
'''Computer connected to iOS devices*:'''
* Appium Server, you can install it via the Mobile Testing Supplement for MacOS (see below), of which we regularly provide a new version
* Xcode in a version that supports the iOS version used, available from the Apple App Store
* Java JDK version 8, 9, 10 or 11
* Apple Developer Certificate incl. matching private key (to sign the WebDriverAgent)
* Provisioning Profile for the mobile devices to be used

* Please note that due to the requirements (no connection to non-Apple devices available) iOS devices can only be controlled from a Mac.

Depending on the setup, the above-mentioned computers can also be the same device. expecco can either connect to a remote Appium Server and mobile devices connected to it via the network, or start an Appium Server locally itself and use it with local mobile devices. However, some of expecco's functions that make it easier to create test cases are only available if the mobile devices are connected to the same computer on which expecco is running. A possible setup may therefore look like the following figure:

[[Datei:MobileTestingAufbau.png | 400px]]

The following explains how to install Appium and other necessary applications for Windows and Mac OS.

== Windows ==
The easiest way is to install everything from our Mobile Testing Supplement. However, newer versions do not contain a JDK anymore due to a change in Oracle's license terms, so you have to install it additionally. Of course, you are free to install Appium directly to use the version you want. However, to then be able to start an Appium server with expecco, a suitable batch file must be available and specified in the [[Mobile_Testing_Plugin/en#Plugin_Configuration|settings]]. However, connections can also be established to other running Appium servers.
*'''expecco 23.1''': [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Same versions as in the predecessor, but the installer now allows to add Appium to the Autostart.
*expecco 22.2 and 22.1: [https://download.exept.de/transfer/h-expecco-22.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 from platform-tools 33.0.2
:''* We added the capability'' startChromedriverTimeout ''to Appium, to get a timeout earlier, if Chromedriver cannot be initialized. (see [[#startChromedriverTimeout|Problems and Solutions]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Contains Appium version 1.22.0, Node still is version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Only minor changes compared to the previous version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Compared to the previous version, Appium was updated to version 1.16.0-rc.1 and node 12 is used.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:This installs Appium in the version 1.12.0 and now additionally contains build-tools in the version 28.0.3 in the android-sdk. Apart from this, it is the same as the previous version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:This installs Appium in the version 1.8.1. In addition, an installation of ''Android Debug Bridge'' and ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) is offered. This covers drivers for a broad range of Android devices, and you won't have to install an individual driver for each device. A '''JDK is not contained anymore (due to a change in Oracle's license terms)''', you have to download it on your own, e.g. from [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: same procedure as for expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:This installs a Java JDK Version 8, android-sdk and Appium Version 1.6.4. The supplement also offers a universal adb driver ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]). This driver supports a wide range of Android Devise, and avoids the need to search for individual device-specific drivers.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:It installs a Java JDK version 8, android-sdk and Appium version 1.4.16. During the installation the graphical user interface of Appium is started, you can close this window immediately. The supplement also offers a universal adb driver (ClockworkMod). This combines drivers for a wide range of Android devices so that you do not have to search for and install a separate driver for each device.

If expecco has to use mobile devices that are connected to another computer, you have to start an Appium server there. You can do this by using the file <code>appium_standalone.cmd</code>. The server is then started on default port 4723. If you want to use a different port number, start the server with

appium_standalone.cmd -p <portnummer>

The server is ready, as soon as the line
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
is displayed, where you can read the used port number at the end.

If your Android device is connected to a remote machine,
you may want to see the live screen locally using a tool like
[https://github.com/Genymobile/scrcpy scrcpy].

When Appium is started for the first time – either standalone or by expecco – it may happen that the Windows firewall blocks access to the node server. Allow the access or Appium cannot be started.

== Mac OS ==
Note: the following can be ignored if you do not plan to test iOS (iPhone) devices. The Mac setup is not needed for Android devices.

=== Xcode ===
Automation with iOS devices needs [https://developer.apple.com/xcode/ Xcode]. You can install it from the App Store. Please make sure that the version matches the tested iOS versions.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
This table is only a simplified overview, better see [https://xcodereleases.com/ Xcode releases] or [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode versions] for the exact versions. For new iOS minor versions, there is usually also a new release of Xcode, e.g. for iOS 10.2 you need at least Xcode 8.2, for iOS 10.3 at least Xcode 8.3, etc. So if you are upgrading to a newer iOS version, you will usually need a newer Xcode version as well. Newer versions of Xcode may not run on older operating systems, which in turn may require an operating system upgrade. If you also want to test older iOS versions, it can be useful to install the corresponding Xcode versions in parallel.

=== Appium ===
You can install Appium either as command-line tool or use it with [https://github.com/appium/appium-desktop Appium Desktop], which provides a GUI to start the server. Meanwhile there is also Appium 2.0, which is not tested with expecco yet and therefore not recommended to use.

==== Appium Desktop ====
Download the newest version of [https://github.com/appium/appium-desktop/releases/ Appium Desktop]. For the Mac, it is best to take the dmg file and install it to the applications. When starting ''Appium Server GUI'' you will probably get the error message, that it is not possible for security reasons. In this case, open the context menu of the app file (right click or Ctrl + click) and choose ''Open'' there. Then confirm that you really want to open the application. From now on you can open the application normally.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Since Xcode 14 there are problems with signing the WebDriverAgent, which Appium loads on the device for the automation. This means that no connection is possible with version 1.22.3-4 of Appium Desktop. In newer versions of WebDriverAgent, this problem is solved, but currently there is no version of Appium Desktop using such a new version (as of November 2022). However, you can manually download a new version (e.g. 4.10.2) and replace the files in Appium. To do this, download one of the two archive files (zip or tar.gz) containing the source code from the [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent download page]. Then open and extract this file. Copy the contents of the folder ''WebDriverAgent-4.10.2' to

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

If you navigate there by Finder, make a context click (right click or Ctrl + click) on the application and choose ''Show Package Contents'' from the menu. Replace all files that are already present with the same name.

==== Install Appium using npm ====
You can install Appium using npm (Node Package Manager) as well. To do this, you have to install node/npm first. This can be done using [https://github.com/nvm-sh/nvm nvm] (Node Version Manager), which you can get on Github. If the following installation instructions should not work for you, you will find detailed information in the [https://github.com/nvm-sh/nvm#readme Readme] there.

Open a Terminal window. Then clone the Github repository of nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
and load it
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Then execute
command -v nvm
to see if it works. It should print ''nvm''. If there is no response, execute
touch ~/.zshrc
and try again.

Now you can install node with the following command.
nvm install 16.15.1
As there are problems installing Appium using the newest version of node, we recommend this version.

After node is installed, you can use it to install Appium:
npm install -g appium

The Appium server now simply can be started with the command
appium
The output will then be written directly to the terminal.

This version also has problems with signing the WebDriverAgent, like explained in [[#Appium_Desktop | Appium Desktop]]. Therefore download a newer version of WebDriverAgent in this case as well and replace the old files. You will find them at
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
We provide older versions of Appium via the Mobile Testing Supplement for Mac OS, with which you can easily install it:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.2)]
:Contains Appium version 1.18.3 and uses node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.0)]
:Only a few changes compared to the previous version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.98)]
:Appium is updated to version 1.16.0-rc.1 and node 12 is used.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.96)]
:This version contains Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.94)]
:This version contains Appium 1.8.0.

* expecco 2.11:[http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.0.94)]
:This version contains Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement for Mac OS]
:Diese Version entält Appium 1.4.16.

After you have downloaded the supplement, you can move it to a directory of your choice (e.g. your home directory) and unpack it there. A suitable command in a shell could look like this, adjust the version number accordingly:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

If your default Xcode installation is the one you want to use, you can start Appium directly from the file in the ''bin'' directory with the appropriate version number:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

If you want to use another Xcode than the one configured as default, you have to tell Appium the corresponding path by using the environment variable ''DEVELOPER_DIR''. For example, if you have installed Xcode in ''/Applications/Xcode-11.3.app'', you can start Appium this way:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

To find out what is set as the default Xcode installation on your system, use this command:

xcode-select -p

If Appium cannot find your Xcode installation, a message like this appears:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
In such a case, restart Appium by specifying a valid ''DEVELOPER_DIR''.

==== Signing WebDriverAgent ====
For automation, Appium installs an App called WebDriverAgent on the device and therefore has to be able to sign it. You need an Apple account and a respective certificate for this. For evaluation you can use a free account. This has the disadvantage that created profiles are only valid for one week and must be recreated afterwards. Also be careful when sharing the account, as certificates may be revoked or invalidated by automatic generation. As a result, apps that have already been signed can no longer be used.

If you already have a respective certificate and its associated private key in your keychain on the Mac, you can have the WebDriverAgent automatically signed. If not, it is recommended to set and manage the signing using Xcode.

First, connect the device you want to use to your Mac via USB. Make sure both the Mac and the device are in the same network or there will be problems when connection with Appium. Start Xcode and open ''Preferences''. Go to the Accounts page and create an entry with your account. You can then click on ''Manage Certificates...'' to see the certificates that belong to that account. To run tests, you need an iOS Development Certificate and the associated private key. If you do not already have one, create one. If you already have one, but it is not in your keychain (indicated by "Not in Keychain"), you can import it. You can do that by the [https://support.apple.com/en-us/guide/keychain-access/welcome/mac keychain access] on your Mac, if you have exported it previously from the keychain, where it is stored. The certificate with the associated key should be in the keychain ''Login''. It can be exported from there as PKCS#12 file (typical ending .p12). To import a certificate into your keychain, select the option ''Import objects'' from the ''File'' menu. If you don't know where the certificate is stored, you can also revoke it in Xcode and recreate it in your keychain. However, only do this if you know that the old certificate is no longer in use because it can no longer be used afterwards. Now the keychain should contain an iOS development certificate.


Now open the WebDriverAgent project in Xcode. If you have installed the Mobile Testing Supplement, you will find it in this directory at
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
If you have installed Appium Desktop, you will find it at
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''

You can use the Finder to navigate to the Xcode project file and open it by double clicking. Note, that you have to perform a context click (right click or Ctrl + click) on the Appium Server GUI app and select ''Show Package Contents'' in the menu, to get to its subdirectory.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Select ''WebDriverAgentLib'' and the page ''Signing & Capabilities''. In the section ''Signing'' set the option ''Automatically manage signing'' and then select a team. Now switch to ''WebDriverAgentRunner'' and do the same there.

By setting the team, the errors showing up for WebDriverAgentRunner should disappear. If Xcode should not be able to create a Provisioning Profile matching the Bundle ID ''com.facebook.WebDriverAgentRunner'', you can edit the latter so that it fits your certificate. After that you can quit Xcode or you can, like explained further below, directly start the build in Xcode, so the project will be already built when Appium wants to use it.

If you now connect to your device from expecco, the WebDriverAgent will be installed and started on it and then switch to the app to be tested. You may still have to trust the execution of the WebDriverAgent on the device. It maybe a sign that you have to do this, if the app WebDriverAgent first appears on the device and tries to start, but then is uninstalled again. To trust the execution, open the settings during the connection setup on the device and then the entry ''Device management'' under ''General''. This entry is only visible if a developer app is installed on the device. You may therefore have to wait until the WebDriverAgent is installed before the entry appears. Select the entry of your Apple account and trust it. Since the WebDriverAgent will be uninstalled again if the start did not work, you have to do this during the connection setup. If this is too hectic for you, you can also execute the following code:

xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

or
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

This installs the WebDriverAgent on the device without deleting it again.

If there are problems while installing the WebDriverAgent, you can also try and start the build in Xcode. Make sure the right target ''WebDriverAgent'' is selected. Error messages in Xcode might indicate easier what the problem is about. Sometimes it even helps to try for a second time, if it took too long for the first time and got aborted. It may occur, that you are asked several times during the build to enter the password for the keychain.

[[Datei:WebDriverAgentCodesign.png]]

Read also the documentation of Appium on [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Setting up tests with iOS devices]. Refer to the [https://support.apple.com/en-us/HT204460 Apple documentation] for details on installing and trusting of apps.

Once the WebDriverAgent is installed on the device, it will be reused for later connections und connecting should work faster. The signed version is then already on your Mac as well and doesn't have to be built again. This should speed up the connect with other devices as well. If you know, that the connect has to build and sign the WebDriverAgent first, it is advisable to set the capability ''wdaLaunchTimeout''. This timeout specifies how long Appium waits for the WebDriverAgents to start up on the device and is per default set to 60000 ms. Building often takes a little longer than one minute, so the connect attempt will be canceled. A value of 120000 will be more reliable here.

== Plugin Configuration ==
Before you start, please check the settings of the Mobile Testing Plugin and adjust them if necessary. Select the menu item "''Extras''" → "''Settings''" → "''Extensions''" → "''Mobile Testing''" (see fig.). By default, these paths are found automatically (1). To adjust a path manually, deactivate the corresponding check mark at the right. You'll see a drop-down list with some paths to choose from. If an entered path is wrong or cannot be found, the field is marked red and a message appears. Make sure that all paths are specified correctly.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Plugin Configuration]]

*'''appium''': Enter the path to the executable file with which Appium can be started in the command line. Under Windows this file will usually be called "<code>appium.cmd</code>". This path is used when expecco starts an Appium server.
*'''node''': Enter the path to the executable that starts Node (also called (also called "Node.js"). This path is passed to Appium when a server is started so that Appium can find it independently of the PATH variable. Under Windows this file is usually called "<code>node.exe</code>".
*'''JAVA_HOME''': Enter the path to a JDK (Java Development Kit)here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable. To specify which Java should be used by expecco, set this path in the Java Bridge settings.
*'''ANDROID_HOME''': Enter the path to an Android SDK here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable.
*'''adb''': The path to the adb command. Under Windows the file is called "<code>adb.exe</code>". This file is used by expecco, for example, to get the list of connected devices. This path should be selected automatically, if the command is found in the ANDROID_HOME directory. This is also used by Appium. If expecco and Appium use different versions of adb, conflicts may occur.
*'''android.bat''': This file is only needed to start the AVD and the SDK Manager, which deal with phone emulators. The file in the ANDROID_HOME directory will be selected automatically, if present there.
*'''aapt''': The path to the "aapt" command here. Under Windows this file is called "<code>aapt.exe</code>". expecco uses "aapt" only in the connection editor to read the package and activities of an "apk" file. The file in the ANDROID_HOME directory will be selected automatically, if present there.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | JDK Configuration]]

Starting with expecco 2.11, there is an additional field called ''Team ID''. If you run iOS tests, enter the Team ID of your certificate here. This is used for every iOS connection, unless you change the value in the connection settings in individual cases. For information on how to obtain the team ID, please refer to the section on [[#Signing| signing]] for installations on Mac OS. With expecco 2.10 and older, you can only enter the Team ID as capability for each connection setting separately. However, you must use the [[#Extended_View|extended view]] to do this. Enter the capability ''xcodeOrgId'' here and set the Team ID of the certificate as value.

The server address setting at the bottom of the page refers to the behavior of the connection editor. It checks at the end whether the server address ends in ''/wd/hub'' as this is the usual form. If not, a dialog asks how to react. The defined behavior can be viewed and changed here.

Also switch to the entry ''Java Bridge'' (see figure). Here you have to specify the path to your Java installation, which is used by expecco. Enter a JDK here. If you want to use the one from the Mobile Testing Supplement under Windows, the path is
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
You can also use the system settings.

== Prepare Android Device ==
If you connect an Android device under Windows, you may still need an adb driver for the device. You can usually find a suitable driver on the manufacturer's website. If you have installed the universal driver from the Mobile Testing Supplement, everything should already work for most devices. In some cases, Windows will automatically try to install a driver when you connect the device for the first time. 
'''Attention''': Before you can control a mobile device with the Appium plugin, you have to allow this debugging!

For Android devices, you can find this option in the settings under ''[https://developer.android.com/studio/debug/dev-options Developer Options]'' called ''USB-Debugging''. If the developer options are not displayed, you can unlock them by tapping Build Number seven times in About the Phone.

Also enable the ''Stay awake'' feature to prevent the device from turning off the screen during test creation or execution.

For security reasons, USB debugging must be allowed for each computer individually. When connecting the device to the PC via USB, you must agree to the connection on the device. If you haven't done this for your computer yet, but no corresponding dialog appears on the device, it may help to unplug and reconnect the device. This can happen especially if you have installed the ADB driver while the device was already connected via USB. If this doesn't help either, open the notifications by dragging them from the top of the screen. There you will find the USB connection and you can open the options. Select another type of connection; usually MTP or PTP should work.

You can also test on an emulator. It does not need to be prepared separately, as it is already designed for USB debugging. It is even possible to start an emulator at the beginning of the test.

To check if a device you have connected to your computer can be used, open the [[#Connection_Editor|connection editor]]. The device should be displayed there.

=== Connection via WLAN ===
It is possible to connect to Android devices via Wireless LAN. For devices using Android 11 or newer, this can be done wirelessly, else you have to connect initially via USB. Since expecco 22.1, WiFi connections can be established using the [[Mobile_Testing_Plugin/en#Connection_Editor|Connection Editor]]. It is also possible to do this using a command window.
==== Wireless Connect (Android 11) ====
In the developer options of your device, enable wireless debugging and open its options. You initially have to pair your machine with the device. To do this, choose "''Pair device with pairing code''" to get a pairing code and an IP address with port. Then open a command window (terminal window) on your machine and enter:
<nowiki>adb pair <Device IP Address>:<Pairing Port></nowiki>
where <tt><Device IP Address>:<Pairing Port></tt> is the IP address and port as shown on the device. After that, you will be asked for the pairing code. If everything went right, the popup on the device should have closed and your machine is added to the list of paired devices. Then enter at the command window:
<nowiki>adb connect <Device IP Address>:<Debugging Port></nowiki>
The IP address is the same as for pairing, but the port is different. Both are shown as IP address & Port on the device. The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted. Restarting the device often disables wireless debugging and the used port is changed. The pairing, however, is permanent and has not to be done again the next time you connect.
==== Start via USB ====
First, connect your device via USB. Then open a command window (terminal window) and enter:
<nowiki>adb tcpip 5555</nowiki>
The device listens for a TCP/IP connection on port 5555. If you have several devices connected or emulators running, you have to specify which device you mean. Enter in this case:
<nowiki>adb devices -l</nowiki>
to get a list of all devices, where the first column gives the device's ID.
Then, enter:
<nowiki>adb -s <deviceID> tcpip 5555</nowiki>
with the device identification of the desired device. You can now disconnect the USB connection. Now you have to find out the IP address of your device. You can usually find it somewhere in the device's settings, for example in the Status or WLAN settings of the phone. Then type in:
<nowiki>adb connect <IP address of device></nowiki>
The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> again or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted.

== Preparing an iOS-Device and App ==
Control of iOS devices is only possible via a Mac. Please also read the section [[#Mac_OS|Installation under Mac OS]].

Before you can control a mobile device with the Mobile Testing Plugin, you must allow debugging for iOS devices with iOS 8 or higher. Activate the option "''Enable UI Automation''" under the "''Developer''" menu in the device settings. If you cannot find the "''Developer''" entry in the settings, proceed as follows: Connect the device to the Mac via USB. If necessary, you must still agree to the connection on the device. Start Xcode and then select "''Devices''" from the menu bar at the top of the screen in the "''Window''" menu. A window opens in which a list of the connected devices is displayed. Select your device there. Then the entry "''Developer''" should appear in the settings on the device. You may have to exit the settings and restart.

[[Datei:Alert.png | thumb | 270px | Alert unter iOS]]
It is not possible to establish a connection to the device as long as it shows certain alerts. Such an alert may appear if FaceTime is activated (by displaying a message about SMS charges as shown in the screenshot). Be sure to configure the device so that it does not show such alerts when idle.

=== expecco 2.11 and later ===
You can test any app which is executable or already installed on the device used. If the app is available as a development build, the UDID of the device must be stored in the app. In any case, the WebDriverAgent must be signed for the device. Please read the section about [[#Signing|signing]] under Mac OS.

If you want to use the Home button in a test, you must activate "AssistiveTouch" on the device. You will find this option in the settings under "''General''" > "''Operating Help''" > "''AssistiveTouch''". Then place the menu in the middle of the upper edge of the screen. You can then record pressing the Home button with the corresponding menu entry in the recorder or use the "''Press Home Button''" block directly.

=== expecco 2.10 ===
The app you want to use must be available as a development build. The UDID of the device must also be stored in the app.

=== Sign the development build ===
A development build of an app is only allowed for a limited number of devices and cannot be started on other devices. However, it is possible to exchange the certificate and the usable devices in a development build.

* Evaluation with demo app of eXept:
:We will be happy to provide you with a demo app which is available as a development build and which we can sign for your device. Please send the UDID of your device to your eXept contact person. How to determine the UDID of your device is described in the following section.

* Using your own app for your test device:
:If you receive a development build (IPA file) from the app developers that is approved for your test device, you can use it directly. To do this, you must tell the developers the UDID of your device so they can enter it. '''You can use Xcode to read the UDID of a device'''. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window opens in which a list of the connected devices is displayed. Select your device and search for the ''Identifier'' entry in Properties. The UDID is a 40-digit hexadecimal number.

* Externally developed app for your test device:
:You can also re-sign apps to make them run on other devices. However, this process is complicated and requires access to an Apple Developer account. A documentation on the procedure is currently in preparation.

:For the evaluation we will gladly support you with the re-signing of your app..


For more information about using iOS devices, see also the
[http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Appium documentation].

=== Native iOS-Apps ===
You can also use apps that are already natively present on the device. To do this, you must know their bundle ID and then enter it in the connection settings. Here is a small selection of common apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

You can find further Bundle-IDs [https://github.com/joeblau/apple-bundle-identifiers here].

= Examples =
In the demo test suites for expecco you will also find examples for tests with the Mobile Testing Plugin. To do this, select the option "''Example from File''" on the start screen and open the folder named "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
The test suite contains two simple test plans: "''Simple CalculatorTest''" and "''Complex Calculator and Messaging Test''". Both tests use an Android emulator, which you must start before starting. The apps used in the test are part of the basic equipment of the emulator and therefore no longer need to be installed. Since the apps may differ under every Android version, it is important that your emulator runs under Android 6.0. In addition, the language must be set to English.

; Simple CalculatorTest
: This test connects to the calculator and enters the formula ''2+3''. The result of the calculator is compared with the expected value ''5''.

; Complex Calculator and Messaging Test
: This test connects to the calculator and then opens the message service. There it waits for an incoming message from the number ''15555215556'', in which a formula to be calculated is sent. The message is generated before via a socket at the emulator. When the message arrives, it is opened by the test and its contents are read. Then the calculator is opened again, the received formula is entered and the result is read. The test then switches back to the message service and sends the result as an answer.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
These are part of the tutorial for the Mobile Testing Plugin. The included test case is incomplete and will be added during the tutorial. Please read the section [[#Tutorial|Tutorial]].

= Tutorial =
There is a tutorial describing the basic procedure for creating tests with the Mobile Testing Plugin. It is based on a supplied example consisting of a simple app and an expecco test suite.

You find it on the page [[Mobile_Testing_Tutorial/en|Mobile Testing Tutorial]] in two versions for Android and iOS devices.
*  [[Mobile_Testing_Tutorial/en#First_steps_with_Android|First steps with Android]]
*  [[Mobile_Testing_Tutorial/en#First_steps_with_iOS|First steps with iOS]]

= Dialogs of the Mobile Testing Plugin =
== Connection Editor ==
You can use the Connection Editor to quickly define, change, or establish connections. Depending on the task, the dialog has small differences and is opened differently:
*If you want to establish a connection, access the dialog in the GUI browser by clicking on ''Connect'' and then selecting ''Mobile Testing''.
*To change or copy an existing connection in the GUI browser, select it, right-click and select ''Edit Connection'' or ''Copy Connection'' from the context menu.
*If you do not want to create connection settings for the GUI browser but for use in a test, choose ''Create Connection Settings'' from the Mobile Testing Plugin menu.... This only allows you to create the settings for a connection without creating a connection in the GUI browser.

The Connection Editor menu has several buttons, some of which are only visible when creating connection settings:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#''Delete Settings'': Resets all entries. (Only visible when creating settings.)
#''Load settings from file'': Allows to open a saved settings file (*.csf). Its settings are transferred to the dialog. Entries already made without conflict are retained.
#''Load settings from attachment'': Allows you to open an attachment with connection settings from an open project. These settings are applied to the dialog. Entries already made without conflict are retained.
#''Save settings to file'' and
#''Save settings to attachment'': Here you can save the entered settings to a file (*.csf) or create them as an attachment in an open project. Both options have a delayed menu in which you can choose to save only a certain part of the settings. (Only visible when creating settings.)
#''Advanced View'': Allows you to switch to the advanced view to make additional settings. Read more about this at the end of this chapter. (Only visible when creating settings.)
#''Help'': A help text for the respective step is shown or hidden on the right side.

The dialog is divided into three steps. In the first step you select the device you want to use, in the second step you select which App should be used and in the last step the settings for the Appium server are made.

===Step 1: Select Device ===
In the upper part you will see a list of all connected Appium devices that are detected. With the checkbox below you can hide devices that are detected but not ready. If you want to enter a device that is not connected, you can create it with the corresponding button ''Enter Android device'' or ''Enter iOS device''. However, you need to know the required properties of your device. The device is then created in a second device list and can be selected there. If no list with connected elements can be displayed, various messages are displayed instead:
*No devices found
*:expecco could not find any Android devices.
*:To automatically configure a connection to a device, make sure
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*No available devices found
*:expecco could not find any available Android devices. But not available ones were found, e.g. with the status "unauthorized".
*:To configure a connection to a device automatically, make sure that
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*:To view unavailable devices, enable this option below.
*Connection lost
*:expecco has lost the connection to the adb server. Try to re-establish the connection by clicking on the button.
*Connection failed
*:expecco could not connect to the adb server. Possibly it is not running or the specified path is not correct.
*:Check the adb configuration in the settings and try to start the adb server and establish a connection by clicking on the button.
*Connect ...
*:expecco connects to the adb server. This may take a few seconds.
*Start adb-Server ...
*:expecco starts the adb-Server. This may take a few seconds.

With ''Next'' you get to the next step. If you enter settings for the GUI browser, this is only possible once a device has been selected.

Note on unlocking: In newer Android versions the developer options are no longer offered in the settings at first. If your Android device does not show an entry for "''Developer options''" in the settings, first select the entry "''Phone info''", then "''SoftwareVersionsInfo''" and click on the entry "''BuildVersion''" several times.

==== Manage Chromedrivers ====
If the App you want to automate uses WebViews with Chrome, Appium needs to have access to an appropriate Chromedriver. If you have selected a device in the list, you can use "''Manage Chromedrivers''" to see, which Chrome versions are installed on the device and which Chromedriver versions are provided by expecco. With this dialog you can also download required Chromedriver versions. Beware that there may be several Chrome versions on the device. An App doesn't have to use the version of the installed Chrome browser for its WebViews. The Chromedriver you use should fit your app for everything to work properly. You can also change the path to the Chromedriver in the capabilities generated at the end of the connection editor.

==== Connect WiFi Android Device ====

You can connect to Android devices using WiFi as well. In this case, the device has to be connected to ADB first, see [[Mobile_Testing_Plugin/en#Connection_via_WLAN|Connection via WLAN]]. Since expecco 22.1, the connection editor provides a dialog helping to set this up, which can be used instead of the command window. For devices using Android 11 or newer, you can pair the device with your machine here by specifying the appropriate parameters and then establish the connection by specifying the IP address and port. You can also use this to establish a wireless connection for devices that are connected via USB. When you select the corresponding device in the list, the required information is read out automatically.

Note that establishing a wireless connection is not part of the connection settings. If you want to establish a new connection with the generated settings, you must make sure that the device is connected to ADB with the specified IP address and port so that it can be found. The ADB connection will be lost if the ADB server or the device are restarted. The permission for wireless debugging is also often reset when the device is restarted and the debug port can then change. Therefore, a wireless connection must always be established manually.

===Step 2: Select App===
Here you can enter information about the app to be tested. You can decide if you want to use an app that is already installed on the device or if you want to install an app for the test. Select the appropriate tab above. Depending on whether you selected an Android or an iOS device in the previous step, the required input will change.

*'''Android'''
**''App on Device''
**:If you have selected a connected device in the first step, the packages of all installed apps are automatically retrieved and you can select from the drop-down lists. The installed apps are divided into third-party packages and system packages; select the appropriate package list. This selection does not belong to the settings, but only provides the corresponding package list. You can use the filter to further narrow down the list and then select the desired package. The activities of the selected package are also automatically retrieved and made available as a drop-down list. Select the activity you want to start. As a rule, an activity is automatically entered from the list. If you are not using a connected device, you must enter the package and the activity manually.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. If you are using a local Appium server, you can use the right button to navigate to the App installation file and enter this path. If possible, the corresponding package and the activity are also entered in the fields below. However, this entry is not necessary.

*'''iOS'''
**''App on Device''
**:Specify the bundle ID of an installed app. You can find out the IDs of the installed apps using Xcode, for example. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window will open displaying a list of connected devices. If you select your device, you will see a list of the apps you have installed in the overview.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. For the requirements of apps for real devices, please read the section [[#iOS-Ger.C3.A4t_and_App_Preparing|Preparing an iOS-Device and App]].

In the lower part you can specify whether the app should be reset or uninstalled when the connection is terminated, and whether it should be reset initially. Again, the corresponding capability is not set if you select ''(Default)''. With ''Next'' you get to the next step.

===Step 3: Server Settings===
In the last step, a list of all the capabilities that result from your entries in the previous steps is first displayed in the upper part. If you are familiar with Appium and want to set additional capabilities that are not covered by the connection editor, you can click on ''Edit'' to open the extended view. See the section below for more information.

If you enter settings for the GUI browser, you can enter the ''Connection name'' with which the connection is displayed. This is also the name under which devices can use this connection when it is established. If you leave the field blank, a name will be generated. If the box "''Managed by expecco''" is checked, expecco will start a local Appium server on a free port, or use a free server that has already been started. To use your own server, turn this feature off and enter the appropriate address. You will get the local default address and already used addresses to choose from.

In older expecco versions the box is labeled "''Start on demand''". In this case, you must also enter an address if you want expecco to start the server. expecco then tries to start an Appium server at the given address when connecting, if none is running there yet. This server will then also be shut down when the connection is terminated. This only works for local addresses. Make sure that you only use port numbers that are free. It is best to only use odd port numbers from the standard port 4723. The following port number is also used when establishing a connection, which could otherwise lead to conflicts.

Depending on how you opened the dialog, there are now different buttons to close it. In any case you have the option to save. This opens a dialog where you can either select an open project to save the settings there as an attachment, or choose to save it to a file that you can then specify. Saving does not close the dialog, allowing you to select another option.

If you have opened the editor for establishing a connection, you can finally click on ''Connect'' or ''Start and connect server'', depending on whether the check mark for server start is set. For changing or copying a connection in the GUI Browser, this option is called ''Apply'', since in this case only the connection entry is changed or created, but the connection setup is not started. If necessary, you can do this afterwards via the context menu. If you have changed capabilities of an existing connection, a dialog then prompts you to decide whether these changes should be applied directly by closing the connection and establishing the new connection or not. In this case, the changes only take effect after you reestablish the connection.

To use the connection editor, also read the corresponding section in the respective tutorial in step 1. (Android: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo|Run Demo]], iOS: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo_2|Run Demo]]).

===Extended View===
The extended view of the connection editor can be obtained either by clicking on ''Edit'' in the third step or at any time via the corresponding menu item if you have started the editor via the plugin menu. This view displays a list of all configured Appium Capabilities. You can add, change or remove further entries to this list. To add a capability, select it from the drop-down list of the input field. In this list all known capabilities are sorted into the categories ''Common'', ''Android'' and ''iOS''. If you have selected a capability, a short information text is displayed. You can also enter a capability manually in the field. Then click on ''Add'' to add the capability to the list. There you can set the value in the right column. To delete an entry, select it and click on ''Remove''. With ''Back'' you leave the extended view.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Running Appium Servers ==
In the menu of the Mobile Testing Plugin you will find the entry ''Appium-Server...''. This opens a window with an overview of all Appium servers started by expecco and on which port they are running. By clicking on the icon in the column ''Show Log'' you can view the logfile of the corresponding server. This is deleted when the server is shut down. With the icons in the column ''Exit'' the corresponding server can be terminated. However, this is prevented if expecco still has an open connection via this server. The rightmost column shows for which connection the server is in use. If it reads ''<idle>'', the server is currently not used by expecco.

[[Datei:MobileTestingAppiumServer.png]]

When opening the editor to start an Appium connection, an Appium server is started immediately to speed up the connection process. For this purpose, expecco always keeps one idle running Appium server. Additional running servers however, which are not in use anymore, will be terminated automatically after a while.

In the menu of the Mobile Testing Plugin you will also find the entry ''Close all Connections and Servers''. This is intended for cases where connections or servers cannot be terminated in any other way. If possible, always terminate connections in the GUI browser or by executing a corresponding block. Servers that you have started in the server overview should be terminated there; servers that were started with a connection are automatically terminated with this connection.

Note that only servers started and managed by expecco are listed in the overview. Possible other Appium servers that were started in a different way are not recognized.

== Recorder ==
If the GUI browser is connected to a device, the integrated recorder can be used to record a test section with that device. To start the recorder, select the appropriate connection in the GUI browser and click the Record button. A new window opens for the recorder. The recorded actions are created in the GUI browser work area. It is therefore possible to edit the recorded data in parallel.

[[Datei:MobileTestingRecorder.png|caption|]]

====Components of the Recorder Window====
#'''Continue/Pause Recording''': You can pause the recording by clicking the right icon. You will then see a large pause sign in the view. All actions that you perform now in the recorder are executed, but no blocks are recorded. You can switch back to normal recording mode by clicking the left icon.
#'''Stop Recording''': Stops the recording and closes the recorder window.
#'''Update''': Gets the current image and element tree from the device. This is necessary if the device takes longer to execute an action or if something changes without being triggered by the recorder. Since expecco 21.2, there is an additional submenu here that can be used to enable automatic update by checking for changes in the background (see also ''Automatic Update'' further below).
#'''Follow Mouse''': Select the element under the mouse pointer in the GUI browser.
#'''Element Highlighting''': The element under the mouse is outlined in red.
#'''Show Elements''': Show the borders of all elements in the view.
#'''Tools''': Selection, which tool is used for recording. The selected action is triggered with each click on the view. The following actions are available:
#*Element Actions:
#**Click: Short click on the element under cursor. To determine more precisely which element is used, use the Follow Mouse or Element Highlighting function.
#**Tap with Duration (Element): Similar to click, except that the duration of the click will be recorded as well. This allows the recording of long clicks.
#**Tap with Position (Element): Similar to click, but additionally records the position inside the element. The position can be recorded relative to the element size or, when pressing Ctrl while clicking, as absolute position from the upper left corner of the element.
#**Set Text: Allows to set the text of an input field.
#**Clear Text: Clears the text of an input field.
#*Device Actions:
#**Tap (Screen): Triggers a click at the screen position.
#**Tap with Duration (Screen): Triggers a click at the screen position, which also considers the duration.
#**Swipe: Swipe in a straight line from the point where you press the mouse button until you release it. The duration is also recorded.
#:Please note for this actions that the result may differ on different devices, e.g. with different screen resolutions.
#*Test Flow Blocks
#**Check Attribute: Compares the value of a specified attribute of the element with a predefined value. The result triggers the corresponding output.
#**Assert Attribut: Compares the value of a specified attribute of the element with a predefined value. If the values are not equal, the test fails.
#**Get Attribute: Gets the current value of a specified attribute of the element.
#*Auto
#:If the Auto tool is selected, you can use all actions by specific input methods: ''Click'', ''Tap Element'' and ''Swipe'' still work by clicking, but are distinguished by the duration and movement of the cursor. To trigger a ''Tap'', hold down Ctrl while clicking. The remaining actions are available in a context menu by right-clicking on the element.
#'''Context Actions''': Here you can record actions concerning contexts:
#*Switch to Context: Shows a list of all currently available contexts and you can select to which one you want to switch.
#*Get Current Context: Gets the handle of the current context.
#*Get Context Handles: Gets a list of all currently available contexts.
#'''Softkeys''': Only for Android. Simulates pressing the buttons Back, Home, Menu and Power.
#'''Home Button''': Only for iOS since expecco 2.11. Allows pressing the Home button.Prior to expecco 19.2, it only works if AssistiveTouch is activated and the menu is located in the middle of the upper screen border. From expecco 19.2 on, the function no longer uses AssistiveTouch.
#'''Help''': Opens this online documentation on the general page about [[GuiBrowser_Recorder/en|GUI Browser recorders]].
#'''View''': Shows a screenshot of the device. Actions are triggerd by mouse depending on the selected tool. If a new action can be recorded, the window has a green frame, else it is red.
#'''Resize Window to Image''': Resizes the recorder window so that the screenshot can be displayed completely.
#'''Resize Image to Window''': Scales the screenshot to a size that makes use of the full size of the window.
#'''Adjust Display''': Opens a dialog to adjust the displayed image, if expecco does not show it right. You can correct the scaling or rotate the image by 90°.
#'''Correct Orientation''': Corrects the image if it is upside down. Using the arrow to the right, the image can also be rotated by 90°, if this should ever be necessary. Since expecco 19.1 you find this functionality under ''Adjust Display''. The orientation of the image is irrelevant for the functionality of the recorder, it only works on the elements it receives.
#'''Scaling''': Changes the scaling of the screenshots.
#'''Messages''': Shows the path of the current selected element or other messages. It has a context menu to show a list of previous messages.

====Usage====
Each click in the window triggers an action and is recorded in the workspace of the GUI browser. There you can run, edit, or create a new block from what you have recorded. You find the actions to trigger softkeys directly in the menu bar (see above). To record actions on elements, either change the selection of the tool in the menu bar (see above) and then click on the element or select the corresponding action from the context menu by right-clicking on the corresponding element. For text input it is also possible to place the cursor over the element and enter the text. This opens the input dialog for this action. On how to use the recorder, see also step 2 in the tutorial ([[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_Block_with_the_Recorder|Android]] resp. [[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_block_with_the_Recorder_2|iOS]]).

====Hide elements====
Since expecco 21.2 it is also possible to hide the selected element in the recorder from the context menu. This means that this element cannot be selected from now on. This function is useful for ignoring elements that are in the foreground to be able to access elements below them. To undo this state, you have to find the corresponding element in the tree of the GUI browser, which also has such an entry in the context menu.

====Automatic Update====
The recorder doesn't show a live image of the device, but only a snapshot. Therefore an update is needed after changes to match what is displayed on the device. The recorder updates automatically after executing an action. Since expecco 20.2 there are further automatic updates possible. You can enable the, in the menu "View".

One option is, to check after an action has been executed, if there are further changes after the first update. If so, a second update is triggered. This shall fix the problem, that the recorder is not up to date after an action, because the update has been done too early.

The second option is to enable a periodical update. After a set interval the recorder is automatically updated if there are changes. Thereby the recorder view is mostly up to date, but this causes an overhead regarding the communication to the device.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid Apps and WebViews =
'''!!! IMPORTANT NOTICE - If you have problems switching to the webview, please set the "Default Application - Browser App" in Android Settings to "Chrome" !!!'''

Hybrid apps contain platform native elements as well as other elements that are integrated in a WebView. These elements can also be used, but you first have to switch to the corresponding context. With the block ''Get Current Context'' you get the current context. Initially this is ''NATIVE_APP'', i.e. the context of the native elements. With the block ''Get Context Handles'' you get a collection of all existing contexts. If there is a WebView context, it is called ''WEBVIEW_1'' or ''WEBVIEW_<package>'' with the package of the WebView. Several WebView contexts are also possible. For each WebView context, there is a corresponding WebView element in the native context. You can use the ''Switch to Context'' block to switch to such a context and from now on only have access to the elements in this context.

In the GUI browser, the existing contexts are displayed at the top of the tree as well as the tree of a context is inserted below the corresponding WebView element.

=Customizing XPath using the GUI Browser=
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen ''GTIN-13 (EAN-13)'' und ''Verify'', das Eingabefeld der Zahl ''4006381333986'' und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des GTIN-13-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch ''Pfad überprüfen'' (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit ''Verify Path: OK'' (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit * zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert ''GTIN-13 (EAN-13)'' besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer ''hierarchy'' (für iOS wäre es ''AppiumAUT''), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix ''android.widget.'', das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend ''XCUIElementType'' am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. ''FrameLayout'' ist ein Kindelement von ''hierarchy'', ''LinearLayout'' ist ein Kind von ''FrameLayout'' usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element ''hierarchy'' beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben ''TextView''-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ ''Button'' gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut ''resource-id''. Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut ''name'' verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem @ eingeleitet und der Wert mit einem = in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter ''Test'' eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf ''Lauf''. Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu ''Eigenschaften'', wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

=Problems and Solutions=
== Locators depend on the version or are variable ==
In this case consider to either store the locators (xPath) in a variable or to define a locator mapping inside a screenplay attachment. It is also possible to store just parts of an locator (e.g. locator path of a parent or attribute value) in a variable and add them in the freeze value of the locator pin by "''$(varName)''".

== Invisible UI Elements ==
Note that the [[#Recorder|Recorder]] also considers items that you cannot see on the screen. Therefore, turn on element highlighting or use the follow mouse function and the element tree in the GUI browser to determine if the correct element is used. It can happen, that invisible elements are in front of other elements and cover them, so that the desired element cannot be selected in the recorder. See section [[#Hide_elements|Hide elements]] for a solution to this.

== iOS: Cable not certified ==
In some cases, when connecting an iOS device via USB, a message appears indicating that the cable used is not certified. In this case, replacing the respective cable is the only solution.

== iOS: Alerts when connecting ==
Make sure that no alerts are open when connecting to an iOS device. Otherwise the connection will fail because the app cannot be brought to the foreground. See also [[#Preparing_an_iOS-Device_and_App|Preparing an iOS-Device and App]].

== iOS: .ipa cannot be installed ==
Note that on iOS simulators no ''.ipa'' files can be installed but only ''.app'' files.

==iOS: First Connect is not working==
If there is not already a signed build of the WebDriverAgent on your Mac, it has to be created during the first connect. Usually, this can take a little longer than one minute. Per default Appium uses a timeout of 60000 ms to wait for the WebDriverAgent to start on the device, so the connect will be canceled in that case. You can set this timeout with the capability ''wdaLaunchTimeout'', e.g. to ''120000''.

Moreover, the signing settings have to be correct. In our experience, the most reliable solution is to set automatic signing in the WebDriverAgent Xcode project an selecting the team there. See the explanation in section [[#Signing_WebDriverAgent|Signing WebDriverAgent]] for that. In this case you should '''not''' use the capabilities ''xcodeConfigFile'' resp. ''xcodeOrgId'' and ''xcodeSigningId'', as they could cause a conflict. Caution: If you have set a Team ID in the Mobile Testing settings, expecco will automatically set this as ''xcodeOrgId''!

Pay attention to your device during the first connect. You might have to agree to the installation by entering your password. On the Mac you might need to enter the password to allow access to the key chain for signing, often several times.

== Android: Device not visible in the connect editor ==
If an Android device connected via USB does not appear in the connection editor, try changing the USB connection type. Usually MTP or PTP should work. Check again, if "USB Debugging" is enabled in the developer options on the device (these options are disabled on some devices and have to be enabled first using a trick.) See also [[#Prepare_Android_Device|Prepare Android Device]].

== Android: Truncated Elements at Bottom ==
For Android devices that automatically show and hide the navigation bar/softkeys, the recorder may cut off elements in the lower area that would be hidden by the softkeys, even if they are not displayed at this time. In this case it is advisable to set the softkeys so that they are permanently displayed.

For newer Android versions there usually is no such option. Even if the controls are visible all the time, they don't have their own space, but are on top of the content of the app. Therefore, there is an area on the lower part of the screen, which cannot be automated, because it is not counted to the active area of the app. Appium will then truncate the elements there. This area can even be larger then the needed by the controls. This is a known issue for Samsung devices with Android 11. Since the information about the size of the app area is already provided on Android level, we cannot offer a solution for this, but can only hope that the problem will be fixed by the manufacturer. You may try to get better results by setting the control to gestures, but this bears the same issue.

== Android: Test Hangs While Finding an Element==
The block ''Find Element by XPath'' and all element blocks wait until an element is present for the given path. The timeout for this can be set either directly at the block or in the environment variables. However, if the element should already be present, but the test doesn't continue anyway, the reason could be in the UIAutomator/UIAutomator2. It waits for the app to go to the idle state before it even starts to search for the element. This may take longer, if the app e.g. runs an animation in the background or executes other kinds of actions. Fetching the page source, e.g. when updating in the GUI browser or in the recorder, can also take longer for this reason. There is a default timeout of 10 seconds after which it no longer waits for the idle state. This timeout can be set in Appium (waitForIdleTimeout). If you want to change the value of this timeout, you can do this since expecco 21.2 by executing the Smalltalk code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> before the test. The timeout is given in milliseconds, so the example sets it to 2 seconds.

==Android: Updating the Tree or Switching to Webview Context takes too long==
Especially with older devices it can happen that newer Chromedriver cannot be initialized. This makes it impossible to switch to the webview context. However, this is only detected over a timeout by Appium, which is 4 minutes by default. Since expecco also tries to switch to the webview context when building the tree in the GUI browser, this can lead to very long loading times. Since there is no way to decrease this timeout in Appium, we have added a corresponding capability to the version we provide in the MobileTestingSupplement. Starting with version 1.13.1.0 of the [[#Windows|MobileTestingSupplement]], ''chromedriverStartTimeout'' can be used to set the timeout in milliseconds. The switch still doesn't work then, but expecco doesn't take as long to update the tree and the context switch module fails faster. The connection dialog adds this capability automatically starting with expecco 22.1.

== No Action on Click ==
The block to click on an element is successful, but no action was performed on the device.
:This can happen if the element is hidden by another element and therefore clicking on the element is not possible. In this case, Appium does not throw an error, but simply nothing happens. If you would like to make a click at the position of the element anyways, even if it is hidden, use the block ''Tap'' instead and pass the location of the element to it (''Get Location''). If instead you want to check before a click whether the element is hidden at this moment, try whether the properties ''Is Displayed'' or ''Is Enabled'' might help you.

== No Update After Action ==
An action was triggered on the recorder and a block has been recorded, but the recorder still shows the old image.
:The recorder doesn't show a live image of the device, but only a snapshot. After an action has been executed, the recorder will update automatically. However, it can happen, that the image has already been updated before the effects of the action are fully completed on the device. In this case you should update the recorder by hand using the icon with the blue arrows. Since expecco 20.2 you can also enable automatic updates for this case. See also the description for the [[#Recorder|recorder]].

== Attribute "clickable" is wrong ==
An element has for the attribute/property "''clickable''" the value "''false''", but is actually clickable.
:The attribute "''clickable''" has to be set explicitly by the app developer and does not affect the behavior of the app. You should generally disregard this attribute in your tests. Unfortunately, many apps exist where the programmer was "lazy" about this.

==Connecting Fails==
If the connection to the Appium server fails, you will receive an error message in expecco similar to the one shown below.

[[File:MobileTestingVerbindungsfehler.png]]

Here you can see the type of error that has occurred. Click on "''Details''" to get more information. Possible errors are:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:The specified server is not running or is not reachable. Check the server address.
*''org.openqa.selenium.WebDriverException''
:Read the message after ''Original Error'' in the first line of the details:
:*''Unknown device or simulator UDID''
::Either the device is not connected properly or the udid is not correct.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::This error can have various causes. Either the WebDriverAgent could actually not be built because the signing settings are wrong or the appropriate provisioning profile is missing. Please read the section about [[#Signing|Signing]]. It is also possible that the WebDriverAgent cannot be started on the device, for example because an alert is in the foreground or you did not trust the developer.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::The specified app cannot be installed on the iOS device because it is not entered in the app's Provisioning Profile.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.''
::The path to the app is wrong. Make sure that the file is located in the specified path on your Mac.
:*''packageAndLaunchActivityFromManifest failed.''
::The specified ''apk'' file is probably broken.
:*''Could not find app apk at [...]''
::The path to the app is wrong. Make sure that the ''apk'' file is located in the specified path.

If the error is not due to one of the causes listed above, the automation applications on the device may no longer function properly. In this case it helps to uninstall them from the mobile device. They are then automatically reinstalled the next time a connection is established.

*For iOS devices, this is the WebDriverAgent, which you can simply uninstall from the home screen. This usually solves problems caused by changing the used Mac or the Xcode version.

*For Android devices, it is the UIAutomator2; here, a problem occurs sporadically on some devices, the cause is currently unknown to us. To uninstall, on the device, navigate to "''Settings''" > "''Applications''"* and search the list for the following entries:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Click on the respective application and then on "''Uninstall''".
*''The corresponding entry may have a slightly different name on some devices.''

If this doesn't help, check the output of the Appium server. For a server started by expecco, you can find the log in the list of [[#Running_Appium_Servers|Running Appium Servers]].

==I do not have a Mac==
Maybe this site will help you: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin/en

2023-11-30T11:45:33Z

Matilk: /* Problems and Solutions */ first iOS connect

[[Mobile_Testing_Plugin|Deutsche Version]] | '''English Version'''

= Introduction =
With the ''Mobile Testing Plugin'' applications can be tested on Android and iOS devices. This includes both real and emulated devices. It does not matter whether real mobile devices or emulated devices are used. The plugin can (and usually is) used in conjunction with the [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]], which supports the creation of tests. It can also be used to record test procedures.

[http://appium.io/ Appium] is used to connect to the devices. Appium is a free open source framework for testing and automating mobile applications.

We recommend to go through the [[Mobile_Testing_Tutorial/en|Tutorial]] to familiarize yourself with the Mobile Plugin. This tutorial leads step by step through the creation of a test case using an example and explains the necessary basics.

= Installation and Setup =
To use the ''Mobile Testing Plugin'', you must have installed expecco together with the corresponding plugin, and you need the appropriate licenses. expecco communicates with the mobile devices via an Appium server, which either runs on the same computer as expecco, or on a second computer. This must be accessible for expecco.

== Installation Overview ==
'''Computer running expecco:'''
* Java JDK version 8, 9, 10 or 11
'''Computer connected to Android devices :'''
* Appium Server, you can install it via the Mobile Testing Supplement (see below), of which we regularly provide a new version
* Android SDK, you can also get it with the Mobile Testing Supplement
* Java JDK version 8, 9, 10 or 11
'''Computer connected to iOS devices*:'''
* Appium Server, you can install it via the Mobile Testing Supplement for MacOS (see below), of which we regularly provide a new version
* Xcode in a version that supports the iOS version used, available from the Apple App Store
* Java JDK version 8, 9, 10 or 11
* Apple Developer Certificate incl. matching private key (to sign the WebDriverAgent)
* Provisioning Profile for the mobile devices to be used

* Please note that due to the requirements (no connection to non-Apple devices available) iOS devices can only be controlled from a Mac.

Depending on the setup, the above-mentioned computers can also be the same device. expecco can either connect to a remote Appium Server and mobile devices connected to it via the network, or start an Appium Server locally itself and use it with local mobile devices. However, some of expecco's functions that make it easier to create test cases are only available if the mobile devices are connected to the same computer on which expecco is running. A possible setup may therefore look like the following figure:

[[Datei:MobileTestingAufbau.png | 400px]]

The following explains how to install Appium and other necessary applications for Windows and Mac OS.

== Windows ==
The easiest way is to install everything from our Mobile Testing Supplement. However, newer versions do not contain a JDK anymore due to a change in Oracle's license terms, so you have to install it additionally. Of course, you are free to install Appium directly to use the version you want. However, to then be able to start an Appium server with expecco, a suitable batch file must be available and specified in the [[Mobile_Testing_Plugin/en#Plugin_Configuration|settings]]. However, connections can also be established to other running Appium servers.
*'''expecco 23.1''': [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Same versions as in the predecessor, but the installer now allows to add Appium to the Autostart.
*expecco 22.2 and 22.1: [https://download.exept.de/transfer/h-expecco-22.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 from platform-tools 33.0.2
:''* We added the capability'' startChromedriverTimeout ''to Appium, to get a timeout earlier, if Chromedriver cannot be initialized. (see [[#startChromedriverTimeout|Problems and Solutions]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Contains Appium version 1.22.0, Node still is version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Only minor changes compared to the previous version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Compared to the previous version, Appium was updated to version 1.16.0-rc.1 and node 12 is used.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:This installs Appium in the version 1.12.0 and now additionally contains build-tools in the version 28.0.3 in the android-sdk. Apart from this, it is the same as the previous version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:This installs Appium in the version 1.8.1. In addition, an installation of ''Android Debug Bridge'' and ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) is offered. This covers drivers for a broad range of Android devices, and you won't have to install an individual driver for each device. A '''JDK is not contained anymore (due to a change in Oracle's license terms)''', you have to download it on your own, e.g. from [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: same procedure as for expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:This installs a Java JDK Version 8, android-sdk and Appium Version 1.6.4. The supplement also offers a universal adb driver ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]). This driver supports a wide range of Android Devise, and avoids the need to search for individual device-specific drivers.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:It installs a Java JDK version 8, android-sdk and Appium version 1.4.16. During the installation the graphical user interface of Appium is started, you can close this window immediately. The supplement also offers a universal adb driver (ClockworkMod). This combines drivers for a wide range of Android devices so that you do not have to search for and install a separate driver for each device.

If expecco has to use mobile devices that are connected to another computer, you have to start an Appium server there. You can do this by using the file <code>appium_standalone.cmd</code>. The server is then started on default port 4723. If you want to use a different port number, start the server with

appium_standalone.cmd -p <portnummer>

The server is ready, as soon as the line
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
is displayed, where you can read the used port number at the end.

If your Android device is connected to a remote machine,
you may want to see the live screen locally using a tool like
[https://github.com/Genymobile/scrcpy scrcpy].

When Appium is started for the first time – either standalone or by expecco – it may happen that the Windows firewall blocks access to the node server. Allow the access or Appium cannot be started.

== Mac OS ==
Note: the following can be ignored if you do not plan to test iOS (iPhone) devices. The Mac setup is not needed for Android devices.

=== Xcode ===
Automation with iOS devices needs [https://developer.apple.com/xcode/ Xcode]. You can install it from the App Store. Please make sure that the version matches the tested iOS versions.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
This table is only a simplified overview, better see [https://xcodereleases.com/ Xcode releases] or [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode versions] for the exact versions. For new iOS minor versions, there is usually also a new release of Xcode, e.g. for iOS 10.2 you need at least Xcode 8.2, for iOS 10.3 at least Xcode 8.3, etc. So if you are upgrading to a newer iOS version, you will usually need a newer Xcode version as well. Newer versions of Xcode may not run on older operating systems, which in turn may require an operating system upgrade. If you also want to test older iOS versions, it can be useful to install the corresponding Xcode versions in parallel.

=== Appium ===
You can install Appium either as command-line tool or use it with [https://github.com/appium/appium-desktop Appium Desktop], which provides a GUI to start the server. Meanwhile there is also Appium 2.0, which is not tested with expecco yet and therefore not recommended to use.

==== Appium Desktop ====
Download the newest version of [https://github.com/appium/appium-desktop/releases/ Appium Desktop]. For the Mac, it is best to take the dmg file and install it to the applications. When starting ''Appium Server GUI'' you will probably get the error message, that it is not possible for security reasons. In this case, open the context menu of the app file (right click or Ctrl + click) and choose ''Open'' there. Then confirm that you really want to open the application. From now on you can open the application normally.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Since Xcode 14 there are problems with signing the WebDriverAgent, which Appium loads on the device for the automation. This means that no connection is possible with version 1.22.3-4 of Appium Desktop. In newer versions of WebDriverAgent, this problem is solved, but currently there is no version of Appium Desktop using such a new version (as of November 2022). However, you can manually download a new version (e.g. 4.10.2) and replace the files in Appium. To do this, download one of the two archive files (zip or tar.gz) containing the source code from the [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent download page]. Then open and extract this file. Copy the contents of the folder ''WebDriverAgent-4.10.2' to

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

If you navigate there by Finder, make a context click (right click or Ctrl + click) on the application and choose ''Show Package Contents'' from the menu. Replace all files that are already present with the same name.

==== Install Appium using npm ====
You can install Appium using npm (Node Package Manager) as well. To do this, you have to install node/npm first. This can be done using [https://github.com/nvm-sh/nvm nvm] (Node Version Manager), which you can get on Github. If the following installation instructions should not work for you, you will find detailed information in the [https://github.com/nvm-sh/nvm#readme Readme] there.

Open a Terminal window. Then clone the Github repository of nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
and load it
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Then execute
command -v nvm
to see if it works. It should print ''nvm''. If there is no response, execute
touch ~/.zshrc
and try again.

Now you can install node with the following command.
nvm install 16.15.1
As there are problems installing Appium using the newest version of node, we recommend this version.

After node is installed, you can use it to install Appium:
npm install -g appium

The Appium server now simply can be started with the command
appium
The output will then be written directly to the terminal.

This version also has problems with signing the WebDriverAgent, like explained in [[#Appium_Desktop | Appium Desktop]]. Therefore download a newer version of WebDriverAgent in this case as well and replace the old files. You will find them at
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
We provide older versions of Appium via the Mobile Testing Supplement for Mac OS, with which you can easily install it:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.2)]
:Contains Appium version 1.18.3 and uses node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement for Mac OS (1.2.0)]
:Only a few changes compared to the previous version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.98)]
:Appium is updated to version 1.16.0-rc.1 and node 12 is used.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.96)]
:This version contains Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.1.94)]
:This version contains Appium 1.8.0.

* expecco 2.11:[http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement for Mac OS (1.0.94)]
:This version contains Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement for Mac OS]
:Diese Version entält Appium 1.4.16.

After you have downloaded the supplement, you can move it to a directory of your choice (e.g. your home directory) and unpack it there. A suitable command in a shell could look like this, adjust the version number accordingly:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

If your default Xcode installation is the one you want to use, you can start Appium directly from the file in the ''bin'' directory with the appropriate version number:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

If you want to use another Xcode than the one configured as default, you have to tell Appium the corresponding path by using the environment variable ''DEVELOPER_DIR''. For example, if you have installed Xcode in ''/Applications/Xcode-11.3.app'', you can start Appium this way:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

To find out what is set as the default Xcode installation on your system, use this command:

xcode-select -p

If Appium cannot find your Xcode installation, a message like this appears:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
In such a case, restart Appium by specifying a valid ''DEVELOPER_DIR''.

==== Signing WebDriverAgent ====
For automation, Appium installs an App called WebDriverAgent on the device and therefore has to be able to sign it. You need an Apple account and a respective certificate for this. For evaluation you can use a free account. This has the disadvantage that created profiles are only valid for one week and must be recreated afterwards. Also be careful when sharing the account, as certificates may be revoked or invalidated by automatic generation. As a result, apps that have already been signed can no longer be used.

If you already have a respective certificate and its associated private key in your keychain on the Mac, you can have the WebDriverAgent automatically signed. If not, it is recommended to set and manage the signing using Xcode.

First, connect the device you want to use to your Mac via USB. Make sure both the Mac and the device are in the same network or there will be problems when connection with Appium. Start Xcode and open ''Preferences''. Go to the Accounts page and create an entry with your account. You can then click on ''Manage Certificates...'' to see the certificates that belong to that account. To run tests, you need an iOS Development Certificate and the associated private key. If you do not already have one, create one. If you already have one, but it is not in your keychain (indicated by "Not in Keychain"), you can import it. You can do that by the [https://support.apple.com/en-us/guide/keychain-access/welcome/mac keychain access] on your Mac, if you have exported it previously from the keychain, where it is stored. The certificate with the associated key should be in the keychain ''Login''. It can be exported from there as PKCS#12 file (typical ending .p12). To import a certificate into your keychain, select the option ''Import objects'' from the ''File'' menu. If you don't know where the certificate is stored, you can also revoke it in Xcode and recreate it in your keychain. However, only do this if you know that the old certificate is no longer in use because it can no longer be used afterwards. Now the keychain should contain an iOS development certificate.


Now open the WebDriverAgent project in Xcode. If you have installed the Mobile Testing Supplement, you will find it in this directory at
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
If you have installed Appium Desktop, you will find it at
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''

You can use the Finder to navigate to the Xcode project file and open it by double clicking. Note, that you have to perform a context click (right click or Ctrl + click) on the Appium Server GUI app and select ''Show Package Contents'' in the menu, to get to its subdirectory.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Select ''WebDriverAgentLib'' and the page ''Signing & Capabilities''. In the section ''Signing'' set the option ''Automatically manage signing'' and then select a team. Now switch to ''WebDriverAgentRunner'' and do the same there.

By setting the team, the errors showing up for WebDriverAgentRunner should disappear. If Xcode should not be able to create a Provisioning Profile matching the Bundle ID ''com.facebook.WebDriverAgentRunner'', you can edit the latter so that it fits your certificate. After that you can quit Xcode or you can, like explained further below, directly start the build in Xcode, so the project will be already built when Appium wants to use it.

If you now connect to your device from expecco, the WebDriverAgent will be installed and started on it and then switch to the app to be tested. You may still have to trust the execution of the WebDriverAgent on the device. It maybe a sign that you have to do this, if the app WebDriverAgent first appears on the device and tries to start, but then is uninstalled again. To trust the execution, open the settings during the connection setup on the device and then the entry ''Device management'' under ''General''. This entry is only visible if a developer app is installed on the device. You may therefore have to wait until the WebDriverAgent is installed before the entry appears. Select the entry of your Apple account and trust it. Since the WebDriverAgent will be uninstalled again if the start did not work, you have to do this during the connection setup. If this is too hectic for you, you can also execute the following code:

xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

or
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

This installs the WebDriverAgent on the device without deleting it again.

If there are problems while installing the WebDriverAgent, you can also try and start the build in Xcode. Make sure the right target ''WebDriverAgent'' is selected. Error messages in Xcode might indicate easier what the problem is about. Sometimes it even helps to try for a second time, if it took too long for the first time and got aborted. It may occur, that you are asked several times during the build to enter the password for the keychain.

[[Datei:WebDriverAgentCodesign.png]]

Read also the documentation of Appium on [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Setting up tests with iOS devices]. Refer to the [https://support.apple.com/en-us/HT204460 Apple documentation] for details on installing and trusting of apps.

== Plugin Configuration ==
Before you start, please check the settings of the Mobile Testing Plugin and adjust them if necessary. Select the menu item "''Extras''" → "''Settings''" → "''Extensions''" → "''Mobile Testing''" (see fig.). By default, these paths are found automatically (1). To adjust a path manually, deactivate the corresponding check mark at the right. You'll see a drop-down list with some paths to choose from. If an entered path is wrong or cannot be found, the field is marked red and a message appears. Make sure that all paths are specified correctly.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Plugin Configuration]]

*'''appium''': Enter the path to the executable file with which Appium can be started in the command line. Under Windows this file will usually be called "<code>appium.cmd</code>". This path is used when expecco starts an Appium server.
*'''node''': Enter the path to the executable that starts Node (also called (also called "Node.js"). This path is passed to Appium when a server is started so that Appium can find it independently of the PATH variable. Under Windows this file is usually called "<code>node.exe</code>".
*'''JAVA_HOME''': Enter the path to a JDK (Java Development Kit)here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable. To specify which Java should be used by expecco, set this path in the Java Bridge settings.
*'''ANDROID_HOME''': Enter the path to an Android SDK here. This path is passed to each Appium server. Leave the field blank to use the value from the environment variable.
*'''adb''': The path to the adb command. Under Windows the file is called "<code>adb.exe</code>". This file is used by expecco, for example, to get the list of connected devices. This path should be selected automatically, if the command is found in the ANDROID_HOME directory. This is also used by Appium. If expecco and Appium use different versions of adb, conflicts may occur.
*'''android.bat''': This file is only needed to start the AVD and the SDK Manager, which deal with phone emulators. The file in the ANDROID_HOME directory will be selected automatically, if present there.
*'''aapt''': The path to the "aapt" command here. Under Windows this file is called "<code>aapt.exe</code>". expecco uses "aapt" only in the connection editor to read the package and activities of an "apk" file. The file in the ANDROID_HOME directory will be selected automatically, if present there.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | JDK Configuration]]

Starting with expecco 2.11, there is an additional field called ''Team ID''. If you run iOS tests, enter the Team ID of your certificate here. This is used for every iOS connection, unless you change the value in the connection settings in individual cases. For information on how to obtain the team ID, please refer to the section on [[#Signing| signing]] for installations on Mac OS. With expecco 2.10 and older, you can only enter the Team ID as capability for each connection setting separately. However, you must use the [[#Extended_View|extended view]] to do this. Enter the capability ''xcodeOrgId'' here and set the Team ID of the certificate as value.

The server address setting at the bottom of the page refers to the behavior of the connection editor. It checks at the end whether the server address ends in ''/wd/hub'' as this is the usual form. If not, a dialog asks how to react. The defined behavior can be viewed and changed here.

Also switch to the entry ''Java Bridge'' (see figure). Here you have to specify the path to your Java installation, which is used by expecco. Enter a JDK here. If you want to use the one from the Mobile Testing Supplement under Windows, the path is
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
You can also use the system settings.

== Prepare Android Device ==
If you connect an Android device under Windows, you may still need an adb driver for the device. You can usually find a suitable driver on the manufacturer's website. If you have installed the universal driver from the Mobile Testing Supplement, everything should already work for most devices. In some cases, Windows will automatically try to install a driver when you connect the device for the first time. 
'''Attention''': Before you can control a mobile device with the Appium plugin, you have to allow this debugging!

For Android devices, you can find this option in the settings under ''[https://developer.android.com/studio/debug/dev-options Developer Options]'' called ''USB-Debugging''. If the developer options are not displayed, you can unlock them by tapping Build Number seven times in About the Phone.

Also enable the ''Stay awake'' feature to prevent the device from turning off the screen during test creation or execution.

For security reasons, USB debugging must be allowed for each computer individually. When connecting the device to the PC via USB, you must agree to the connection on the device. If you haven't done this for your computer yet, but no corresponding dialog appears on the device, it may help to unplug and reconnect the device. This can happen especially if you have installed the ADB driver while the device was already connected via USB. If this doesn't help either, open the notifications by dragging them from the top of the screen. There you will find the USB connection and you can open the options. Select another type of connection; usually MTP or PTP should work.

You can also test on an emulator. It does not need to be prepared separately, as it is already designed for USB debugging. It is even possible to start an emulator at the beginning of the test.

To check if a device you have connected to your computer can be used, open the [[#Connection_Editor|connection editor]]. The device should be displayed there.

=== Connection via WLAN ===
It is possible to connect to Android devices via Wireless LAN. For devices using Android 11 or newer, this can be done wirelessly, else you have to connect initially via USB. Since expecco 22.1, WiFi connections can be established using the [[Mobile_Testing_Plugin/en#Connection_Editor|Connection Editor]]. It is also possible to do this using a command window.
==== Wireless Connect (Android 11) ====
In the developer options of your device, enable wireless debugging and open its options. You initially have to pair your machine with the device. To do this, choose "''Pair device with pairing code''" to get a pairing code and an IP address with port. Then open a command window (terminal window) on your machine and enter:
<nowiki>adb pair <Device IP Address>:<Pairing Port></nowiki>
where <tt><Device IP Address>:<Pairing Port></tt> is the IP address and port as shown on the device. After that, you will be asked for the pairing code. If everything went right, the popup on the device should have closed and your machine is added to the list of paired devices. Then enter at the command window:
<nowiki>adb connect <Device IP Address>:<Debugging Port></nowiki>
The IP address is the same as for pairing, but the port is different. Both are shown as IP address & Port on the device. The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted. Restarting the device often disables wireless debugging and the used port is changed. The pairing, however, is permanent and has not to be done again the next time you connect.
==== Start via USB ====
First, connect your device via USB. Then open a command window (terminal window) and enter:
<nowiki>adb tcpip 5555</nowiki>
The device listens for a TCP/IP connection on port 5555. If you have several devices connected or emulators running, you have to specify which device you mean. Enter in this case:
<nowiki>adb devices -l</nowiki>
to get a list of all devices, where the first column gives the device's ID.
Then, enter:
<nowiki>adb -s <deviceID> tcpip 5555</nowiki>
with the device identification of the desired device. You can now disconnect the USB connection. Now you have to find out the IP address of your device. You can usually find it somewhere in the device's settings, for example in the Status or WLAN settings of the phone. Then type in:
<nowiki>adb connect <IP address of device></nowiki>
The device should now be connected via WLAN and can be used in the same way as with a USB connection. You can check this by entering <tt>adb devices -l</tt> again or open the connection dialog in expecco. In the list, the device appears with its IP address and port. Remember that the WLAN connection no longer exists when the ADB server or the device is restarted.

== Preparing an iOS-Device and App ==
Control of iOS devices is only possible via a Mac. Please also read the section [[#Mac_OS|Installation under Mac OS]].

Before you can control a mobile device with the Mobile Testing Plugin, you must allow debugging for iOS devices with iOS 8 or higher. Activate the option "''Enable UI Automation''" under the "''Developer''" menu in the device settings. If you cannot find the "''Developer''" entry in the settings, proceed as follows: Connect the device to the Mac via USB. If necessary, you must still agree to the connection on the device. Start Xcode and then select "''Devices''" from the menu bar at the top of the screen in the "''Window''" menu. A window opens in which a list of the connected devices is displayed. Select your device there. Then the entry "''Developer''" should appear in the settings on the device. You may have to exit the settings and restart.

[[Datei:Alert.png | thumb | 270px | Alert unter iOS]]
It is not possible to establish a connection to the device as long as it shows certain alerts. Such an alert may appear if FaceTime is activated (by displaying a message about SMS charges as shown in the screenshot). Be sure to configure the device so that it does not show such alerts when idle.

=== expecco 2.11 and later ===
You can test any app which is executable or already installed on the device used. If the app is available as a development build, the UDID of the device must be stored in the app. In any case, the WebDriverAgent must be signed for the device. Please read the section about [[#Signing|signing]] under Mac OS.

If you want to use the Home button in a test, you must activate "AssistiveTouch" on the device. You will find this option in the settings under "''General''" > "''Operating Help''" > "''AssistiveTouch''". Then place the menu in the middle of the upper edge of the screen. You can then record pressing the Home button with the corresponding menu entry in the recorder or use the "''Press Home Button''" block directly.

=== expecco 2.10 ===
The app you want to use must be available as a development build. The UDID of the device must also be stored in the app.

=== Sign the development build ===
A development build of an app is only allowed for a limited number of devices and cannot be started on other devices. However, it is possible to exchange the certificate and the usable devices in a development build.

* Evaluation with demo app of eXept:
:We will be happy to provide you with a demo app which is available as a development build and which we can sign for your device. Please send the UDID of your device to your eXept contact person. How to determine the UDID of your device is described in the following section.

* Using your own app for your test device:
:If you receive a development build (IPA file) from the app developers that is approved for your test device, you can use it directly. To do this, you must tell the developers the UDID of your device so they can enter it. '''You can use Xcode to read the UDID of a device'''. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window opens in which a list of the connected devices is displayed. Select your device and search for the ''Identifier'' entry in Properties. The UDID is a 40-digit hexadecimal number.

* Externally developed app for your test device:
:You can also re-sign apps to make them run on other devices. However, this process is complicated and requires access to an Apple Developer account. A documentation on the procedure is currently in preparation.

:For the evaluation we will gladly support you with the re-signing of your app..


For more information about using iOS devices, see also the
[http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Appium documentation].

=== Native iOS-Apps ===
You can also use apps that are already natively present on the device. To do this, you must know their bundle ID and then enter it in the connection settings. Here is a small selection of common apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

You can find further Bundle-IDs [https://github.com/joeblau/apple-bundle-identifiers here].

= Examples =
In the demo test suites for expecco you will also find examples for tests with the Mobile Testing Plugin. To do this, select the option "''Example from File''" on the start screen and open the folder named "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
The test suite contains two simple test plans: "''Simple CalculatorTest''" and "''Complex Calculator and Messaging Test''". Both tests use an Android emulator, which you must start before starting. The apps used in the test are part of the basic equipment of the emulator and therefore no longer need to be installed. Since the apps may differ under every Android version, it is important that your emulator runs under Android 6.0. In addition, the language must be set to English.

; Simple CalculatorTest
: This test connects to the calculator and enters the formula ''2+3''. The result of the calculator is compared with the expected value ''5''.

; Complex Calculator and Messaging Test
: This test connects to the calculator and then opens the message service. There it waits for an incoming message from the number ''15555215556'', in which a formula to be calculated is sent. The message is generated before via a socket at the emulator. When the message arrives, it is opened by the test and its contents are read. Then the calculator is opened again, the received formula is entered and the result is read. The test then switches back to the message service and sends the result as an answer.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
These are part of the tutorial for the Mobile Testing Plugin. The included test case is incomplete and will be added during the tutorial. Please read the section [[#Tutorial|Tutorial]].

= Tutorial =
There is a tutorial describing the basic procedure for creating tests with the Mobile Testing Plugin. It is based on a supplied example consisting of a simple app and an expecco test suite.

You find it on the page [[Mobile_Testing_Tutorial/en|Mobile Testing Tutorial]] in two versions for Android and iOS devices.
*  [[Mobile_Testing_Tutorial/en#First_steps_with_Android|First steps with Android]]
*  [[Mobile_Testing_Tutorial/en#First_steps_with_iOS|First steps with iOS]]

= Dialogs of the Mobile Testing Plugin =
== Connection Editor ==
You can use the Connection Editor to quickly define, change, or establish connections. Depending on the task, the dialog has small differences and is opened differently:
*If you want to establish a connection, access the dialog in the GUI browser by clicking on ''Connect'' and then selecting ''Mobile Testing''.
*To change or copy an existing connection in the GUI browser, select it, right-click and select ''Edit Connection'' or ''Copy Connection'' from the context menu.
*If you do not want to create connection settings for the GUI browser but for use in a test, choose ''Create Connection Settings'' from the Mobile Testing Plugin menu.... This only allows you to create the settings for a connection without creating a connection in the GUI browser.

The Connection Editor menu has several buttons, some of which are only visible when creating connection settings:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#''Delete Settings'': Resets all entries. (Only visible when creating settings.)
#''Load settings from file'': Allows to open a saved settings file (*.csf). Its settings are transferred to the dialog. Entries already made without conflict are retained.
#''Load settings from attachment'': Allows you to open an attachment with connection settings from an open project. These settings are applied to the dialog. Entries already made without conflict are retained.
#''Save settings to file'' and
#''Save settings to attachment'': Here you can save the entered settings to a file (*.csf) or create them as an attachment in an open project. Both options have a delayed menu in which you can choose to save only a certain part of the settings. (Only visible when creating settings.)
#''Advanced View'': Allows you to switch to the advanced view to make additional settings. Read more about this at the end of this chapter. (Only visible when creating settings.)
#''Help'': A help text for the respective step is shown or hidden on the right side.

The dialog is divided into three steps. In the first step you select the device you want to use, in the second step you select which App should be used and in the last step the settings for the Appium server are made.

===Step 1: Select Device ===
In the upper part you will see a list of all connected Appium devices that are detected. With the checkbox below you can hide devices that are detected but not ready. If you want to enter a device that is not connected, you can create it with the corresponding button ''Enter Android device'' or ''Enter iOS device''. However, you need to know the required properties of your device. The device is then created in a second device list and can be selected there. If no list with connected elements can be displayed, various messages are displayed instead:
*No devices found
*:expecco could not find any Android devices.
*:To automatically configure a connection to a device, make sure
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*No available devices found
*:expecco could not find any available Android devices. But not available ones were found, e.g. with the status "unauthorized".
*:To configure a connection to a device automatically, make sure that
*:*it is connected
*:*it is turned on
*:*that it has an appropriate adb driver installed
*:*it is enabled for debugging (see below).
*:To view unavailable devices, enable this option below.
*Connection lost
*:expecco has lost the connection to the adb server. Try to re-establish the connection by clicking on the button.
*Connection failed
*:expecco could not connect to the adb server. Possibly it is not running or the specified path is not correct.
*:Check the adb configuration in the settings and try to start the adb server and establish a connection by clicking on the button.
*Connect ...
*:expecco connects to the adb server. This may take a few seconds.
*Start adb-Server ...
*:expecco starts the adb-Server. This may take a few seconds.

With ''Next'' you get to the next step. If you enter settings for the GUI browser, this is only possible once a device has been selected.

Note on unlocking: In newer Android versions the developer options are no longer offered in the settings at first. If your Android device does not show an entry for "''Developer options''" in the settings, first select the entry "''Phone info''", then "''SoftwareVersionsInfo''" and click on the entry "''BuildVersion''" several times.

==== Manage Chromedrivers ====
If the App you want to automate uses WebViews with Chrome, Appium needs to have access to an appropriate Chromedriver. If you have selected a device in the list, you can use "''Manage Chromedrivers''" to see, which Chrome versions are installed on the device and which Chromedriver versions are provided by expecco. With this dialog you can also download required Chromedriver versions. Beware that there may be several Chrome versions on the device. An App doesn't have to use the version of the installed Chrome browser for its WebViews. The Chromedriver you use should fit your app for everything to work properly. You can also change the path to the Chromedriver in the capabilities generated at the end of the connection editor.

==== Connect WiFi Android Device ====

You can connect to Android devices using WiFi as well. In this case, the device has to be connected to ADB first, see [[Mobile_Testing_Plugin/en#Connection_via_WLAN|Connection via WLAN]]. Since expecco 22.1, the connection editor provides a dialog helping to set this up, which can be used instead of the command window. For devices using Android 11 or newer, you can pair the device with your machine here by specifying the appropriate parameters and then establish the connection by specifying the IP address and port. You can also use this to establish a wireless connection for devices that are connected via USB. When you select the corresponding device in the list, the required information is read out automatically.

Note that establishing a wireless connection is not part of the connection settings. If you want to establish a new connection with the generated settings, you must make sure that the device is connected to ADB with the specified IP address and port so that it can be found. The ADB connection will be lost if the ADB server or the device are restarted. The permission for wireless debugging is also often reset when the device is restarted and the debug port can then change. Therefore, a wireless connection must always be established manually.

===Step 2: Select App===
Here you can enter information about the app to be tested. You can decide if you want to use an app that is already installed on the device or if you want to install an app for the test. Select the appropriate tab above. Depending on whether you selected an Android or an iOS device in the previous step, the required input will change.

*'''Android'''
**''App on Device''
**:If you have selected a connected device in the first step, the packages of all installed apps are automatically retrieved and you can select from the drop-down lists. The installed apps are divided into third-party packages and system packages; select the appropriate package list. This selection does not belong to the settings, but only provides the corresponding package list. You can use the filter to further narrow down the list and then select the desired package. The activities of the selected package are also automatically retrieved and made available as a drop-down list. Select the activity you want to start. As a rule, an activity is automatically entered from the list. If you are not using a connected device, you must enter the package and the activity manually.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. If you are using a local Appium server, you can use the right button to navigate to the App installation file and enter this path. If possible, the corresponding package and the activity are also entered in the fields below. However, this entry is not necessary.

*'''iOS'''
**''App on Device''
**:Specify the bundle ID of an installed app. You can find out the IDs of the installed apps using Xcode, for example. Start Xcode and select ''Devices'' from the menu bar at the top of the screen in the ''Window'' menu. A window will open displaying a list of connected devices. If you select your device, you will see a list of the apps you have installed in the overview.
**''Install App''
**:Under ''App'', enter the path to an app. The path must be valid for the Appium server being used. You can also specify a URL. For the requirements of apps for real devices, please read the section [[#iOS-Ger.C3.A4t_and_App_Preparing|Preparing an iOS-Device and App]].

In the lower part you can specify whether the app should be reset or uninstalled when the connection is terminated, and whether it should be reset initially. Again, the corresponding capability is not set if you select ''(Default)''. With ''Next'' you get to the next step.

===Step 3: Server Settings===
In the last step, a list of all the capabilities that result from your entries in the previous steps is first displayed in the upper part. If you are familiar with Appium and want to set additional capabilities that are not covered by the connection editor, you can click on ''Edit'' to open the extended view. See the section below for more information.

If you enter settings for the GUI browser, you can enter the ''Connection name'' with which the connection is displayed. This is also the name under which devices can use this connection when it is established. If you leave the field blank, a name will be generated. If the box "''Managed by expecco''" is checked, expecco will start a local Appium server on a free port, or use a free server that has already been started. To use your own server, turn this feature off and enter the appropriate address. You will get the local default address and already used addresses to choose from.

In older expecco versions the box is labeled "''Start on demand''". In this case, you must also enter an address if you want expecco to start the server. expecco then tries to start an Appium server at the given address when connecting, if none is running there yet. This server will then also be shut down when the connection is terminated. This only works for local addresses. Make sure that you only use port numbers that are free. It is best to only use odd port numbers from the standard port 4723. The following port number is also used when establishing a connection, which could otherwise lead to conflicts.

Depending on how you opened the dialog, there are now different buttons to close it. In any case you have the option to save. This opens a dialog where you can either select an open project to save the settings there as an attachment, or choose to save it to a file that you can then specify. Saving does not close the dialog, allowing you to select another option.

If you have opened the editor for establishing a connection, you can finally click on ''Connect'' or ''Start and connect server'', depending on whether the check mark for server start is set. For changing or copying a connection in the GUI Browser, this option is called ''Apply'', since in this case only the connection entry is changed or created, but the connection setup is not started. If necessary, you can do this afterwards via the context menu. If you have changed capabilities of an existing connection, a dialog then prompts you to decide whether these changes should be applied directly by closing the connection and establishing the new connection or not. In this case, the changes only take effect after you reestablish the connection.

To use the connection editor, also read the corresponding section in the respective tutorial in step 1. (Android: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo|Run Demo]], iOS: [[Mobile_Testing_Tutorial/en#Step_1:_Run_Demo_2|Run Demo]]).

===Extended View===
The extended view of the connection editor can be obtained either by clicking on ''Edit'' in the third step or at any time via the corresponding menu item if you have started the editor via the plugin menu. This view displays a list of all configured Appium Capabilities. You can add, change or remove further entries to this list. To add a capability, select it from the drop-down list of the input field. In this list all known capabilities are sorted into the categories ''Common'', ''Android'' and ''iOS''. If you have selected a capability, a short information text is displayed. You can also enter a capability manually in the field. Then click on ''Add'' to add the capability to the list. There you can set the value in the right column. To delete an entry, select it and click on ''Remove''. With ''Back'' you leave the extended view.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Running Appium Servers ==
In the menu of the Mobile Testing Plugin you will find the entry ''Appium-Server...''. This opens a window with an overview of all Appium servers started by expecco and on which port they are running. By clicking on the icon in the column ''Show Log'' you can view the logfile of the corresponding server. This is deleted when the server is shut down. With the icons in the column ''Exit'' the corresponding server can be terminated. However, this is prevented if expecco still has an open connection via this server. The rightmost column shows for which connection the server is in use. If it reads ''<idle>'', the server is currently not used by expecco.

[[Datei:MobileTestingAppiumServer.png]]

When opening the editor to start an Appium connection, an Appium server is started immediately to speed up the connection process. For this purpose, expecco always keeps one idle running Appium server. Additional running servers however, which are not in use anymore, will be terminated automatically after a while.

In the menu of the Mobile Testing Plugin you will also find the entry ''Close all Connections and Servers''. This is intended for cases where connections or servers cannot be terminated in any other way. If possible, always terminate connections in the GUI browser or by executing a corresponding block. Servers that you have started in the server overview should be terminated there; servers that were started with a connection are automatically terminated with this connection.

Note that only servers started and managed by expecco are listed in the overview. Possible other Appium servers that were started in a different way are not recognized.

== Recorder ==
If the GUI browser is connected to a device, the integrated recorder can be used to record a test section with that device. To start the recorder, select the appropriate connection in the GUI browser and click the Record button. A new window opens for the recorder. The recorded actions are created in the GUI browser work area. It is therefore possible to edit the recorded data in parallel.

[[Datei:MobileTestingRecorder.png|caption|]]

====Components of the Recorder Window====
#'''Continue/Pause Recording''': You can pause the recording by clicking the right icon. You will then see a large pause sign in the view. All actions that you perform now in the recorder are executed, but no blocks are recorded. You can switch back to normal recording mode by clicking the left icon.
#'''Stop Recording''': Stops the recording and closes the recorder window.
#'''Update''': Gets the current image and element tree from the device. This is necessary if the device takes longer to execute an action or if something changes without being triggered by the recorder. Since expecco 21.2, there is an additional submenu here that can be used to enable automatic update by checking for changes in the background (see also ''Automatic Update'' further below).
#'''Follow Mouse''': Select the element under the mouse pointer in the GUI browser.
#'''Element Highlighting''': The element under the mouse is outlined in red.
#'''Show Elements''': Show the borders of all elements in the view.
#'''Tools''': Selection, which tool is used for recording. The selected action is triggered with each click on the view. The following actions are available:
#*Element Actions:
#**Click: Short click on the element under cursor. To determine more precisely which element is used, use the Follow Mouse or Element Highlighting function.
#**Tap with Duration (Element): Similar to click, except that the duration of the click will be recorded as well. This allows the recording of long clicks.
#**Tap with Position (Element): Similar to click, but additionally records the position inside the element. The position can be recorded relative to the element size or, when pressing Ctrl while clicking, as absolute position from the upper left corner of the element.
#**Set Text: Allows to set the text of an input field.
#**Clear Text: Clears the text of an input field.
#*Device Actions:
#**Tap (Screen): Triggers a click at the screen position.
#**Tap with Duration (Screen): Triggers a click at the screen position, which also considers the duration.
#**Swipe: Swipe in a straight line from the point where you press the mouse button until you release it. The duration is also recorded.
#:Please note for this actions that the result may differ on different devices, e.g. with different screen resolutions.
#*Test Flow Blocks
#**Check Attribute: Compares the value of a specified attribute of the element with a predefined value. The result triggers the corresponding output.
#**Assert Attribut: Compares the value of a specified attribute of the element with a predefined value. If the values are not equal, the test fails.
#**Get Attribute: Gets the current value of a specified attribute of the element.
#*Auto
#:If the Auto tool is selected, you can use all actions by specific input methods: ''Click'', ''Tap Element'' and ''Swipe'' still work by clicking, but are distinguished by the duration and movement of the cursor. To trigger a ''Tap'', hold down Ctrl while clicking. The remaining actions are available in a context menu by right-clicking on the element.
#'''Context Actions''': Here you can record actions concerning contexts:
#*Switch to Context: Shows a list of all currently available contexts and you can select to which one you want to switch.
#*Get Current Context: Gets the handle of the current context.
#*Get Context Handles: Gets a list of all currently available contexts.
#'''Softkeys''': Only for Android. Simulates pressing the buttons Back, Home, Menu and Power.
#'''Home Button''': Only for iOS since expecco 2.11. Allows pressing the Home button.Prior to expecco 19.2, it only works if AssistiveTouch is activated and the menu is located in the middle of the upper screen border. From expecco 19.2 on, the function no longer uses AssistiveTouch.
#'''Help''': Opens this online documentation on the general page about [[GuiBrowser_Recorder/en|GUI Browser recorders]].
#'''View''': Shows a screenshot of the device. Actions are triggerd by mouse depending on the selected tool. If a new action can be recorded, the window has a green frame, else it is red.
#'''Resize Window to Image''': Resizes the recorder window so that the screenshot can be displayed completely.
#'''Resize Image to Window''': Scales the screenshot to a size that makes use of the full size of the window.
#'''Adjust Display''': Opens a dialog to adjust the displayed image, if expecco does not show it right. You can correct the scaling or rotate the image by 90°.
#'''Correct Orientation''': Corrects the image if it is upside down. Using the arrow to the right, the image can also be rotated by 90°, if this should ever be necessary. Since expecco 19.1 you find this functionality under ''Adjust Display''. The orientation of the image is irrelevant for the functionality of the recorder, it only works on the elements it receives.
#'''Scaling''': Changes the scaling of the screenshots.
#'''Messages''': Shows the path of the current selected element or other messages. It has a context menu to show a list of previous messages.

====Usage====
Each click in the window triggers an action and is recorded in the workspace of the GUI browser. There you can run, edit, or create a new block from what you have recorded. You find the actions to trigger softkeys directly in the menu bar (see above). To record actions on elements, either change the selection of the tool in the menu bar (see above) and then click on the element or select the corresponding action from the context menu by right-clicking on the corresponding element. For text input it is also possible to place the cursor over the element and enter the text. This opens the input dialog for this action. On how to use the recorder, see also step 2 in the tutorial ([[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_Block_with_the_Recorder|Android]] resp. [[Mobile_Testing_Tutorial/en#Step_2:_Creating_a_block_with_the_Recorder_2|iOS]]).

====Hide elements====
Since expecco 21.2 it is also possible to hide the selected element in the recorder from the context menu. This means that this element cannot be selected from now on. This function is useful for ignoring elements that are in the foreground to be able to access elements below them. To undo this state, you have to find the corresponding element in the tree of the GUI browser, which also has such an entry in the context menu.

====Automatic Update====
The recorder doesn't show a live image of the device, but only a snapshot. Therefore an update is needed after changes to match what is displayed on the device. The recorder updates automatically after executing an action. Since expecco 20.2 there are further automatic updates possible. You can enable the, in the menu "View".

One option is, to check after an action has been executed, if there are further changes after the first update. If so, a second update is triggered. This shall fix the problem, that the recorder is not up to date after an action, because the update has been done too early.

The second option is to enable a periodical update. After a set interval the recorder is automatically updated if there are changes. Thereby the recorder view is mostly up to date, but this causes an overhead regarding the communication to the device.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid Apps and WebViews =
'''!!! IMPORTANT NOTICE - If you have problems switching to the webview, please set the "Default Application - Browser App" in Android Settings to "Chrome" !!!'''

Hybrid apps contain platform native elements as well as other elements that are integrated in a WebView. These elements can also be used, but you first have to switch to the corresponding context. With the block ''Get Current Context'' you get the current context. Initially this is ''NATIVE_APP'', i.e. the context of the native elements. With the block ''Get Context Handles'' you get a collection of all existing contexts. If there is a WebView context, it is called ''WEBVIEW_1'' or ''WEBVIEW_<package>'' with the package of the WebView. Several WebView contexts are also possible. For each WebView context, there is a corresponding WebView element in the native context. You can use the ''Switch to Context'' block to switch to such a context and from now on only have access to the elements in this context.

In the GUI browser, the existing contexts are displayed at the top of the tree as well as the tree of a context is inserted below the corresponding WebView element.

=Customizing XPath using the GUI Browser=
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen ''GTIN-13 (EAN-13)'' und ''Verify'', das Eingabefeld der Zahl ''4006381333986'' und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des GTIN-13-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch ''Pfad überprüfen'' (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit ''Verify Path: OK'' (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit * zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert ''GTIN-13 (EAN-13)'' besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer ''hierarchy'' (für iOS wäre es ''AppiumAUT''), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix ''android.widget.'', das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend ''XCUIElementType'' am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. ''FrameLayout'' ist ein Kindelement von ''hierarchy'', ''LinearLayout'' ist ein Kind von ''FrameLayout'' usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element ''hierarchy'' beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben ''TextView''-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ ''Button'' gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut ''resource-id''. Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut ''name'' verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem @ eingeleitet und der Wert mit einem = in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter ''Test'' eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf ''Lauf''. Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu ''Eigenschaften'', wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

=Problems and Solutions=
== Locators depend on the version or are variable ==
In this case consider to either store the locators (xPath) in a variable or to define a locator mapping inside a screenplay attachment. It is also possible to store just parts of an locator (e.g. locator path of a parent or attribute value) in a variable and add them in the freeze value of the locator pin by "''$(varName)''".

== Invisible UI Elements ==
Note that the [[#Recorder|Recorder]] also considers items that you cannot see on the screen. Therefore, turn on element highlighting or use the follow mouse function and the element tree in the GUI browser to determine if the correct element is used. It can happen, that invisible elements are in front of other elements and cover them, so that the desired element cannot be selected in the recorder. See section [[#Hide_elements|Hide elements]] for a solution to this.

== iOS: Cable not certified ==
In some cases, when connecting an iOS device via USB, a message appears indicating that the cable used is not certified. In this case, replacing the respective cable is the only solution.

== iOS: Alerts when connecting ==
Make sure that no alerts are open when connecting to an iOS device. Otherwise the connection will fail because the app cannot be brought to the foreground. See also [[#Preparing_an_iOS-Device_and_App|Preparing an iOS-Device and App]].

== iOS: .ipa cannot be installed ==
Note that on iOS simulators no ''.ipa'' files can be installed but only ''.app'' files.

==iOS: First Connect is not working==
If there is not already a signed build of the WebDriverAgent on your Mac, it has to be created during the first connect. Usually, this can take a little longer than one minute. Per default Appium uses a timeout of 60000 ms to wait for the WebDriverAgent to start on the device, so the connect will be canceled in that case. You can set this timeout with the capability ''wdaLaunchTimeout'', e.g. to ''120000''.

Moreover, the signing settings have to be correct. In our experience, the most reliable solution is to set automatic signing in the WebDriverAgent Xcode project an selecting the team there. See the explanation in section [[#Signing_WebDriverAgent|Signing WebDriverAgent]] for that. In this case you should '''not''' use the capabilities ''xcodeConfigFile'' resp. ''xcodeOrgId'' and ''xcodeSigningId'', as they could cause a conflict. Caution: If you have set a Team ID in the Mobile Testing settings, expecco will automatically set this as ''xcodeOrgId''!

Pay attention to your device during the first connect. You might have to agree to the installation by entering your password. On the Mac you might need to enter the password to allow access to the key chain for signing, often several times.

== Android: Device not visible in the connect editor ==
If an Android device connected via USB does not appear in the connection editor, try changing the USB connection type. Usually MTP or PTP should work. Check again, if "USB Debugging" is enabled in the developer options on the device (these options are disabled on some devices and have to be enabled first using a trick.) See also [[#Prepare_Android_Device|Prepare Android Device]].

== Android: Truncated Elements at Bottom ==
For Android devices that automatically show and hide the navigation bar/softkeys, the recorder may cut off elements in the lower area that would be hidden by the softkeys, even if they are not displayed at this time. In this case it is advisable to set the softkeys so that they are permanently displayed.

For newer Android versions there usually is no such option. Even if the controls are visible all the time, they don't have their own space, but are on top of the content of the app. Therefore, there is an area on the lower part of the screen, which cannot be automated, because it is not counted to the active area of the app. Appium will then truncate the elements there. This area can even be larger then the needed by the controls. This is a known issue for Samsung devices with Android 11. Since the information about the size of the app area is already provided on Android level, we cannot offer a solution for this, but can only hope that the problem will be fixed by the manufacturer. You may try to get better results by setting the control to gestures, but this bears the same issue.

== Android: Test Hangs While Finding an Element==
The block ''Find Element by XPath'' and all element blocks wait until an element is present for the given path. The timeout for this can be set either directly at the block or in the environment variables. However, if the element should already be present, but the test doesn't continue anyway, the reason could be in the UIAutomator/UIAutomator2. It waits for the app to go to the idle state before it even starts to search for the element. This may take longer, if the app e.g. runs an animation in the background or executes other kinds of actions. Fetching the page source, e.g. when updating in the GUI browser or in the recorder, can also take longer for this reason. There is a default timeout of 10 seconds after which it no longer waits for the idle state. This timeout can be set in Appium (waitForIdleTimeout). If you want to change the value of this timeout, you can do this since expecco 21.2 by executing the Smalltalk code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> before the test. The timeout is given in milliseconds, so the example sets it to 2 seconds.

==Android: Updating the Tree or Switching to Webview Context takes too long==
Especially with older devices it can happen that newer Chromedriver cannot be initialized. This makes it impossible to switch to the webview context. However, this is only detected over a timeout by Appium, which is 4 minutes by default. Since expecco also tries to switch to the webview context when building the tree in the GUI browser, this can lead to very long loading times. Since there is no way to decrease this timeout in Appium, we have added a corresponding capability to the version we provide in the MobileTestingSupplement. Starting with version 1.13.1.0 of the [[#Windows|MobileTestingSupplement]], ''chromedriverStartTimeout'' can be used to set the timeout in milliseconds. The switch still doesn't work then, but expecco doesn't take as long to update the tree and the context switch module fails faster. The connection dialog adds this capability automatically starting with expecco 22.1.

== No Action on Click ==
The block to click on an element is successful, but no action was performed on the device.
:This can happen if the element is hidden by another element and therefore clicking on the element is not possible. In this case, Appium does not throw an error, but simply nothing happens. If you would like to make a click at the position of the element anyways, even if it is hidden, use the block ''Tap'' instead and pass the location of the element to it (''Get Location''). If instead you want to check before a click whether the element is hidden at this moment, try whether the properties ''Is Displayed'' or ''Is Enabled'' might help you.

== No Update After Action ==
An action was triggered on the recorder and a block has been recorded, but the recorder still shows the old image.
:The recorder doesn't show a live image of the device, but only a snapshot. After an action has been executed, the recorder will update automatically. However, it can happen, that the image has already been updated before the effects of the action are fully completed on the device. In this case you should update the recorder by hand using the icon with the blue arrows. Since expecco 20.2 you can also enable automatic updates for this case. See also the description for the [[#Recorder|recorder]].

== Attribute "clickable" is wrong ==
An element has for the attribute/property "''clickable''" the value "''false''", but is actually clickable.
:The attribute "''clickable''" has to be set explicitly by the app developer and does not affect the behavior of the app. You should generally disregard this attribute in your tests. Unfortunately, many apps exist where the programmer was "lazy" about this.

==Connecting Fails==
If the connection to the Appium server fails, you will receive an error message in expecco similar to the one shown below.

[[File:MobileTestingVerbindungsfehler.png]]

Here you can see the type of error that has occurred. Click on "''Details''" to get more information. Possible errors are:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:The specified server is not running or is not reachable. Check the server address.
*''org.openqa.selenium.WebDriverException''
:Read the message after ''Original Error'' in the first line of the details:
:*''Unknown device or simulator UDID''
::Either the device is not connected properly or the udid is not correct.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::This error can have various causes. Either the WebDriverAgent could actually not be built because the signing settings are wrong or the appropriate provisioning profile is missing. Please read the section about [[#Signing|Signing]]. It is also possible that the WebDriverAgent cannot be started on the device, for example because an alert is in the foreground or you did not trust the developer.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::The specified app cannot be installed on the iOS device because it is not entered in the app's Provisioning Profile.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.''
::The path to the app is wrong. Make sure that the file is located in the specified path on your Mac.
:*''packageAndLaunchActivityFromManifest failed.''
::The specified ''apk'' file is probably broken.
:*''Could not find app apk at [...]''
::The path to the app is wrong. Make sure that the ''apk'' file is located in the specified path.

If the error is not due to one of the causes listed above, the automation applications on the device may no longer function properly. In this case it helps to uninstall them from the mobile device. They are then automatically reinstalled the next time a connection is established.

*For iOS devices, this is the WebDriverAgent, which you can simply uninstall from the home screen. This usually solves problems caused by changing the used Mac or the Xcode version.

*For Android devices, it is the UIAutomator2; here, a problem occurs sporadically on some devices, the cause is currently unknown to us. To uninstall, on the device, navigate to "''Settings''" > "''Applications''"* and search the list for the following entries:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Click on the respective application and then on "''Uninstall''".
*''The corresponding entry may have a slightly different name on some devices.''

If this doesn't help, check the output of the Appium server. For a server started by expecco, you can find the log in the list of [[#Running_Appium_Servers|Running Appium Servers]].

==I do not have a Mac==
Maybe this site will help you: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin

2023-11-30T11:01:38Z

Matilk: /* Probleme und Lösungen */ erster Verbindungsaufbau iOS

'''Deutsche Version''' | [[Mobile_Testing_Plugin/en|English Version]]

= Einleitung =
Mit dem ''Mobile Testing Plugin'' können Anwendungen auf Android- und iOS-Geräten getestet werden. Dabei ist es egal, ob reale mobile Endgeräte oder emulierte Geräte verwendet werden. Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests unterstützt. Zudem ist damit das Aufzeichnen von Testabläufen möglich.

Zur Verbindung mit den Geräten wird [http://appium.io/ Appium] verwendet. Appium ist ein freies Open-Source-Framework zum Testen und Automatisieren von mobilen Anwendungen.

Zur Einarbeitung in das Mobile Plugin empfehlen wir das [[Mobile_Testing_Tutorial|Tutorial]] zu bearbeiten. Dieses führt anhand eines Beispiels Schritt für Schritt durch die Erstellung eines Testfalls und erklärt die nötigen Grundlagen.

= Installation und Aufbau =
Zur Verwendung des Mobile Testing Plugins müssen Sie expecco inkl. des Plugins Mobile Testing installiert haben und Sie benötigen die entsprechenden Lizenzen. expecco kommuniziert mit den Mobilgeräten über einen Appium-Server, der entweder auf demselben Rechner wie expecco läuft, oder auf einem zweiten Rechner. Dieser muss für expecco erreichbar sein.

==Installationsübersicht==

'''Rechner, auf dem expecco läuft:'''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem Android-Geräte angeschlossen sind:'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Android SDK'', dieses erhalten Sie ebenfalls mit dem Mobile Testing Supplement''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem iOS-Geräte angeschlossen sind2):'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement für Mac OS installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Xcode ''in einer Version, die die verwendete iOS-Version unterstützt, erhältlich über den Apple App Store''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
* Apple-Entwickler-Zertifikat mit zugehörigem privaten Schlüssel ''(zum Signieren des WebDriverAgents)''
* Provisioning Profile mit den verwendeten Mobilgeräten

Je nach Aufbau können die oben genannten Rechner auch das selbe Gerät sein. expecco kann sich sowohl über das Netzwerk mit einem entfernten Appium-Server und dort angeschlossenen Mobilgeräten verbinden, als auch lokal selbst einen Appium-Server starten und diesen mit lokalen Mobilgeräten verwenden. Einige Funktionen von expecco, die die Erstellung von Testfällen erleichtern, sind jedoch nur verfügbar, wenn die Mobilgeräte am selben Rechner angeschlossen sind, auf dem auch expecco läuft. Ein möglicher Aufbau kann daher wie in folgender Abbildung aussehen:

[[Datei:MobileTestingAufbau.png | 400px]]

Im Folgenden wird die Installation von Appium und anderer nötiger Programme für Windows und Mac OS erklärt.

1): Zum Zeitpunkt der Erstellung dieses Dokuments wurden Versionen bis 11 auf Funktion verifiziert. Neuere Versionen sollten - sofern nicht grundlegende Änderungen von Oracle vorgenommen wurden, ebenfalls funktionieren.

2): Beachten Sie, dass aufgrund der Voraussetzungen (keine Anbindung an nicht-Apple Geräte verfügbar) iOS-Geräte nur von einem Mac aus angesteuert werden können. Sie benötigen also einen Mac als "Vermittler" (siehe auch unten: [[#Ich habe keinen Mac | "Ich habe keinen Mac"]])

== Windows ==
Am einfachsten installieren Sie alles mit unserem Mobile Testing Supplement1. In neueren Versionen ist allerdings aufgrund geänderter Lizenzbedingungen seitens Oracle kein JDK mehr enthalten, sodass sie dieses zusätzlich installieren müssen. Sie können natürlich Appium auch direkt installieren, um die Version zu verwenden, die Sie möchten. Um dann einen Appium-Server mit expecco starten zu können, muss allerdings eine entsprechende Batchdatei vorhanden sein und in den [[Mobile_Testing_Plugin#Konfiguration_des_Plugins|Einstellungen]] angegeben werden. Verbindungen können aber auch zu anderen laufenden Appium-Servern aufgebaut werden.
*'''expecco 23.1''': [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Gleiche Versionen wie der Vorgänger, aber der Installer erlaubt nun, Appium zum Autostart hinzuzufügen.
*expecco 22.2 und 22.1: [https://download.exept.de/transfer/h-expecco-22.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 aus platform-tools 33.0.2
:''* Wir haben Appium um die Capability'' startChromedriverTimeout ''erweitert, um schneller einen Timeout zu bekommen, wenn der Chromedriver nicht gestartet werden kann. (siehe [[#startChromedriverTimeout|Probleme und Lösungen]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Enthält die Appium-Version 1.22.0, Node ist weiterhin in der Version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Nur kleine Änderungen im Vergleich zur vorigen Version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und node 12 verwendet.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:Dieses installiert Appium in der Version 1.12.0 und enthält nun zusätzlich build-tools der Version 28.0.3 im android-sdk. Ansonsten ist es gleich wie die vorige Version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:Dieses installiert Appium in der Version 1.8.1. Außerdem bietet das Supplement auch an, ''Android Debug Bridge'' und ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) zu installieren. Damit sind Treiber für ein breites Spektrum an Android-Geräten abgedeckt, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen. Ein '''JDK ist (aufgrund geänderter Lizenzbedingungen seitens Oracle) nicht mehr enthalten''', dieses müssen Sie selbst herunterladen, z.B. von [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: wie expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.6.4. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.4.16. Während der Installation wird die grafische Oberfläche von Appium gestartet, dieses Fenster können Sie sofort wieder schließen. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.

Wenn expecco Mobilgeräte verwenden soll, die an einem anderen Rechner angeschlossen sind, müssen Sie dort einen Appium-Server starten. Dies können Sie mit der Datei <code>appium_standalone.cmd</code> tun. Der Server wird dann mit dem Standard-Port 4723 gestartet. Falls Sie eine andere Portnummer verwenden wollen, starten Sie den Server mit

appium_standalone.cmd -p <portnummer>

Der Server ist bereit, sobald die Zeile
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
angezeigt wird, wobei Sie am Ende die verwendete Portnummer ablesen können.

Beim ersten Starten von Appium – sowohl im Standalone als auch gestartet von expecco – kann es vorkommen, dass die Windows-Firewall den Node-Server blockiert. Lassen Sie den Zugriff zu, sonst kann Appium nicht gestartet werden.

1) Sie können natürlich auch die Command Line Tools (adb, sdkmanager, avdmanager etc.) einer vorhandenen Android Studio Version verwenden, sowie Appium separat installieren.
Da sich diese Tools regelmäßig ändern, und es in der Vergangenheit zu Inkompatibilitäten und Fehlern nach Releasewechseln kam, empfehlen wir zu Beginn, das mitgelieferte Paket zu verwenden. Dies ist möglicherweise nicht das aktuellste, wurde aber auf Lauffähigkeit getestet.

Falls das Android Mobilgerät an einem entfernen Rechner angeschlossen ist,
können Sie den aktuellen Bildschirminhalt z.B. mit dem [https://github.com/Genymobile/scrcpy scrcpy] tool live mitverfolgen.

== Mac OS (nicht erforderlich für Android-Tests)==
Hinweis: Wenn Sie nicht vorhaben, iOS-Geräte (iPhone, iPad, etc.) zu testen, können Sie das Folgende ignorieren. '''Der Apple-Rechner sowie das Mac-Setup werden für Android-Geräte nicht benötigt'''.

=== Xcode ===
Zur Automatisierung mit iOS-Geräten wird [https://developer.apple.com/xcode/ Xcode] benötigt. Sie erhalten dieses über den App Store. Dabei ist darauf zu achten, dass die Version zu den getesteten iOS-Versionen passt.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
Diese Tabelle gibt nur eine vereinfachte Übersicht, lesen Sie besser unter [https://xcodereleases.com/ Xcode Releases] oder [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode-Versionen] welche Version Sie brauchen. Für neue iOS Minor-Versionen gibt es in der Regel auch ein Update für Xcode, z.B. brauchen Sie für iOS 10.2 mindestens Xcode 8.2, für iOS 10.3 mindestens Xcode 8.3 usw.
Wenn Sie also auf eine neuere iOS-Version wechseln, benötigen Sie in der Regel auch eine neuere Xcode-Version. Neuere Versionen von Xcode laufen möglicherweise nicht auf älteren Betriebssystemen, was wiederum eine Aktualisierung des Betriebssystems erforderlich machen kann. Falls Sie auch ältere iOS-Versionen testen wollen kann es sinnvoll sein, die entsprechenden Xcode-Versionen parallel zu installieren.

=== Appium ===
Der Appium-Server kann entweder als Kommandozeilen-Anwendung installiert werden oder über [https://github.com/appium/appium-desktop Appium Desktop] verwendet werden, welcher den Server über ein GUI zur Verfügung stellt. Mittlerweile gibt es auch Appium 2.0, was wir aber bisher noch nicht mit expecco getestet haben und daher nicht empfehlen.

==== Appium Desktop ====
Laden Sie die neueste Version von [https://github.com/appium/appium-desktop/releases/ Appium Desktop] herunter. Für den Mac nehmen Sie am besten die dmg-Datei und installieren sie in den Anwendungen. Beim Starten der Anwendung ''Appium Server GUI'' erhalten Sie wahrscheinlich eine Fehlermeldung, dass es aus Sicherheitsgründen nicht möglich ist. Öffnen Sie dann das Kontextmenü auf der Anwendungsdatei (Rechtsklick bzw. Strg + Klick) und wählen Sie dort ''Öffnen'' aus. Bestätigen Sie dann, dass Sie die Anwendung wirklich öffnen wollen. Fortan können Sie die Anwendung normal öffnen.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Ab Xcode 14 gibt es Probleme beim Signieren des WebDriverAgents, den Appium zur Automatisierung auf das Gerät spielt. Dadurch ist mit der Version 1.22.3-4 von Appium Desktop kein Verbindungsaufbau möglich. Das Problem ist in neueren Versionen des WebDriverAgents behoben, es gibt aber aktuell noch keine Version von Appium Desktop, die eine solche Version enthält (Stand November 2022). Sie können aber manuell eine neue Version herunterladen (z.B. 4.10.2) und die Dateien in Appium ersetzen. Laden Sie dazu von der [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent Download-Seite] eine der beiden Archivdateien (zip oder tar.gz) mit dem Source Code herunter. Öffnen und entpacken Sie dann diese Datei. Den Inhalt des Ordners WebDriverAgent-4.10.2 müssen Sie nun nach

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

kopieren. Wenn Sie über den Finder dorthin navigieren, machen Sie auf die Anwendung ''Appium Server GUI'' einen Kontextklick (Rechtsklick bzw. Strg + Klick) und wählen Sie im Menü ''Paketinhalt anzeigen''. Ersetzen Sie alle Dateien, die bereits mit gleichem Namen enthalten sind.

==== Appium über npm installieren ====
Sie können Appium auch über npm (Node Package Manager) installieren. Dazu müsen Sie erst node/npm installieren. Das geht mit [https://github.com/nvm-sh/nvm nvm] (Node Version Manager) was Sie von Github bekommen. Falls die folgende Installationsanleitung bei Ihnen nicht funktionieren sollte, finden Sie dort ausführlichere Informationen im [https://github.com/nvm-sh/nvm#readme Readme].

Öffnen Sie ein Terminal-Fenster. Klonen Sie dann das Github-Repository von nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
und laden Sie es
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Führen Sie danach
command -v nvm
aus, um zu testen, ob es funktioniert hat. Es sollte ''nvm'' ausgegeben werden. Kommt keine Antwort, führen Sie
touch ~/.zshrc
aus, und versuchen Sie es erneut.

Nun können Sie node mit dem folgenden Befehl installieren.
nvm install 16.15.1
Da es mit der aktuellen Version von node Probleme beim Installieren von Appium gibt, empfehlen wir diese Version.

Nachdem node installiert ist, können Sie Appium darüber installieren:
npm install -g appium

Den Appium-Server können Sie nun einfach über den Befehl
appium
starten. Die Ausgabe erfolgt dann direkt im Terminal.

Auch bei dieser Version gibt es das Problem bei der Signierung des WebDriverAgents, wie bei [[#Appium_Desktop | Appium Desktop]] beschrieben. Laden Sie also auch in diesem Fall eine neuere Version des WebDriverAgents herunter und ersetzen Sie die alten Dateien. Diese finden Sie unter
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
Ältere Appium-Versionen stellen wir Ihnen über das Mobile Testing Supplement für Mac OS zur Verfügung, mit dem Sie es einfach installieren können:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.2)]
:Enthält Appium Version 1.18.3 und verwendet node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.0)]
:Nur wenige Änderungen im Vergleich zur vorigen Version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.98)]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und es wird node 12 verwendet.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.96)]
:Diese Version enthält Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.94)]
:Diese Version enthält Appium 1.8.0.

* expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.0.94)]
:Diese Version enthält Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement für Mac OS]
:Diese Version entält Appium 1.4.16.

Nachdem Herunterladen des Supplements, können Sie es in ein Verzeichnis Ihrer Wahl (z. B. Ihr Home-Verzeichnis) verschieben und dort entpacken. Ein geeigneter Befehl in einer Shell könnte wie folgt aussehen, passen Sie dabei die Versionsnummer entsprechend an:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

Wenn Sie Ihre Standard-Xcode-Installation verwenden wollen, können Sie Appium direkt über die Datei im ''bin''-Verzeichnis mit der entsprechenden Versionsnummer starten:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Falls Sie ein anderes Xcode als das als Standard konfigurierte verwenden wollen, müssen Sie Appium den entsprechenden Pfad über die Umgebungsvariable ''DEVELOPER_DIR'' angeben.
Wenn Sie Xcode z. B. in ''/Applications/Xcode-11.3.app'' installiert haben, müssten Sie Appium so starten:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Was als Standard-Xcode-Installation gesetzt ist, zeigt der Befehl:

xcode-select -p

Wenn Appium Ihre Xcode-Installation nicht findet, erscheint beim Verbinden eine Fehlermeldung in der Art:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
Starten Sie in diesem Fall Appium erneut, unter Angabe eines gültigen ''DEVELOPER_DIR''.

==== WebDriverAgent-Signierung ====
Zur Automatisierung lädt Appium eine App namens WebDriverAgent auf das Gerät und muss sie dafür signieren können. Dazu brauchen Sie einen Apple-Account und ein entsprechendes Zertifikat. Zur Evaluierung können Sie einen kostenlosen Account verwenden. Dieser hat den Nachteil, dass erstellte Profile nur eine Woche gültig sind und danach neu erstellt werden müssen. Seien Sie auch vorsichtig, wenn Sie sich den Account teilen, da es vorkommen kann, dass Zertifikate widerrufen werden oder durch automatische Generierung ungültig werden. Als Folge können bereits signierte Apps nicht mehr verwendet werden.

Wenn Sie bereits ein entsprechendes Zertifikat mit dem zugehörigen privaten Schlüssel in Ihrer [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac haben, können Sie den WebDriverAgent automatisch signieren lassen. Ansonsten empfiehlt es sich, die Signierung über Xcode einzustellen und zu verwalten.

Schließen Sie zuerst das Gerät, das Sie verwenden möchten, über USB an den Mac an. Stellen Sie sicher, dass sich der Mac und das Gerät im selben Netzwerk befinden, ansonsten kann es beim Verbindungsaufbau mit Appium zu Problemen kommen. Starten Sie Xcode und öffnen Sie ''Preferences''. Wechseln Sie zur Seite der Accounts und legen Sie einen Eintrag mit Ihrem Account an. Anschließend können Sie auf ''Manage Certificates...'' klicken, um die Zertifikate zu sehen, die zu diesem Account gehören. Zum Ausführen von Tests benötigen Sie ein iOS-Development-Zertifikat und den dazugehörigen privaten Schlüssel. Wenn Sie noch keines besitzen, erstellen Sie eines. Wenn Sie bereits eines haben, aber es nicht in Ihrem Schlüsselbund vorhanden ist (erkennbar an dem Hinweis "Not in Keychain"), können Sie es importieren. Das können Sie über die [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac machen, wenn Sie es zuvor aus dem Schlüsselbund exportiert haben, in dem es sich befindet. Das Zertifikat mit dem zugehörigen Schlüssel sollte sich im Schlüsselbund ''Anmeldung'' befinden. Dort kann es als PKCS#12-Datei (Endung typischerweise .p12) exportiert werden. Um ein Zertifikat in Ihren Schlüsselbund zu importieren, wählen Sie im Menü ''Ablage'' die Option ''Objekte importieren''. Falls Sie nicht wissen, wo das Zertifikat gespeichert ist, können Sie es in Xcode auch widerrufen und in Ihrem Schlüsselbund neu anlegen. Machen Sie das jedoch nur, wenn Sie wissen, dass das alte Zertifikat nicht mehr in Verwendung ist, da es danach nicht mehr benutzt werden kann. Nun sollte Ihr Schlüsselbund ein iOS-Development-Zertifikat enthalten.


Öffnen Sie nun das WebDriverAgent-Projekt in Xcode. Wenn Sie das Mobile Testing Supplement installiert haben, finden Sie es in dessen Verzeichnis unter
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
Wenn Sie Appium Desktop installier haben, finden Sie es unter
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''
Sie können einfach im Finder zu der Xcode-Project-Datei navigieren und Sie über einen Doppelklick öffnen. Beachten Sie dabei, dass Sie dabei auf die Anwendung Appium Server GUI einen Kontextklick (Rechtsklick bzw. Strg + Klick) machen und im Menü ''Paketinhalt anzeigen'' auswählen müssen, um in deren Unterverzeichnis zu gelangen.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Wählen Sie ''WebDriverAgentLib'' und die Seite ''Signing & Capabilities'' aus. Setzen Sie dort im Abschnitt ''Signing'' die Option ''Automatically manage signing'' und wählen Sie dann ein Team aus. Wechseln Sie nun zu ''WebDriverAgentRunner'' und tun Sie dort dasselbe.

Durch das Setzen des Teams sollten die Fehler für den WebDriverAgentRunner verschwinden. Sollte Xcode kein passendes Provisioning Profile für die Bundle ID ''com.facebook.WebDriverAgentRunner'' erstellen können, können Sie diese anpassen, dass sie zu Ihrem Zertifikat passt. Danach können Sie Xcode beenden oder auch, wie weiter unten beschrieben, direkt den Build über Xcode starten, damit das Projekt bereits gebaut ist, wenn Appium es verwenden möchte.

Wenn Sie sich nun von expecco eine Verbindung zu Ihrem Gerät aufbauen, wird der WebDriverAgent darauf installiert und gestartet, um anschließend zur zu testenden App zu wechseln. Eventuell muss auf dem Gerät muss der Ausführung des WebDriverAgents vertraut noch werden. Ein Anzeichnen dafür kann sein, dass die App WebDriverAgent zwar auf dem Gerät erscheint und zu starten versucht, danach aber wieder deinstalliert wird. Öffnen Sie dazu während des Verbindungsaufbaus auf dem Gerät in die Einstellungen und dort unter ''Allgemein'' den Eintrag ''Geräteverwaltung''. Dieser Eintrag ist nur sichtbar, wenn eine Entwickler-App auf dem Gerät installiert ist. Sie müssen daher möglicherweise warten, bis der WebDriverAgent installiert ist, bevor der Eintrag erscheint. Wählen Sie dort den Eintrag Ihres Apple-Accounts und vertrauen Sie ihm. Da der WebDriverAgent wieder deinstalliert wird, wenn der Start nicht funktioniert hat, müssen Sie dies während des Verbindungsaufbaus tun. Falls Ihnen das zu hektisch ist, können Sie auch folgenden Code ausführen:

<nowiki>xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test</nowiki>
bzw.
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

Damit wird der WebDriverAgent auf dem Gerät installiert ohne dass er wieder gelöscht wird.

Wenn es Probleme beim Installieren des WebDriverAgents gibt, können Sie auch versuchen, den Build über Xcode zu starten. Stellen Sie sicher, dass das richtige Target ''WebDriverAgent'' ausgewählt ist. Fehlermeldungen in Xcode zeigen vielleicht einfacher, wo das Problem liegt. Manchmal hilft es auch, es ein zweites Mal zu versuchen, weil es möglicherweise beim ersten Mal zu lange gedauert hat und abgebrochen wurde. Es kann sein, dass Sie während des Builds mehrmals aufgefordert werden, das Passwort für Ihren Schlüsselbund anzugeben.

[[Datei:WebDriverAgentCodesign.png]]

Lesen Sie auch die Dokumentation von Appium zum [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Aufsetzen von Tests mit iOS-Geräten]. In der [https://support.apple.com/en-us/HT204460 Dokumentation von Apple] finden Sie nähere Informationen zum Installieren und Vertrauen von Apps.

Ist der WebDriverAgent einmal auf dem Gerät installiert, wird er für spätere Verbindungen wieder verwendet und der Verbindungsaufbau sollte schneller funktionieren. Ebenso liegt dann die signierte Version bereits auf Ihrem Mac und muss nicht erneut gebaut werden, was die Verbindung zu weiteren Geräten ebenfalls beschleunigt. Wenn Sie wissen, dass bei Ihrem Verbindungsaufbau der WebDriverAgent erst noch signiert und gebaut werden muss, ist es ratsam, die Capability ''wdaLaunchTimeout'' zu setzen. Dieser Timeout, wie lange auf den Start der WebDriverAgents auf dem Gerät gewartet werden soll, liegt standardmäßig bei 60000 ms. Der Build dauert aber häufig über eine Minute, sodass der Versuch zum Verbindungsaufbau dann abgebrochen wird. Ein Wert von 120000 hat sich hier als besser erwiesen.

== Konfiguration des Plugins ==
Bevor Sie loslegen, sollten Sie die Einstellungen des Mobile Testing Plugins überprüfen und ggf. anpassen.

Öffnen Sie im Menü den Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" den Eintrag "''Mobile Testing''" (s. Abb.). Standardmäßig werden diese Pfade automatisch gefunden (1). Um einen Pfad manuell anzupassen, deaktivieren Sie den entsprechenden Haken rechts davon. Sie erhalten in einer Drop-down-Liste einige Pfade zur Auswahl. Ist ein eingetragener Pfad falsch oder kann er nicht gefunden werden, wird das Feld rot markiert und es erscheint ein diesbezüglicher Hinweis. Stellen Sie sicher, dass alle Pfade richtig angegeben sind.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Konfiguration des Plugins]]

*'''appium''': Geben Sie hier den Pfad zur ausführbaren Datei an mit der Appium in der Kommandozeile gestartet werden kann. Unter Windows wird diese Datei in der Regel "<code>appium.cmd</code>" heißen. Dieser Pfad wird benutzt, wenn expecco einen Appium-Server startet.
*'''node''': Geben Sie hier den Pfad zur ausführbaren Datei an, die Node (auch "Node.js") startet. Dieser Pfad wird beim Starten eines Servers an Appium weitergegeben, damit Appium ihn unabhängig von der PATH-Variablen findet. Unter Windows heißt diese Datei in der Regel "<code>node.exe</code>".
*'''JAVA_HOME''': Geben Sie hier den Pfad zu einem JDK an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden. Um einzustellen, welches Java von expecco verwendet werden soll, setzen Sie diesen Pfad in den Einstellungen für die Java Bridge.
*'''ANDROID_HOME''': Geben Sie hier den Pfad zu einem SDK von Android an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden.
*'''adb''': Hier steht der Pfad zum adb-Befehl. Unter Windows heißt die Datei adb.exe. Diese wird von expecco beispielsweise verwendet, um die Liste der angeschlossenen Geräte zu erhalten. Diesen Pfad sollten Sie automatisch wählen lassen, da dann der Befehl im ANDROID_HOME-Verzeichnis verwendet wird. Dieser wird auch von Appium verwendet. Falls expecco und Appium jedoch verschiedene Versionen von adb verwenden kann es zu Konflikten kommen.
*'''android.bat''': Diese Datei wird nur benötigt, um damit den AVD und den SDK Manager zu starten. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.
*'''aapt''': Geben Sie hier den Pfad zum aapt-Befehl an. Unter Windows heißt diese Datei ''aapt.exe''. expecco verwendet aapt nur im Verbindungseditor, um das Paket und die Activities einer apk-Datei zu lesen. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | Konfiguration des JDKs]]

Ab expecco 2.11 gibt es das Feld ''Team-ID''. Wenn Sie iOS-Tests ausführen, tragen Sie hier die Team-ID Ihres Zertifikats ein. Diese wird für jede iOS-Verbindung verwendet, außer Sie setzen den Wert im Einzelfall in den Verbindungseinstellungen um. Wie Sie die Team-ID erhalten, lesen Sie im Abschnitt zur [[#Signierung|Signierung]] ber der Installation auf Mac OS. Mit expecco 2.10 können Sie die Team-ID nur für jede Verbindungseinstellung extra als Capability eintragen. Dazu müssen Sie jedoch die [[#Erweiterte_Ansicht|erweiterte Ansicht]] verwenden. Geben Sie hier die Capability ''xcodeOrgId'' an und setzen Sie als Wert die Team-ID des Zertifikats.

Die Einstellung zur Serveradresse unten auf der Seite bezieht sich auf das Verhalten des Verbindungseditors. Dieser prüft am Ende, ob die Serveradresse auf ''/wd/hub'' endet, da dies die übliche Form ist. Falls nicht, wird in einem Dialog gefragt, wie darauf reagiert werden soll. Das festgelegte Verhalten kann hier eingesehen und verändert werden.

Wechseln Sie ebenfalls zum Eintrag ''Java Bridge'' (s. Abb.). Hier muss der Pfad zu Ihrer Java-Installation angegeben werden, die von expecco benutzt wird. Tragen Sie hier ein JDK ein. Falls Sie unter Windows das aus dem Mobile Testing Supplement verwenden möchten, lautet der Pfad
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
Sie können auch die Systemeinstellungen verwenden.

== Android-Gerät vorbereiten ==
Wenn Sie ein Android-Gerät unter Windows anschließen benötigen Sie möglicherweise noch einen adb-Treiber für das Gerät. Einen passenden Treiber finden Sie üblicherweise auf der jeweiligen Webseite des Herstellers. Haben Sie den Universal-Treiber aus dem Mobile Testing Supplement installiert, sollte für die meisten Geräte bereits alles funktionieren. In einigen Fällen versucht auch Windows automatisch einen Treiber zu installieren, wenn Sie das Gerät zum ersten mal anschließen.
 
===USB-Debugging Einschalten===
'''Achtung:'''
Bevor Sie ein Mobilgerät mit dem Appium-Plugin ansteuern können, müssen Sie für dieses Debugging erlauben!

Für Android-Geräte finden Sie diese Option in den Einstellungen unter ''[https://www.droidwiki.org/wiki/Entwickleroptionen Entwickleroptionen]'' mit dem Namen ''[https://www.droidwiki.org/USB-Debugging USB-Debugging]''. Falls die Entwickleroptionen nicht angezeigt werden, können Sie diese freischalten, indem Sie unter "''Über das Telefon''" siebenmal auf "''Build-Nummer''" tippen.

===Wach bleiben Aktivieren===
Aktivieren Sie auch die Funktion ''Wach bleiben'', damit das Gerät nicht während der Testerstellung oder -ausführung den Bildschirm abschaltet.

Aus Sicherheitsgründen muss USB-Debugging für jeden Computer einzeln zugelassen werden. Beim Verbinden des Geräts mit dem PC über USB müssen Sie dabei am Gerät der Verbindung zustimmen. Falls Sie dies für Ihren Computer noch nicht getan haben, aber auf dem Gerät kein entsprechender Dialog erscheint, kann es helfen, das Gerät aus- und wieder einzustecken. Das kann insbesondere dann passieren, wenn Sie den ADB-Treiber installiert haben während das Gerät bereits über USB angeschlossen war. Falls auch das nicht hilft, öffnen Sie die Benachrichtigungen, indem Sie sie vom oberen Bildschirmrand herunter ziehen. Dort finden Sie die USB-Verbindung und Sie können die Optionen dazu öffnen. Wählen Sie einen anderen Verbindungstypen aus; in der Regel sollten MTP oder PTP funktionieren.

Sie können auch auf einem Emulator testen. Dieser muss nicht gesondert vorbereitet werden, da er bereits für USB-Debugging ausgelegt ist. Es ist sogar möglich, einen Emulator bei Testbeginn zu starten.

Um zu überprüfen, ob ein Gerät, das Sie an Ihren Rechner angeschlossen haben, verwendet werden kann, öffnen Sie den [[#Verbindungseditor|Verbindungseditor]]. Das Gerät sollte dort angezeigt werden.

=== Verbindung über WLAN ===
Es ist auch möglich, Android-Geräte über WLAN zu verbinden. Für Geräte mit Android 11 oder neuer ist dies direkt über WLAN möglich, im anderen Fall müssen Sie das Gerät zuerst über USB verbinden. Ab expecco 22.1 können Sie eine WLAN-Verbindung über den [[Mobile Testing Plugin#Verbindungseditor|Verbindungseditor]] aufbauen. Ansonsten ist es auch über die Eingabeaufforderung möglich.
==== Drahtlos verbinden über die Eingabeaufforderung mit expecco Versionen vor 22.1 (ab Android 11) ====
Mit expecco ab Version 22.1 funktioniert das einfacher über den Verbindungseditor.

Erlauben Sie in den Entwickleroptionen des Geräts Debugging über WLAN und öffnen Sie dessen Optionen. Sie müssen zuerst das Gerät mit dem Rechner koppeln. Wählen Sie dazu "''Gerät mit einem Kopplungscode koppeln''", um einen Kopplungscode und eine IP-Adresse mit Port zu erhalten. Öffnen Sie dann auf dem Rechner die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb pair <IP-Adresse des Geräts>:<Kopplungsport></nowiki>
wobei Sie <tt><IP-Adresse des Geräts>:<Kopplungsport></tt> durch die auf dem Gerät angezeigte IP-Adresse & Port ersetzen. Danach werden Sie aufgefordert, den Kopplungscode einzugeben. Wenn alles geklappt hat, sollte sich das Popup auf dem Gerät schließen und der Rechner als gekoppeltes Gerät angezeigt werden. Geben Sie dann in der Eingabeaufforderung ein:
<nowiki>adb connect <IP-Adresse des Geräts>:<Debug-Port></nowiki>
Die IP-Adresse ist hier noch die gleiche wie beim Koppeln, aber der Port ist ein anderer. Beides wird als IP-Adresse & Port auf dem Gerät angezeigt. Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie entweder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden. Häufig wird beim Neustart des Geräts auch die Erlaubnis für das Debugging über WLAN wieder zurückgesetzt und der verwendete Port ändert sich. Die Kopplung bleibt aber bestehen und muss beim nächsten Verbinden nicht noch einmal durchgeführt werden.

==== WLAN Verbindung über USB starten (Android 10 und früher) ====
Verbinden Sie zunächst das Gerät über USB mit dem Rechner. Öffnen Sie dann die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb tcpip 5555</nowiki>
Damit lauscht das Gerät auf eine TCP/IP-Verbindung an Port 5555. Sollten Sie mehrere Geräte angeschlossen oder Emulatoren laufen haben, müssen Sie genauer angeben, welches Gerät Sie meinen. Geben Sie in diesem Fall ein:
<nowiki>adb devices -l</nowiki>
Sie erhalten eine Liste aller Geräte, wobei die erste Spalte deren Kennung ist. Schreiben Sie dann stattdessen
<nowiki>adb -s <Gerätekennung> tcpip 5555</nowiki>
mit der Gerätekennung des gewünschten Geräts. Sie können die USB-Verbindung nun trennen. Jetzt müssen Sie die IP-Adresse Ihres Gerätes in Erfahrung bringen. Sie finden diese üblicherweise irgendwo in den Einstellungen des Geräts, beispielsweise beim Status oder in den WLAN-Einstellungen. Geben Sie dann ein:
<nowiki>adb connect <IP-Adresse des Geräts></nowiki>
Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie wieder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden.

=== Verbindung zu einem Emulator ===
Sie benötigen dazu den Emulator selbst, sowie mindestens ein AVD (Android Virtual Device). Hinweise zu Installation finden Sie in der [https://developer.android.com/studio/run/emulator Android Studio Dokumentation].

Wenn Sie Android Studio bereits mit den Defaulteinstellungen installiert haben 1), sollte der Emulator bereits mitinstalliert sein. Falls nicht, wählen Sie in Android Studio "''Configure''" - "''SDK Manager''" - "''Android SDK''" - "''SDK Tools''" - ''Android Emulator''", sowie dort die "''Platform Tools''".
Alternativ geht das auch über die Kommandzeile mit dem "sdkmanager" Kommando.

Als nächstes benötigen Sie mindestens ein AVD; auch dies geht am einfachsten über den Dialog in Android Studio:
wählen sie "''Configure''" - "''AVD Manager''" und folgen den Anweisungen (Deviceauswahl, Platform und Android Version).

Auch wenn Sie den Emulator automatisieren benötigen sie Appium; installieren Sie dieses entweder mit dem Mobile Testing Supplement, oder direkt von der Appium homepage (https://github.com/appium/appium-desktop/releases).

1)Android Studio selbst wird nicht von expecco benötigt; es bietet aber kompfortable Dialoge zum Installieren von Paketen und AVDs.

== iOS-Gerät und App vorbereiten ==
Das Ansteuern von iOS-Geräten ist nur über einen Mac möglich. Lesen Sie daher auch den Abschnitt zur [[#Mac_OS|Installation unter Mac OS]].

Bevor Sie ein Mobilgerät mit dem Mobile Testing Plugin ansteuern können, müssen Sie für iOS-Geräte ab iOS 8 Debugging erlauben. Aktivieren Sie dazu die Option ''Enable UI Automation'' unter dem Menüpunkt ''Entwickler'' in den Einstellungen des Geräts. Falls Sie den Eintrag ''Entwickler'' in den Einstellungen nicht finden, gehen Sie wie folgt vor: Schließen Sie das Gerät über USB an den Mac an. Dabei müssen Sie ggf. am Gerät noch der Verbindung zustimmen. Starten Sie Xcode und wählen Sie dann in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie dort Ihr Gerät aus. Danach sollte der Eintrag ''Entwickler'' in den Einstellungen auf dem Gerät auftauchen. Dazu müssen Sie möglicherweise die Einstellungen beenden und neu starten.

[[Datei:Alert.png | thumb | 270px | Beispiel für einen Alert unter iOS]]
Ein Verbindungsaufbau zu dem Gerät ist nicht möglich solange es bestimmte Alerts zeigt. Ein solcher Alert kann z. B. erscheinen wenn FaceTime aktiviert ist, indem ein Hinweis auf anfallende SMS-Gebühren angezeigt wird (siehe Screenshot). Achten Sie darauf, das Gerät so zu konfigurieren, dass es im Leerlauf keine solchen Alerts zeigt.

=== expecco 2.11 und später ===
Sie können beliebige Apps testen, die auf dem verwendeten Gerät lauffähig oder bereits installiert sind. Wenn die App als Development-Build vorliegt, muss die UDID des Geräts in der App hinterlegt sein. In jedem Fall muss der WebDriverAgent für das Gerät signiert werden. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]] unter Mac OS.

Falls Sie in einem Test den Home-Button verwenden wollen, müssen Sie auf dem Gerät AssistiveTouch aktivieren. Sie finden diese Option in den Einstellungen unter ''Allgemein'' > ''Bedienungshilfen'' > ''AssistiveTouch''. Platzieren Sie dann das Menü in der Mitte des oberen Bildschirmrands. Sie können das Drücken des Home-Buttons dann mit dem entsprechenden Menüeintrag im Recorder aufzeichnen oder direkt den Baustein ''Press Home Button'' benutzen.

=== expecco 2.10 ===
Die App, die Sie verwenden wollen, muss als Development-Build vorliegen. Außerdem muss die UDID des Geräts in der App hinterlegt sein.

=== Development-Build signieren ===
Ein Development-Build einer App ist nur für eine begrenzte Zahl von Geräten zugelassen und kann auf anderen Geräten nicht gestartet werden. Es ist aber möglich, das Zertifikat und die verwendbaren Geräte in einem Development-Build auszutauschen.

* Evaluierung mit Demo-App von eXept:
:Gerne stellen wir Ihnen eine Demo-App zur Verfügung, die als Development-Build vorliegt und die wir für Ihr Gerät signieren können. Senden Sie dazu bitte Ihrem eXept-Ansprechpartner die UDID Ihres Gerätes zu. Wie Sie die UDID Ihres Gerätes ermitteln können, ist im folgenden Abschnitt beschrieben.

* Eigene App für Ihr Testgerät verwenden:
:Wenn Sie von den App-Entwicklern einen Development-Build (IPA-Datei) erhalten, der für Ihr Testgerät zugelassen ist, können Sie diesen direkt verwenden. Dazu müssen Sie den Entwicklern die UDID Ihres Geräts mitteilen, damit sie diese eintragen können. '''Sie können die UDID eines Gerätes mithilfe von Xcode auslesen'''. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie Ihr Gerät aus und suchen Sie in Eigenschaften den Eintrag ''Identifier''. Die UDID ist eine 40-stellige Hexadezimalzahl.

* Extern entwickelte App für Ihr Testgerät umsignieren:
:Es können auch Apps umsigniert werden, damit Sie auf anderen Geräten lauffähig sind. Dieser Vorgang ist jedoch kompliziert und setzt insbesondere einen Zugang zu einem Apple-Developer-Account voraus. Eine Dokumentation zur Vorgehensweise ist derzeit in Vorbereitung.

:Für die Evaluierung unterstützen wir Sie gerne beim Umsignieren Ihrer App.


Weitere Informationen zur Verwendung von iOS-Geräten finden Sie auch in der [http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Dokumentation von Appium].

=== Native iOS-Apps ===
Sie können auch Apps verwenden, die bereits nativ auf dem Gerät vorhanden sind. Dazu müssen Sie deren Bundle-ID kennen und diese dann in die Verbindungseinstellungen eintragen. Hier eine kleine Auswahl gängiger Apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

Weitere Bundle-IDs finden Sie [https://github.com/joeblau/apple-bundle-identifiers hier].

= Beispiele =
Bei den Demo-Testsuiten für expecco finden Sie auch Beispiele für Tests mit dem Mobile Testing Plugin. Wählen Sie dazu auf dem Startbildschirm die Option "''Beispiel aus Datei''" und öffnen Sie den Ordner "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
Die Testsuite enthält zwei einfache Testpläne: "''Simple CalculatorTest''" und "''Complex Calculator and Messaging Test''". Beide Tests verwenden einen Android-Emulator, den Sie vor Beginn starten müssen. Die Apps, die im Test verwendet werden, gehören zur Grundausstattung des Emulators und müssen daher nicht mehr installiert werden. Da sich die Apps unter jeder Android-Version unterscheiden können, ist es wichtig, dass Ihr Emulator unter Android 6.0 läuft. Außerdem muss die Sprache auf Englisch gestellt sein.

; Simple CalculatorTest
: Dieser Test verbindet sich mit dem Taschenrechner und gibt die Formel ''2+3'' ein. Das Ergebnis des Rechners wird mit dem erwarteten Wert ''5'' verglichen.

; Complex Calculator and Messaging Test
: Dieser Test verbindet sich mit dem Taschenrechner und öffnet anschließend den Nachrichtendienst. Dort wartet er auf eine einkommende Nachricht von der Nummer ''15555215556'', in der eine zu berechnende Formel gesendet wird. Die Nachricht wird zuvor über einen Socket beim Emulator erzeugt. Nach dem Eintreffen der Nachricht wird diese vom Test geöffnet und deren Inhalt gelesen. Danach wird wieder der Taschenrechner geöffnet, die erhaltene Formel eingegeben und das Ergebnis gelesen. Anschließend wechselt der Test wieder zum Nachrichtendienst und sendet das Ergebnis als Antwort.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
Diese sind Bestandteil des Tutorials zum Mobile Testing Plugin. Der jeweils enthaltene Testfall ist unvollständig und wird im Zuge des Tutorials ergänzt. Lesen Sie dazu den Abschnitt [[#Tutorial|Tutorial]].

= Tutorial =
Es gibt ein Tutorial, das das grundsätzliche Vorgehen zur Erstellung von Tests mit dem Mobile Testing Plugin beschreibt. Grundlage dafür ist ein mitgeliefertes Beispiel, bestehend aus einer einfachen App und einer expecco-Testsuite.

Sie finden es auf der Seite [[Mobile_Testing_Tutorial|Mobile Testing Tutorial]] in zwei Versionen für Android und für iOS.
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_Android|Erste Schritte mit Android]]
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_iOS|Erste Schritte mit iOS]]

= Dialoge des Mobile Testing Plugins =
== Verbindungseditor ==
Mithilfe des Verbindungseditors können Sie schnell Verbindungen definieren, ändern oder aufbauen. Je nach Aufgabe weist der Dialog kleine Unterschiede auf und wird unterschiedlich geöffnet:
*Um eine Verbindung aufzubauen, klicken Sie im GUI-Browser auf "''Verbinden'"' klicken und wählen dann "''Mobile Testing''".
*Um eine bestehende Verbindung im GUI-Browser zu ändern oder zu kopieren, wählen Sie diese aus, machen einen Rechtsklick und wählen im Kontextmenü "''Verbindung bearbeiten''" oder "''Verbindung kopieren''" aus.
*Wollen Sie Verbindungseinstellungen nicht für den GUI-Browser sondern zur Verwendung in einem Test erstellen, wählen Sie im Menü des Mobile Testing Plugins den Punkt "''Verbindungseinstellungen erstellen...''". Darüber können nur die Einstellungen für eine Verbindung erstellt werden, ohne dass eine Verbindung tatsächlich angelegt wird.

Einige der Schaltflächen sind nur beim Erstellen von Verbindungseinstellungen sichtbar:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#"''Einstellungen löschen''": Setzt alle Einträge zurück. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Einstellungen aus Datei laden''": Erlaubt das Öffnen einer gespeicherten Einstellungsdatei (*.csf). Deren Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen aus Anhang laden''": Erlaubt das Öffnen eines Anhangs mit Verbindungseinstellungen aus einem geöffneten Projekt. Diese Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen in Datei speichern''" sowie
#"''Einstellungen in Anhang speichern''": Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern oder als Anhang in einem geöffneten Projekt anlegen. Beide Optionen besitzen ein verzögertes Menü, in dem Sie auswählen können, nur einen bestimmten Teil der Einstellungen zu speichern. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Erweiterte Ansicht''": Damit können Sie in die erweiterte Ansicht wechseln, um zusätzliche Einstellungen vorzunehmen. Lesen Sie dazu mehr am Ende des Kapitels. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Hilfe''": An der rechten Seite wird ein Hilfetext zum jeweiligen Schritt ein- oder ausgeblendet.

Der Dialog ist in drei Schritte unterteilt. Im ersten Schritt wählen Sie das Gerät, das Sie verwenden möchten, im zweiten Schritt wählen Sie aus, welche App verwendet werden soll und im letzten Schritt erfolgen die Einstellungen zum Appium-Server.

===Schritt 1: Gerät auswählen===
Im oberen Teil erhalten Sie eine Liste aller angeschlossenen Appium-Geräte, die erkannt werden. Mit der Checkbox darunter können Sie die Geräte ausblenden, die zwar erkannt werden, aber nicht bereit sind. Falls Sie ein Gerät eintragen wollen, das nicht angeschlossen ist, können Sie dies mit dem entsprechenden Knopf "''Android-Gerät eingeben''" bzw. "''iOS-Gerät eingeben''" anlegen. Dazu müssen Sie jedoch die benötigten Eigenschaften Ihres Geräts kennen. Das Gerät wird dann in einer zweiten Geräteliste angelegt und kann dort ausgewählt werden. Wenn keine Liste mit angeschlossenen Elementen angezeigt werden kann, werden stattdessen verschiedene Meldungen angezeigt:
*Keine Geräte gefunden
*:expecco konnte kein Android-Geräte finden.
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*Keine verfügbaren Geräte gefunden
*:expecco konnte keine verfügbaren Android-Geräte finden. Es wurden aber nicht verfügbare gefunden, z.B. mit dem Status "unauthorized".
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*:Um nicht verfügbare Geräte anzuzeigen, aktivieren Sie unten diese Option.
*Verbindung verloren
*:expecco hat die Verbindung zum adb-Server verloren. Versuchen Sie die Verbindung wieder herzustellen, indem Sie auf den Button klicken.
*Verbindung fehlgeschlagen
*:expecco konnte sich nicht mit dem adb-Server verbinden. Möglicherweise läuft er nicht oder der angegebene Pfad stimmt nicht.
*:Überprüfen Sie die adb-Konfiguration in den Einstellungen und versuchen Sie den adb-Server zu starten und eine Verbindung herzustellen indem Sie auf den Knopf klicken.
*Verbinden ...
*:expecco verbindet sich mit dem adb-Server. Dies kann einige Sekunden dauern.
*adb-Server starten ...
*:expecco startet den adb-Server. Dies kann einige Sekunden dauern.

Mit "''Weiter''" gelangen Sie zum nächsten Schritt. Wenn Sie Einstellungen für den GUI-Browser eingeben, ist das erst möglich, wenn ein Gerät ausgewählt wurde.

Anmerkung zum Freischalten: In jüngeren Android Versionen werden die Entwickleroptionen zunächst nicht mehr in den Einstellungen angeboten. Falls ihr Android Gerät in den Einstellungen keinen Eintrag zu "''Entwickleroptionen''" zeigt, wählen Sie zunächst den Eintrag "''Telefoninfo''", dann "''SoftwareVersionsInfo''" und klicken darin mehrfach auf den Eintrag "''BuildVersion''".

==== Chromedriver verwalten ====
Wenn die App, die Sie bedienen wollen, WebViews mit Chrome benutzt, benötigt Appium Zugriff auf einen passenden Chromedriver. Wenn Sie ein Gerät in der Liste auswählen, können Sie über "''Chromedriver verwalten''" sehen, welche Chrome-Versionen auf dem Gerät vorhanden sind und welche Chromedriver-Versionen durch expecco zur Verfügung stehen. Über diesen Dialog können Sie auch benötigte Chromedriver-Versionen herunterladen. Beachten Sie, dass auf dem Gerät verschiedene Chrome-Versionen vorhanden sein können, da die Apps in ihren WebViews nicht die gleiche Chrome-Version verwenden müssen, wie die als Browser installierte. Damit alles funktioniert, sollte der verwendete Chromedriver zur entsprechenden App passen. Sie können den Pfad zum Chromedriver auch am Ende des Verbindungsdialogs in den erstellten Capabilities ändern.

==== WLAN-Android-Geräte verbinden ====
Sie können sich auch über WLAN zu Android-Geräten verbinden. Dazu muss das Gerät zunächst mit adb verbunden werden, siehe [[Mobile_Testing_Plugin#Verbindung_.C3.BCber_WLAN|Verbindung über WLAN]]. Ab expecco 22.1 bietet der Verbindungseditor hierfür einen Dialog, der Ihnen dabei hilft und den Sie anstatt der Eingabeaufforderung verwenden können. Für Geräte mit Android 11 oder höher können Sie hier das Gerät mit dem Rechner zu koppeln, indem Sie die entsprechenden Parameter angeben und anschließend die Verbindung unter Angabe von IP-Adresse und Port aufbauen. Sie können damit auch für Geräte, die über USB verbunden sind, eine WLAN-Verbindung aufbauen. Wenn Sie das entsprechende Gerät in der Liste auswählen, werden die benötigten Angaben automatisch ausgelesen.

Beachten Sie, dass der Aufbau einer WLAN-Verbindung nicht Teil der Verbindungseinstellungen ist. Wenn Sie mit den erzeugten Einstellungen eine neue Verbindung aufbauen wollen, müssen Sie sicherstellen, dass das Gerät über mit der angegebenen IP-Adresse und dem Port mit adb verbunden ist, damit es gefunden wird. Die ADB-Verbindung geht verloren, wenn der ADB-Server oder das Gerät neu gestartet werden. Die Erlaubnis für das WLAN-Debugging wird beim Neustart des Geräts auch häufig zurückgesetzt und der Debug-Port kann dann wechseln. Daher muss eine WLAN-Verbindung immer manuell hergestellt werden.

===Schritt 2: App auswählen===
Hier können Sie Angaben zur App machen, die getestet werden soll. Dabei können Sie entscheiden, ob Sie eine App verwenden wollen, die bereits auf dem Gerät installiert ist, oder ob für den Test eine App installiert werden soll. Wählen Sie oben den entsprechenden Reiter aus. Je nachdem, ob Sie im vorigen Schritt ein Android- oder ein iOS-Gerät ausgewählt haben, ändert sich die erforderte Eingabe.

*'''Android'''
**''App auf dem Gerät''
**:Wenn Sie im ersten Schritt ein angeschlossenes Gerät ausgewählt haben, werden die Pakete aller installierten Apps automatisch abgerufen und Sie können die Auswahl aus den Drop-down-Listen treffen. Die installierten Apps sind in Fremdpakete und Systempakete unterteilt; wählen Sie die entsprechende Paketliste aus. Diese Auswahl gehört nicht zu den Einstellungen, sondern stellt nur die entsprechende Paketliste zur Verfügung. Sie können den Filter benutzen, um die Liste weiter einzuschränken und dann das gewünschte Paket auswählen. Die Activities des ausgwählten Pakets werden ebenfalls automatisch abgerufen und als Drop-down-Liste zur Verfügung gestellt. Wählen Sie die Activity aus, die gestartet werden soll. In der Regel wird automatisch eine Activity aus der Liste eingetragen. Falls Sie kein verbundenes Gerät verwenden, müssen Sie die Eingabe des Pakets und der Activity von Hand vornehmen.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Benutzen Sie einen lokalen Appium-Server, können Sie den rechten Butten benutzen, um zu der Installationsdatei der App zu navigieren und diesen Pfad einzutragen. Wenn möglich werden dabei auch das entsprechende Paket und die Activity in den Feldern darunter eingetragen. Diese Angabe ist aber nicht notwendig.

*'''iOS'''
**''App auf dem Gerät''
**:Geben Sie die Bundle-ID einer installierten App an. Sie können die IDs der installierten Apps bspw. mithilfe von Xcode erfahren. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü "''Window''" den Eintrag "''Devices''". Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wenn Sie Ihr Gerät auswählen, sehen Sie in der Übersicht eine Auflistung der von Ihnen installierten Apps.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Zu den Vorraussetzungen an Apps für reale Geräte lesen Sie bitte den Abschnitt [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Geräte und App vorbereiten]].

Im unteren Teil können Sie festlegen, ob die App beim Verbindungsabbau zurückgesetzt bzw. deinstalliert werden soll, und ob sie initial zurückgesetzt werden soll. Auch hier wird die entsprechende Capability gar nicht gesetzt, wenn Sie "''(Default)''" auswählen. Mit "''Weiter''" gelangen Sie zum nächsten Schritt.

===Schritt 3: Servereinstellungen===
Im letzten Schritt befindet sich zunächst im oberen Teil eine Liste aller Capabilities, die sich aus Ihren Angaben der vorigen Schritte ergeben. Wenn Sie sich mit Appium auskennen und noch zusätzliche Capabilities setzen möchten, die der Verbindungseditor nicht abdeckt, können Sie durch Klicken auf "''Bearbeiten''" in die erweiterte Ansicht gelangen. Lesen Sie dazu den Abschnitt weiter unten.

Wenn Sie Einstellungen für den GUI-Browser eingeben, können Sie den ''Verbindungsnamen'' eintragen, mit dem die Verbindung angezeigt wird. Dies ist auch der Name unter dem Bausteine diese Verbindung verwenden können, wenn sie aufgebaut ist. Wenn Sie das Feld frei lassen, wird ein Name generiert. Wenn der Haken für "''Von expecco gesteuert''" gesetzt ist, wird expecco einen lokalen Appium-Server an einem freien Port starten, oder einen bereits gestarteten freien Server verwenden. Um einen eigenen Server zu verwenden, schalten Sie diese Funktion ab und geben Sie die entsprechende Adresse ein. Sie erhalten die lokale Standard-Adresse und bereits verwendete Adressen zur Auswahl.

In älteren expecco-Versionen ist der Haken mit "''Bei Bedarf starten''" beschriftet. In diesem Fall müssen Sie auch eine Adresse angeben, wenn expecco den Server starten soll. expecco versucht dann beim Verbinden einen Appium-Server an der angegebenen Adresse zu starten, wenn dort noch keiner läuft. Dieser Server wird dann beim Beenden der Verbindung ebenfalls heruntergefahren. Dies funktioniert nur für lokale Adressen. Achten Sie darauf, nur Portnummern zu verwenden, die auch frei sind. Verwenden Sie am besten nur ungerade Portnummern ab dem Standardport 4723. Beim Verbindungsaufbau wird ebenfalls die folgende Portnummer verwendet, wodurch es sonst zu Konflikten kommen könnte.

Je nachdem, wie Sie den Dialog geöffnet haben, gibt es nun verschiedene Schaltflächen um ihn abzuschließen. In jedem Fall haben Sie die Option zu speichern. Dabei öffnet sich ein Dialog, indem Sie entweder ein geöffnet Projekt auswählen können, um die Einstellungen dort als Anhang zu speichern, oder auswählen es in einer Datei zu speichern, die Sie anschließend angeben können. Durch das Speichern wird der Dialog nicht beendet, wodurch Sie anschließend noch eine andere Option auswählen könnten.

Wenn Sie den Editor zum Verbindungsaufbau geöffnet haben, können Sie abschließend auf "''Verbinden''" oder "''Server starten und verbinden''" klicken, je nachdem, ob der Haken für den Serverstart gesetzt ist. Für das Ändern oder Kopieren einer Verbindung im GUI-Brower heißt diese Option "''Übernehmen''", da in diesem Fall nur der Verbindungseintrag geändert bzw. neu angelegt wird, der Verbindungsaufbau aber nicht gestartet wird. Das können Sie bei Bedarf anschließend über das Kontextmenü tun. Falls Sie Capabilities einer bestehenden Verbindung geändert haben, fordert Sie anschließend ein Dialog auf zu entscheiden, ob diese Änderungen direkt übernommen werden sollen, indem die Verbindung abgebaut und mit den neuen Verbindungen aufgebaut wird, oder nicht. In diesem Fall werden die Änderungen erst wirksam, nachdem Sie die Verbindung neu aufbauen.

Zur Verwendung des Verbindungseditors lesen Sie auch den entsprechenden Abschnitt im jeweiligen Tutorial in Schritt 1 (Android: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren|Demo ausführen]], iOS: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren_.28iOS.29|Demo ausführen (iOS)]]).

===Erweiterte Ansicht===
Die erweiterte Ansicht des Verbindungseditors erhalten Sie entweder durch Klicken auf "''Bearbeiten''" im dritten Schritt oder jederzeit über den entsprechenden Menüeintrag, wenn Sie den Editor über das Plugin-Menü gestartet haben. In dieser Ansicht erhalten Sie eine Liste aller eingestellten Appium-Capabilities. Zu dieser können Sie weitere hinzufügen, Einträge ändern oder entfernen. Um eine Capability hinzuzufügen, wählen Sie diese aus der Drop-down-Liste des Eingabefelds aus. In dieser befinden sich alle bekannten Capabilities sortiert in die Kategorien ''Common'', ''Android'' und ''iOS''. Haben Sie eine Capability ausgewählt, wird ein kurzer Informationstext dazu angezeigt. Sie können in das Feld auch von Hand eine Capability eingeben. Klicken Sie dann auf "''Hinzufügen''", um die Capabilitiy in die Liste einzutragen. Dort können Sie in der rechten Spalte den Wert setzen. Um einen Entrag zu löschen, wählen Sie diesen aus und klicken Sie auf "''Entfernen''". Mit "''Zurück''" verlassen Sie die erweiterte Ansicht.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Laufende Appium-Server ==
Im Menü des Mobile Testing Plugins finden Sie den Eintrag "''Appium-Server...''". Mit diesem öffnen Sie ein Fenster mit einer Übersicht aller Appium-Server, die von expecco gestartet wurden und auf welchem Port diese laufen. Durch Klicken auf das Icon in der Spalte "''Log anzeigen''" können Sie das Logfile des entsprechenden Servers anschauen. Dieses wird beim Beenden des Servers wieder gelöscht. Mit den Icons in der Spalte "''Beenden''" kann der entsprechenden Server beendet werden. Allerdings wird dies verhindert, wenn expecco über diesen Server noch eine offene Verbindung hat. Für welche Verbindung ein Server verwendet wird, sehen Sie in der rechten Spalte. Steht dort ''<idle>'' wird er zur Zeit nicht von expecco verwendet.

[[Datei:MobileTestingAppiumServer.png]]

Beim Öffnen des Editors um eine Appium-Verbindung aufzubauen, wird direkt ein Appium-Server gestartet, um den folgenden Verbindungsaufbau zu beschleunigen. Zu diesem Zweck hält sich expecco auch immer einen freien Appium-Server offen. Weitere laufende Server, die nicht mehr verwendet werden, werden jedoch nach einiger Zeit automatisch beendet.

Im Menü des Mobile Testing Plugins finden Sie auch den Eintrag "''Alle Verbindungen und Server beenden''". Dies ist für den Fall gedacht, dass Verbindungen oder Server auf andere Weise nicht beendet werden können. Beenden Sie Verbindungen wenn möglich immer im GUI-Browser oder durch Ausführen eines entsprechenden Bausteins. Server, die Sie in der Server-Übersicht gestartet haben, beenden Sie dort; Server, die mit einer Verbindung gestartet wurden, werden automatisch mit dieser beendet.

Beachten Sie, dass in der Übersicht nur Server aufgelistet sind, die von expecco gestartet und verwaltet werden. Mögliche andere Appium-Server, die auf andere Art gestartet wurden, werden nicht erkannt.

== Recorder ==
Besteht im GUI-Browser eine Verbindung zu einem Gerät, kann der integrierte Recorder verwendet werden, um mit diesem Gerät einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

[[Datei:MobileTestingRecorder.png|caption|]]

====Komponenten des Recorderfensters====
#'''Aufnahme fortsetzen/pausieren''': Über das rechte Symbol können Sie die Aufnahme pausieren. Sie sehen dann ein großes Pause-Symbol in der Anzeige. Alle Aktionen, die Sie währenddessen im Recorder machen werden zwar ausgeführt, es werden aber keine Bausteine aufgezeichnet. Über das linke Symbol können Sie dann wieder in den normalen Aufnahmemodus wechseln.
#'''Aufnahme stoppen''': Stoppt die Aufnahme und schließt das Recorderfenster.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Gerät. Dies wird nötig, wenn das Gerät zur Ausführung einer Aktion länger braucht oder sich etwas ohne das Anstoßen durch den Recorder ändert. Seit expecco 21.2 gibt es hier zusätzlich ein Untermenü, mit dem automatisches Aktualisieren angeschaltet werden kann, indem im Hintergrund auf Änderungen geprüft wird (siehe auch ''Automatisches Aktualisieren'' weiter unten).
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Elemente einzeichnen''': Die Rahmen aller Elemente der Ansicht werden angezeigt.
#'''Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst. Dabei stehen folgende Aktionen zur Verfügung:
#*Aktionen auf Elemente:
#**Klicken: Kurzer Klick auf das Element, über dem der Cursor steht. Zur genaueren Bestimmung, welches Element verwendet wird, benutzen Sie die Funktion Follow-Mouse oder Element-Highlighting.
#**Antippen mit Dauer (Element): Ähnlich zum Klicken, nur dass zusätzlich die Dauer des Klicks aufgezeichnet wird. Dadurch sind auch längere Klicks möglich.
#**Antippen mit Position (Element): Ähnlich zum Klicken, aber zusätzlich wird die Position innerhalb des Elements aufgenommen. Die Position kann relativ zur Größe des Elements aufgenommen werden oder, wenn Sie dabei Strg gedrückt halten, absolut zur linken oberen Ecke des Elements.
#**Text setzen: Ermöglicht das Setzen eines Textes in Eingabefelder.
#**Text löschen: Löscht den Text eines Eingabefelds.
#*Aktionen auf das Gerät:
#**Antippen (Bildschirm): Löst einen Klick auf die Bildschirmposition aus.
#**Antippen mit Dauer (Bildschirm): Löst einen Klick auf die Bildschirmposition aus, bei dem auch die Dauer berücksichtigt wird.
#**Wischen: Wischen in einer geraden Linie vom Punkt des Drückens des Mausknopfes bis zum Loslassen. Die Dauer wird ebenfalls aufgezeichnet.
#:Beachten Sie bei diesen Aktionen, dass das Ergebnis sich auf verschiedenen Geräten unterscheiden kann, bspw. bei verschiedenen Bildschirmauflösungen.
#*Erstellen von Testablauf-Bausteinen
#**Attribut prüfen: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Das Ergebnis triggert den entsprechenden Ausgang.
#**Attribut zusichern: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Bei Ungleichheit schlägt der Test fehl.
#**Attribut holen: Liest den aktuellen Wert eines Attributs aus.
#*Automatisch
#:Ist das Auto-Werkzeug ausgewählt, können alle Aktionen durch spezifische Eingabeweise benutzt werden: ''Klicken'', ''Element antippen'' und ''Wischen'' funktionieren weiterhin durch Klicken, wobei sie anhand der Dauer und der Bewegung des Cursors unterschieden werden. Um ein ''Antippen'' auszulösen, halten Sie beim Klicken Strg gedrückt. Die übrigen Aktionen erhalten Sie durch einen Rechtsklick auf das Element in einem Kontextmenü.
#'''Kontext-Aktionen''': Hier können Sie Aktionen aufzeichnen, die Kontexte betreffen:
#*Zu Kontext wechseln: Bietet eine Liste der aktuell verfügbaren Kontexte und Sie können auswählen, zu welchem gewechselt werden soll.
#*Aktuellen Kontext holen: Holt den Handle des aktuellen Kontexts.
#*Kontext-Handles holen: Holt eine Liste aller aktuell verfügbaren Kontext-Handles.
#'''Softkeys''': Nur unter Android. Simuliert das Drücken der Knöpfe Zurück, Home, Fensterliste und Power.
#'''Home-Button''': Nur unter iOS ab expecco 2.11. Ermöglicht das Drücken des Home-Buttons. Vor expecco 19.2 funktioniert es nur, wenn AssistiveTouch aktiviert ist und sich das Menü in der Mitte des oberen Bildschirmrands befindet. Ab expecco 19.2 verwendet die Funktion kein AssistiveTouch mehr.
#'''Hilfe''': Öffnet diese Online-Dokumentation auf der allgemeinen Seite zu [[GuiBrowser_Recorder|GUI-Browser Recordern]].
#'''Anzeige''': Zeigt einen Screenshot des Geräts. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Ansicht anpassen''': Öffnet einen Dialog um die Ansicht anzupassen, falls expecco das Bild nicht richtig darstellt. Sie können die Skalierung anpassen oder das Bild um 90° drehen.
#'''Ausrichtung anpassen''': Korrigiert das Bild, falls dieses auf dem Kopf stehen sollte. Über den Pfeil rechts daneben kann das Bild auch um 90° gedreht werden, falls dies einmal nötig sein sollte. Ab expecco 19.1 finden Sie diese Funktion in ''Ansicht anpassen''. Die Ausrichtung des Bildes ist für die Funktion des Recorders unerheblich, dieser arbeitet ausschließlich auf den erhaltenen Elementen.
#'''Skalierung''': Ändert die Skalierung des Screenshots.
#'''Meldungen''': Zeigt den Pfad des ausgewählten Elements oder andere Meldungen an. Es gibt ein Kontextmenü, um eine Liste der vorigen Meldungen zu sehen.

====Verwendung====
Mit jedem Klick im Fenster wird eine Aktion ausgelöst und im Arbeitsbereich des GUI-Browsers aufgezeichnet. Dort können Sie das Aufgenommene abspielen, editieren oder daraus einen neuen Baustein erstellen.
Aktionen zum Auslösen von Sofkeys finden Sie direkt in der Menüleiste (s.o.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Werkzeugs in der Menüleiste (s.o.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion.
Zur Verwendung des Recorders lesen Sie auch Schritt 2 im Tutorial ([[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen|Android]] bzw. [[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen_.28iOS.29|iOS]]).

====Elemente verbergen====
Ab expecco 21.2 gibt es im Kontextmenü außerdem die Möglichkeit, das ausgewählte Element im Recorder zu verbergen. Das bedeutet, dass dieses Element fortan nicht mehr ausgewählt werden kann. Diese Funktion eignet sich dazu, Elemente zu ignorieren, die im Vordergrund liegen, um auf Elemente darunter zugreifen zu können. Um diesen Zustand wieder rückgängig zu machen, müssen Sie das entsprechende Element im Baum des GUI-Browsers finden, dort gibt es im Kontextmenü ebenfalls einen solchen Eintrag.

====Automatisches Aktualisieren====
Der Recorder zeigt kein Livebild des Geräts sondern nur eine Momentaufnahme. Um mit der Anzeige auf dem Gerät übereinzustimmen muss daher nach Änderungen aktualisiert werden. Der Recorder aktualisiert sich automatisch, nachdem er eine Aktion ausgeführt hat. Ab expecco 20.2 sind zudem weitere automatische Updates möglich. Sie können Sie im Menü ''Fenster'' aktivieren.

Zum einen kann kurze Zeit nach dem Ausführen einer Aktion überprüft werden, ob es noch Änderungen nach der ersten Aktualisierung gegeben hat, damit in diesem Fall eine zweite Aktualisierung stattfinden kann. Dies soll das Problem beheben, dass der Recorder nach einer Aktion nicht aktuell ist, weil die Aktualisierung zu früh stattgefunden hat.

Zum anderen kann eine periodische Aktualisierung eingeschaltet werden. Nach einem einstellbaren Interval wird der Recorder automatisch aktualisiert, sollte es Änderungen geben. Dadurch ist die Anzeige im Recorder immer weitgehend aktuell, allerdings entsteht dadurch auch ein Mehraufwand was die Kommunikation mit dem Gerät betrifft.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid-Apps und WebViews =

'''!!! WICHTIGER HINWEIS - Wenn Sie Probleme haben, auf den Webview zu wechseln, geben Sie bitte unter den Android Einstellungen - Apps -Standard Apps "Chrome" als "Browser-App" an !!!
'''

Hybrid-Apps enthalten neben den Plattform-nativen Elementen weitere Elemente, die in einen WebView eingebunden sind. Diese Elemente können ebenfalls bedient werden, allerdings muss zuvor in den entsprechenden Kontext gewechselt werden. Mit dem Baustein "''Get Current Context''" erhalten Sie den aktuellen Kontext. Zu Beginn ist dies "''NATIVE_APP''", also der Kontext der nativen Elemente. Mit dem Baustein "''Get Context Handles''" bekommen Sie eine Collection aller vorhandenen Kontexte. Gibt es einen WebView-Kontext, so heißt dieser "''WEBVIEW_1''" oder "''WEBVIEW_<package>''" mit dem Paket des WebViews. Es kann auch mehrere WebView-Kontexte geben. Zu jedem WebView-Kontext gibt es im nativen Kontext ein entsprechendes WebView-Element. Mit dem Baustein "''Switch to Context''" können Sie in einen solchen Kontext wechseln und haben fortan nur Zugriff auf die Elemente in diesem Kontext.

Im GUI-Browser werden zum einen oben im Baum die vorhandenen Kontexte angezeigt, zum anderen wird der Baum eines Kontexts unterhalb des entsprechenden WebView-Elements eingefügt.

= XPath anpassen mithilfe des GUI-Browsers =
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen "''GTIN-13 (EAN-13)''" und "''Verify''", das Eingabefeld der Zahl "''4006381333986''" und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des "''GTIN-13''"-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch "''Pfad überprüfen''" (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit "''Verify Path: OK''" (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit "*" zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert "''GTIN-13 (EAN-13)''" besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer "''hierarchy''" (für iOS wäre es "''AppiumAUT''"), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix "''android.widget.''", das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend "''XCUIElementType''" am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. "''FrameLayout''" ist ein Kindelement von "''hierarchy''", "''LinearLayout''" ist ein Kind von "''FrameLayout''" usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element "''hierarchy''" beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben "''TextView''"-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ "''Button''" gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut "''resource-id''". Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut "''name''" verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem "@" eingeleitet und der Wert mit einem "=" in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter "''Test''" eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf "''Lauf''". Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu "''Eigenschaften''", wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

== Weitere Locator-Strategien ==
Appium bietet neben XPath noch weitere Strategien zur Adressierung von Elementen an. Einige davon stehen Ihnen '''ab Version 20.1''' ebenfalls mit expecco zur Verfügung. Diese sind nicht ganz so mächtig wie XPath, dafür aber häufig schneller bei der Auflösung auf dem Gerät. Insbesondere bei der Verwendung mit iPhones, wo die Hierarchie bei jeder XPath-Auflösung erst aufgebaut werden muss, bieten alternative Strategien einen Vorteil für die Laufzeit.

XPath ist weiterhin der Standard, das heißt alle Locator ohne besondere Angabe werden als XPath interpretiert. Um eine der anderen Strategien zu verwenden, schreiben Sie diese mit einem Gleichzeichen vor den gewünschten Locator. Diese Technik können Sie sowohl an den Blöcken verwenden, als auch im GUI-Browser testen.

{|
|-
| style="vertical-align:top" | AccessibilityId || style="padding-bottom:0.5em" | Verwendet den Wert des Elements, der dazu dient, die App barrierefrei zu machen. Für iOS ist das das Attribut '''Accessibility-id''', für Android das Attribut '''content-descr'''. ''Beispiel: accessibilityId=Löschen''
|-
| style="vertical-align:top" | className || style="padding-bottom:0.5em" | Verwendet den Namen der Klasse des Elements. ''Beispiel: className=android.widget.FrameLayout''
|-
| style="vertical-align:top" | id || style="padding-bottom:0.5em" | Verwendet die Kennung des Elements. Für iOS ist das das Attribut '''name''', für Android das Attribut '''resource-id'''. ''Beispiel: id=android:id/text1''
|-
| style="vertical-align:top" | iOSClassChain1 || style="padding-bottom:0.5em" | Verwendet die Hierarchie der Elemente ähnlich wie bei XPath. Eine Erklärung zum Aufbau finden Sie [https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules hier]. ''Beispiel: iOSClassChain=XCUIElementTypeWindow/XCUIElementTypeButton[`label == "Ok"`]''
|-
| style="vertical-align:top; padding-right:1em" | iOSNsPredicateString1 || style="padding-bottom:0.5em" | Verwendet einfache Kriterien, wie Attribute, die auch kombiniert werden können. ''Beispiel: iOSNsPredicateString=type == 'XCUIElementTypeButton' AND name == 'Weiter'''
|-
| style="vertical-align:top" | name1 || style="padding-bottom:0.5em" | Verwendet den Namen des Elements. ''Beispiel: name=Bestätigen''
|-
|}

:1 ''nur für iOS''

Um eine direkte Beschleunigung mit iOS zu erzielen, ohne dass Sie Ihre bisherigen Pfade anpassen müssen, wandelt expecco zudem Pfade, die nur aus einem Element mit Klasse und name-Attribut bestehen, zur Laufzeit automatisch in einen entsprechenden Locator der Strategie iOSNsPredicateString um. Wenn Sie einen Pfad explizit als XPath markieren, wird diese Anpassung nicht vorgenommen.

=Probleme und Lösungen=
== Locator sind versionsabhängig oder variabel ==
Dann sollten Sie die Locator (xPath) entweder in einer Variablen halten oder ein Locator-Mapping in einem Screenplay Anhang definieren. Es ist auch möglich, lediglich Teile des Locators (z.B. Locator-Pfad eines Elternelements oder Attributwert) in einer Variable zu halten und im Freezevalue des Locator-Pins mit "''$(varName)''" einzufügen.

==Unsichtbare UI-Elemente==
Beachten Sie, dass im [[#Recorder|Recorder]] auch Elemente berücksichtigt werden, die Sie auf dem Bildschirm nicht sehen. Schalten Sie daher das Element-Highlighting an oder nutzen Sie die Follow-Mouse-Funktion und den Elementbaum im GUI-Browser, um festzustellen, ob das richtige Element verwendet wird. Es kann vorkommen, dass unsichtbare Elemente vor anderen Elementen liegen und diese verdecken, so dass die gewünschten Elemente im Recorder nicht ausgewählt werden können. Lesen Sie dazu den Abschnitt [[#Elemente_verbergen|Elemente verbergen]].

==iOS: Kabel nicht zertifiziert==
In manchen Fällen erscheint beim Verbinden eines iOS-Geräts über USB der Hinweis, das verwendete Kabel sei nicht zertifiziert. In diesem Fall hilft es nur, das entsprechende Kabel auszutauschen.
==iOS: Alerts beim Verbindungsaufbau==
Stellen Sie sicher, dass beim Verbindungsaufbau mit einem iOS-Gerät keine Alerts geöffnet sind. Der Aufbau schlägt sonst fehl, da die App nicht in den Vordergrund kommen kann. Siehe auch [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Gerät und App vorbereiten]].

==iOS: .ipa installieren nicht möglich==
Beachten Sie, dass auf iOS-Simulatoren keine ''.ipa''-Dateien sondern nur ''.app''-Dateien installiert werden können.

==iOS: Erster Verbindungsaufbau funktioniert nicht==
Wenn auf Ihrem Mac noch kein signierter Build des WebDriverAgents liegt, muss dieser beim ersten Verbindungsaufbau erst erzeugt werden. Das kann in der Regel etwas länger als eine Minute dauern. Standardmäßig verwendet Appium aber einen Timeout von 60000 ms um zu warten bis der WebDriverAgent auf dem Gerät startet, so dass der Aufbau in diesen Fällen abgebrochen wird. Sie können den Timeout mit der Capability ''wdaLaunchTimeout'' setzen, z.B. auf ''120000''.

Außerdem müssen die Einstellungen für die Signierung passen. Am zuverlässigsten funktioniert das nach unserer Erfahrung, wenn man im Xcode-Projekt des WebDriverAgents auf automatische Signierung stellt und das Team setzt. Siehe dazu die Erklärung im Abschnitt [[#WebDriverAgent-Signierung|WebDriverAgent-Signierung]]. In diesem Fall sollten Sie die Capabilities ''xcodeConfigFile'' bzw. ''xcodeOrgId'' und ''xcodeSigningId'' '''nicht''' verwenden, da es sonst zu Konflikten kommen kann. Achtung: Wenn Sie eine Team-ID in den Mobile-Testing-Einstellungen gesetzt haben, setzt expecco diese automatisch als ''xcodeOrgId''!

Achten Sie beim ersten Verbindungsaufbau außerdem auf Ihr Gerät, da Sie dort möglicherweise der Installation per Passwort zustimmen müssen. Auf dem Mac kann die Eingabe des Passworts zur Freigabe des Schlüsselbunds für die Signierung nötig werden, häufig auch mehrmals.

==Android: Gerät nicht im Verbindungsdialog==
Wenn ein über USB angeschlossenes Android-Gerät nicht im Verbindungsdialog auftaucht, versuchen Sie, den USB-Verbindungstyp zu ändern. In der Regel sollten MTP oder PTP funktionieren. Prüfen Sie nochmal, ob "USB Debugging" in den Entwicklereinstellungen des Geräts aktiviert ist (diese Einstellungen sind bei manchen Geräten zunächst unsichtbar, und müssen durch einen Trick zugänglich gemacht werden). Siehe auch [[#Android-Ger.C3.A4t_vorbereiten|Android-Gerät vorbereiten]].

==Android: Abgeschnittene Elemente unten==
Bei Android-Geräten, die die Steuerungsleiste bzw. Softkeys automatisch ein- und ausblenden, kann es vorkommen, dass der Recorder im unteren Bereich Elemente abschneidet, die durch die Softkeys verdeckt würden, auch wenn sie zu diesem Zeitpunkt gar nicht angezeigt werden. In diesem Fall hift es, die Softkeys so einzustellen, dass sie in einer permanenten Leiste angezeigt werden.

Bei neueren Android-Versionen gibt es eine solche Einstellung in der Regel nicht. Auch wenn die Steuerelemente permanent eingeblendet sind, liegen sie auf keiner extra Leiste, sondern vor dem Inhalt der App. Es gibt dann im unteren Teil einen Bereich, der nicht bedient werden kann, weil er nicht zum aktiven Bereich der App gezählt wird, weshalb die Elemente von Appium abgeschnitten werden. Dieser Bereich kann auch größer sein als von den Steuerungselementen beansprucht. Bekannt ist dies für Samsung-Geräte mit Android 11. Da die Information über die Größe des App-Bereichs bereits auf Android-Ebene so geliefert wird, können wir hierfür keine Lösung anbieten, sondern können nur hoffen, dass das Problem vom Hersteller behoben wird. Sie können versuchen, ob Sie mit der Einstellung von Gestensteuerung bessere Ergebnisse bekommen, allerdings gibt es hier das gleiche Problem.

== Android: Test hängt beim Suchen eines Elements==
Der Baustein ''Find Element by XPath'' und alle Element-Bausteine warten bis ein Element zum angegebenen Pfad auftaucht. Den Timeout dafür kann man entweder am Baustein direkt oder in den Umgebungsvariablen ändern. Wenn das Element aber bereits da sein sollte und es dennoch sehr lange dauert, bis der Test weitergeht, kann das am UIAutomator/UIAutomator2 liegen. Dieser wartet, bis die App in den Idle-Zustand geht, bevor er überhaupt nach Elementen sucht. Dies kann länger dauern, wenn die App z.B. im Hintergrund noch Animationen abspielt oder andere Aktionen ausführt. Auch das Holen des Page-Sources z.B. beim Aktualisieren im GUI-Browser oder im Recorder kann dadurch länger dauern. Standardmäßig gibt es hierfür einen Timeout von 10 Sekunden, nach dem nicht weiter auf den Idle-Zustand gewartet wird. Dieser Timeout lässt sich durch eine Einstellung in Appium anpassen (waitForIdleTimeout). Falls Sie einen anderen Wert für diesen Timeout setzen möchten, ist dies ab expecco 21.2 möglich, indem Sie vor dem Test den Smalltalk-Code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> ausführen. Der Timeout wird in Millisekunden angegeben, das Beispiel setzt ihn also auf 2 Sekunden.

==Android: Aktualisieren des Trees oder Wechseln zum Webview-Kontext braucht zu lange==
Speziell mit älteren Geräten kann es vorkommen, dass neuere Chromedriver nicht initialisiert werden können. Das führt dann dazu, dass nicht in den Webview-Kontext gewechselt werden kann. Dies wird von Appium allerdings nur über einen Timeout festgestellt, der standardmäßig bei 4 Minuten liegt. Da expecco auch beim Aufbauen des Trees im GUI-Browser versucht in den Webview-Kontext zu wechseln, kann das zu sehr langen Ladezeiten führen. Da es in Appium keine Möglichkeit gibt, diesen Timeout herunter zu setzen, haben wir die Version, die wir im MobileTestingSupplement bereitstellen, um eine entsprechende Capability erweitert. Ab der Version 1.13.1.0 des [[#Windows|MobileTestingSupplements]] kann mit ''chromedriverStartTimeout'' der Timeout in Millisekunden gesetzt werden. Der Wechsel funktioniert dadurch zwar trotzdem nicht, aber expecco braucht dann nicht mehr so lange beim Aktualisieren des Trees und der Baustein zum Wechseln des Kontextes schlägt schneller fehl. Der Verbindungsdialog fügt diese Capability ab expecco 22.1 automatisch hinzu.

==Keine Aktion bei Klick==
Der Baustein zum Klicken auf ein Element ist erfolgreich, aber auf dem Gerät wurde keine Aktion ausgeführt.
:Dies kann vorkommen, wenn das Element von einem anderen Element verdeckt ist und ein Klick auf das Element deshalb nicht möglich ist. In diesem Fall wird von Appium kein Fehler geworfen, sondern es passiert einfach nichts. Wenn Sie dennoch einen Klick an der Position des Elements machen möchten, auch wenn es verdeckt ist, benutzen Sie stattdessen den Baustein ''Tap'' und übergeben Sie diesem die Position des Elements (''Get Location''). Wenn Sie stattdessen vor einem Klick prüfen möchten, ob das Element zu diesem Zeitpunkt verdeckt ist, versuchen Sie, ob Ihnen die Eigenschaften ''Is Displayed'' oder ''Is Enabled'' weiterhelfen.

==Kein Update nach Aktion==
Über den Recorder wurde eine Aktion ausgeführt, für die auch ein Baustein aufgezeichnet wurde, der Recorder zeigt aber immer noch das alte Bild.
:Der Recorder zeigt kein Livebild des Geräts, sondern immer nur eine Momentaufnahme. Nachdem eine Aktion ausgeführt wurde, aktualisiert sich der Recorder automatisch. Es kann aber vorkommen, dass das Bild schon aktualisiert wurde, bevor die Auswirkungen der Aktion auf dem Gerät vollständig abgeschlossen sind. In diesem Fall sollten Sie den Recorder von Hand aktualisieren über das Symbol mit den blauen Pfeilen. Ab expecco 20.2 können Sie für diesen Fall auch automatisches Aktualisieren einstellen. Siehe auch Beschreibung zum [[#Recorder|Recorder]].

=="clickable" Attribut falsch==
Ein Element hat im "''clickable''" Attribut/Property den Wert "''false''", ist aber dennoch anklickbar.
:Das "''clickable''" Attribute muss explizit vom App-Programmierer gesetzt werden, und hat tatsächlich keine Relevanz für das tatsächliche Verhalten der App. Sie sollten dieses Attribut i.A. in Ihren Tests nicht beachten. Leider existieren viele Apps, bei denen der Programmierer hier "lazy" war.

==Verbindungsaufbau schlägt fehl==
Schlägt der Verbindungsaufbau mit dem Appium-Server fehl, erhalten Sie in expecco eine Fehlermeldung ähnlicher der unten abgebildeten.

[[Datei:MobileTestingVerbindungsfehler.png]]

Hier sehen Sie die Art des aufgetretenen Fehlers. Klicken Sie auf "''Details''" um nähere Informationen zu erhalten. Mögliche Fehler sind:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:Der angegebene Server läuft nicht oder ist nicht erreichbar. Überprüfen Sie die Serveradresse.
*''org.openqa.selenium.WebDriverException''
:Lesen Sie in den Details in der ersten Zeile die Meldung hinter ''Original Error'':
:*''Unknown device or simulator UDID''
::Entweder ist das Gerät nicht richtig angeschlossen oder die udid stimmt nicht.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::Dieser Fehler kann verschiedene Ursachen haben. Entweder konnte tatsächlich der WebDriverAgent nicht gebaut werden, weil die Signierungseinstellungen falsch sind oder das passende Provisioning Profile fehlt. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]]. Es kann auch sein, dass der WebDriverAgent auf dem Gerät nicht gestartet werden kann, weil sich beispielsweise ein Alert im Vordergrund befindet oder Sie dem Entwickler nicht vertraut haben.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::Die angegebene App kann nicht auf dem iOS-Gerät installiert werden, weil es nicht im Provisioning Profile der App eingetragen ist.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.'''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die Datei unter dem angegebenen Pfad auf dem Mac befindet.
:*''packageAndLaunchActivityFromManifest failed.''
::Die angegebene ''apk''-Datei ist vermutlich kaputt.
:*''Could not find app apk at [...]''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die ''apk''-Datei am angegebenen Pfad befindet.

Falls der Fehler nicht durch eine der oben gelisteten Ursachen bedingt ist, kann es sein, dass die auf dem Gerät befindlichen Automation-Anwendungen nicht mehr richtig funktionieren. Hier hilft es, diese vom Mobilgerät zu deinstallieren. Beim nächsten Verbindungsaufbau werden sie dann automatisch neu installiert.

*Für iOS-Geräte ist das der WebDriverAgent, den Sie einfach vom Home-Screen deinstallieren können. Dies behebt in der Regel Probleme durch den Wechsel des verwendeten Macs oder der Xcode-Version.

*Für Android-Geräte ist es der UIAutomator2; hier tritt auf einigen Geräten sporadisch ein Problem auf, die Ursache dafür ist uns z.Z. noch nicht bekannt. Zur Deinstallation navigieren Sie auf dem Gerät zu "''Einstellungen''" > "''Anwendungen''"* und suchen in der Liste nach folgenden Einträgen:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Klicken Sie auf die jeweilige Anwendung und dann auf "''Deinstallieren''".
*''Der entsprechende Eintrag heißt auf manchen Geräten möglicherweise etwas anders.''

Falls dies nicht hilft, kann eventuell die Ausgabe des Appium-Servers weiterhelfen. Für einen von expecco gestarteten Server finden Sie das Log in der Liste der [[#Laufende_Appium-Server|laufenden Appium-Server]].

==Ich habe keinen Mac==
Vielleicht hilft Ihnen diese Webseite weiter: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]

Mobile Testing Plugin

2023-11-30T10:32:32Z

Matilk: /* WebDriverAgent-Signierung */ wdaLaunchTimeout

'''Deutsche Version''' | [[Mobile_Testing_Plugin/en|English Version]]

= Einleitung =
Mit dem ''Mobile Testing Plugin'' können Anwendungen auf Android- und iOS-Geräten getestet werden. Dabei ist es egal, ob reale mobile Endgeräte oder emulierte Geräte verwendet werden. Das Plugin kann (und wird üblicherweise) zusammen mit dem [[Expecco_GUI_Tests_Extension_Reference|GUI-Browser]] verwendet werden, der das Erstellen von Tests unterstützt. Zudem ist damit das Aufzeichnen von Testabläufen möglich.

Zur Verbindung mit den Geräten wird [http://appium.io/ Appium] verwendet. Appium ist ein freies Open-Source-Framework zum Testen und Automatisieren von mobilen Anwendungen.

Zur Einarbeitung in das Mobile Plugin empfehlen wir das [[Mobile_Testing_Tutorial|Tutorial]] zu bearbeiten. Dieses führt anhand eines Beispiels Schritt für Schritt durch die Erstellung eines Testfalls und erklärt die nötigen Grundlagen.

= Installation und Aufbau =
Zur Verwendung des Mobile Testing Plugins müssen Sie expecco inkl. des Plugins Mobile Testing installiert haben und Sie benötigen die entsprechenden Lizenzen. expecco kommuniziert mit den Mobilgeräten über einen Appium-Server, der entweder auf demselben Rechner wie expecco läuft, oder auf einem zweiten Rechner. Dieser muss für expecco erreichbar sein.

==Installationsübersicht==

'''Rechner, auf dem expecco läuft:'''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem Android-Geräte angeschlossen sind:'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Android SDK'', dieses erhalten Sie ebenfalls mit dem Mobile Testing Supplement''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
'''Rechner, an dem iOS-Geräte angeschlossen sind2):'''
* Appium-Server'', diesen können Sie über das Mobile Testing Supplement für Mac OS installieren (s.u.), von dem wir regelmäßig einen neue Version zur Verfügung stellen''
* Xcode ''in einer Version, die die verwendete iOS-Version unterstützt, erhältlich über den Apple App Store''
* Java JDK Version 8, 9, 10, 11 oder neuer 1)
* Apple-Entwickler-Zertifikat mit zugehörigem privaten Schlüssel ''(zum Signieren des WebDriverAgents)''
* Provisioning Profile mit den verwendeten Mobilgeräten

Je nach Aufbau können die oben genannten Rechner auch das selbe Gerät sein. expecco kann sich sowohl über das Netzwerk mit einem entfernten Appium-Server und dort angeschlossenen Mobilgeräten verbinden, als auch lokal selbst einen Appium-Server starten und diesen mit lokalen Mobilgeräten verwenden. Einige Funktionen von expecco, die die Erstellung von Testfällen erleichtern, sind jedoch nur verfügbar, wenn die Mobilgeräte am selben Rechner angeschlossen sind, auf dem auch expecco läuft. Ein möglicher Aufbau kann daher wie in folgender Abbildung aussehen:

[[Datei:MobileTestingAufbau.png | 400px]]

Im Folgenden wird die Installation von Appium und anderer nötiger Programme für Windows und Mac OS erklärt.

1): Zum Zeitpunkt der Erstellung dieses Dokuments wurden Versionen bis 11 auf Funktion verifiziert. Neuere Versionen sollten - sofern nicht grundlegende Änderungen von Oracle vorgenommen wurden, ebenfalls funktionieren.

2): Beachten Sie, dass aufgrund der Voraussetzungen (keine Anbindung an nicht-Apple Geräte verfügbar) iOS-Geräte nur von einem Mac aus angesteuert werden können. Sie benötigen also einen Mac als "Vermittler" (siehe auch unten: [[#Ich habe keinen Mac | "Ich habe keinen Mac"]])

== Windows ==
Am einfachsten installieren Sie alles mit unserem Mobile Testing Supplement1. In neueren Versionen ist allerdings aufgrund geänderter Lizenzbedingungen seitens Oracle kein JDK mehr enthalten, sodass sie dieses zusätzlich installieren müssen. Sie können natürlich Appium auch direkt installieren, um die Version zu verwenden, die Sie möchten. Um dann einen Appium-Server mit expecco starten zu können, muss allerdings eine entsprechende Batchdatei vorhanden sein und in den [[Mobile_Testing_Plugin#Konfiguration_des_Plugins|Einstellungen]] angegeben werden. Verbindungen können aber auch zu anderen laufenden Appium-Servern aufgebaut werden.
*'''expecco 23.1''': [https://download.exept.de/transfer/h-expecco-23.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.3.1]
:Gleiche Versionen wie der Vorgänger, aber der Installer erlaubt nun, Appium zum Autostart hinzuzufügen.
*expecco 22.2 und 22.1: [https://download.exept.de/transfer/h-expecco-22.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.13.2.0]
:Appium 1.22.3*
:Node 14.17.5
:adb 1.0.41 aus platform-tools 33.0.2
:''* Wir haben Appium um die Capability'' startChromedriverTimeout ''erweitert, um schneller einen Timeout zu bekommen, wenn der Chromedriver nicht gestartet werden kann. (siehe [[#startChromedriverTimeout|Probleme und Lösungen]])''
*expecco 21.2: [https://download.exept.de/transfer/h-expecco-21.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.12.0.0]
:Enthält die Appium-Version 1.22.0, Node ist weiterhin in der Version 12.13.1.
*expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.1.0]
:Nur kleine Änderungen im Vergleich zur vorigen Version.
*expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.10.0.0]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und node 12 verwendet.
*expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.8.1.0]
:Dieses installiert Appium in der Version 1.12.0 und enthält nun zusätzlich build-tools der Version 28.0.3 im android-sdk. Ansonsten ist es gleich wie die vorige Version.
*expecco 18.2: [http://download.exept.de/transfer/h-expecco-18.2.0/MobileTestingSupplement.exe Mobile Testing Supplement 1.7.3.0]
:Dieses installiert Appium in der Version 1.8.1. Außerdem bietet das Supplement auch an, ''Android Debug Bridge'' und ''Google USB Driver'' ([https://gsmusbdrivers.com/download/adb-fastboot-drivers/ adb-setup-1.4.3]) zu installieren. Damit sind Treiber für ein breites Spektrum an Android-Geräten abgedeckt, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen. Ein '''JDK ist (aufgrund geänderter Lizenzbedingungen seitens Oracle) nicht mehr enthalten''', dieses müssen Sie selbst herunterladen, z.B. von [https://www.oracle.com/technetwork/java/javase/downloads/index.html Oracle].
*expecco 18.1: wie expecco 2.11
*expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/MobileTestingSupplement_1.6.0.2_Setup.exe Mobile Testing Supplement 1.6.0.2]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.6.4. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.
*expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_1.5.0.0_Setup.exe Mobile Testing Supplement 1.5.0.0]
:Dieses installiert ein Java JDK der Version 8, android-sdk und Appium in der Version 1.4.16. Während der Installation wird die grafische Oberfläche von Appium gestartet, dieses Fenster können Sie sofort wieder schließen. Außerdem bietet das Supplement auch einen universellen adb-Treiber ([http://download.clockworkmod.com/test/UniversalAdbDriverSetup.msi ClockworkMod]) an. Dieser vereint Treiber für ein breites Spektrum an Android-Geräten, sodass Sie nicht für jedes Gerät einen eigenen Treiber suchen und installieren müssen.

Wenn expecco Mobilgeräte verwenden soll, die an einem anderen Rechner angeschlossen sind, müssen Sie dort einen Appium-Server starten. Dies können Sie mit der Datei <code>appium_standalone.cmd</code> tun. Der Server wird dann mit dem Standard-Port 4723 gestartet. Falls Sie eine andere Portnummer verwenden wollen, starten Sie den Server mit

appium_standalone.cmd -p <portnummer>

Der Server ist bereit, sobald die Zeile
<blockquote>Appium REST http interface listener started on 0.0.0.0:4723</blockquote>
angezeigt wird, wobei Sie am Ende die verwendete Portnummer ablesen können.

Beim ersten Starten von Appium – sowohl im Standalone als auch gestartet von expecco – kann es vorkommen, dass die Windows-Firewall den Node-Server blockiert. Lassen Sie den Zugriff zu, sonst kann Appium nicht gestartet werden.

1) Sie können natürlich auch die Command Line Tools (adb, sdkmanager, avdmanager etc.) einer vorhandenen Android Studio Version verwenden, sowie Appium separat installieren.
Da sich diese Tools regelmäßig ändern, und es in der Vergangenheit zu Inkompatibilitäten und Fehlern nach Releasewechseln kam, empfehlen wir zu Beginn, das mitgelieferte Paket zu verwenden. Dies ist möglicherweise nicht das aktuellste, wurde aber auf Lauffähigkeit getestet.

Falls das Android Mobilgerät an einem entfernen Rechner angeschlossen ist,
können Sie den aktuellen Bildschirminhalt z.B. mit dem [https://github.com/Genymobile/scrcpy scrcpy] tool live mitverfolgen.

== Mac OS (nicht erforderlich für Android-Tests)==
Hinweis: Wenn Sie nicht vorhaben, iOS-Geräte (iPhone, iPad, etc.) zu testen, können Sie das Folgende ignorieren. '''Der Apple-Rechner sowie das Mac-Setup werden für Android-Geräte nicht benötigt'''.

=== Xcode ===
Zur Automatisierung mit iOS-Geräten wird [https://developer.apple.com/xcode/ Xcode] benötigt. Sie erhalten dieses über den App Store. Dabei ist darauf zu achten, dass die Version zu den getesteten iOS-Versionen passt.
{| class="wikitable"
|-
|'''iOS'''  
|'''Xcode'''
|'''macOS'''
|-
|10.x
|8.x
|10.12 (Sierra)
|-
|11.x
|9.x
|10.13 (High Sierra)
|-
|12.x
|10.x
|10.14 (Mojave)
|-
|13.x
|11.x
|10.15 (Catalina)
|-
|14.x
|12.x
|11.0 (Big Sur)
|-
|15.x
|13.x
|12.0 (Monterey)
|-
|16.x
|14.x
|12.5 (Monterey)
|}
Diese Tabelle gibt nur eine vereinfachte Übersicht, lesen Sie besser unter [https://xcodereleases.com/ Xcode Releases] oder [https://en.wikipedia.org/wiki/Xcode#Version_comparison_table Xcode-Versionen] welche Version Sie brauchen. Für neue iOS Minor-Versionen gibt es in der Regel auch ein Update für Xcode, z.B. brauchen Sie für iOS 10.2 mindestens Xcode 8.2, für iOS 10.3 mindestens Xcode 8.3 usw.
Wenn Sie also auf eine neuere iOS-Version wechseln, benötigen Sie in der Regel auch eine neuere Xcode-Version. Neuere Versionen von Xcode laufen möglicherweise nicht auf älteren Betriebssystemen, was wiederum eine Aktualisierung des Betriebssystems erforderlich machen kann. Falls Sie auch ältere iOS-Versionen testen wollen kann es sinnvoll sein, die entsprechenden Xcode-Versionen parallel zu installieren.

=== Appium ===
Der Appium-Server kann entweder als Kommandozeilen-Anwendung installiert werden oder über [https://github.com/appium/appium-desktop Appium Desktop] verwendet werden, welcher den Server über ein GUI zur Verfügung stellt. Mittlerweile gibt es auch Appium 2.0, was wir aber bisher noch nicht mit expecco getestet haben und daher nicht empfehlen.

==== Appium Desktop ====
Laden Sie die neueste Version von [https://github.com/appium/appium-desktop/releases/ Appium Desktop] herunter. Für den Mac nehmen Sie am besten die dmg-Datei und installieren sie in den Anwendungen. Beim Starten der Anwendung ''Appium Server GUI'' erhalten Sie wahrscheinlich eine Fehlermeldung, dass es aus Sicherheitsgründen nicht möglich ist. Öffnen Sie dann das Kontextmenü auf der Anwendungsdatei (Rechtsklick bzw. Strg + Klick) und wählen Sie dort ''Öffnen'' aus. Bestätigen Sie dann, dass Sie die Anwendung wirklich öffnen wollen. Fortan können Sie die Anwendung normal öffnen.

[[Datei:OpenAppiumServerGUI1.png|text-top]] [[Datei:OpenAppiumServerGUI2.png|text-top]]

Ab Xcode 14 gibt es Probleme beim Signieren des WebDriverAgents, den Appium zur Automatisierung auf das Gerät spielt. Dadurch ist mit der Version 1.22.3-4 von Appium Desktop kein Verbindungsaufbau möglich. Das Problem ist in neueren Versionen des WebDriverAgents behoben, es gibt aber aktuell noch keine Version von Appium Desktop, die eine solche Version enthält (Stand November 2022). Sie können aber manuell eine neue Version herunterladen (z.B. 4.10.2) und die Dateien in Appium ersetzen. Laden Sie dazu von der [https://github.com/appium/WebDriverAgent/releases/ WebDriverAgent Download-Seite] eine der beiden Archivdateien (zip oder tar.gz) mit dem Source Code herunter. Öffnen und entpacken Sie dann diese Datei. Den Inhalt des Ordners WebDriverAgent-4.10.2 müssen Sie nun nach

/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/

kopieren. Wenn Sie über den Finder dorthin navigieren, machen Sie auf die Anwendung ''Appium Server GUI'' einen Kontextklick (Rechtsklick bzw. Strg + Klick) und wählen Sie im Menü ''Paketinhalt anzeigen''. Ersetzen Sie alle Dateien, die bereits mit gleichem Namen enthalten sind.

==== Appium über npm installieren ====
Sie können Appium auch über npm (Node Package Manager) installieren. Dazu müsen Sie erst node/npm installieren. Das geht mit [https://github.com/nvm-sh/nvm nvm] (Node Version Manager) was Sie von Github bekommen. Falls die folgende Installationsanleitung bei Ihnen nicht funktionieren sollte, finden Sie dort ausführlichere Informationen im [https://github.com/nvm-sh/nvm#readme Readme].

Öffnen Sie ein Terminal-Fenster. Klonen Sie dann das Github-Repository von nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
und laden Sie es
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Führen Sie danach
command -v nvm
aus, um zu testen, ob es funktioniert hat. Es sollte ''nvm'' ausgegeben werden. Kommt keine Antwort, führen Sie
touch ~/.zshrc
aus, und versuchen Sie es erneut.

Nun können Sie node mit dem folgenden Befehl installieren.
nvm install 16.15.1
Da es mit der aktuellen Version von node Probleme beim Installieren von Appium gibt, empfehlen wir diese Version.

Nachdem node installiert ist, können Sie Appium darüber installieren:
npm install -g appium

Den Appium-Server können Sie nun einfach über den Befehl
appium
starten. Die Ausgabe erfolgt dann direkt im Terminal.

Auch bei dieser Version gibt es das Problem bei der Signierung des WebDriverAgents, wie bei [[#Appium_Desktop | Appium Desktop]] beschrieben. Laden Sie also auch in diesem Fall eine neuere Version des WebDriverAgents herunter und ersetzen Sie die alten Dateien. Diese finden Sie unter
/Users/<user>/.nvm/versions/16.15.1/lib/appium/node_modules/appium-webdriveragent/

==== Mobile Testing Supplement ====
Ältere Appium-Versionen stellen wir Ihnen über das Mobile Testing Supplement für Mac OS zur Verfügung, mit dem Sie es einfach installieren können:
* '''expecco 20.2''': [https://download.exept.de/transfer/h-expecco-20.2.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.2)]
:Enthält Appium Version 1.18.3 und verwendet node 14.

* expecco 20.1: [https://download.exept.de/transfer/h-expecco-20.1.0/Mobile_Testing_Supplement_for_Mac_OS.tar.bz2 Mobile Testing Supplement für Mac OS (1.2.0)]
:Nur wenige Änderungen im Vergleich zur vorigen Version.

* expecco 19.2: [http://download.exept.de/transfer/h-expecco-19.2.0/MobileTestingSupplement_for_MacOS.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.98)]
:Im Vergleich zur vorigen Version wurde Appium auf die Version 1.16.0-rc.1 aktualisiert und es wird node 12 verwendet.

* expecco 19.1: [http://download.exept.de/transfer/h-expecco-19.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.96.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.96)]
:Diese Version enthält Appium 1.12.0.

* expecco 18.1: [http://download.exept.de/transfer/h-expecco-18.1.0/Mobile_Testing_Supplement_for_Mac_OS_1.1.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.1.94)]
:Diese Version enthält Appium 1.8.0.

* expecco 2.11: [http://download.exept.de/transfer/h-expecco-2.11.1/Mobile_Testing_Supplement_for_Mac_OS_1.0.94.tar.bz2 Mobile Testing Supplement für Mac OS (1.0.94)]
:Diese Version enthält Appium 1.6.4.

* expecco 2.10: [http://download.exept.de/transfer/h-expecco-2.10.0/Mobile_Testing_Supplement_for_Mac_OS_1.0.tar.bz2 Mobile Testing Supplement für Mac OS]
:Diese Version entält Appium 1.4.16.

Nachdem Herunterladen des Supplements, können Sie es in ein Verzeichnis Ihrer Wahl (z. B. Ihr Home-Verzeichnis) verschieben und dort entpacken. Ein geeigneter Befehl in einer Shell könnte wie folgt aussehen, passen Sie dabei die Versionsnummer entsprechend an:

tar -xvpf Mobile_Testing_Supplement_for_Mac_OS_1.1.98.tar.bz2

Wenn Sie Ihre Standard-Xcode-Installation verwenden wollen, können Sie Appium direkt über die Datei im ''bin''-Verzeichnis mit der entsprechenden Versionsnummer starten:

Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Falls Sie ein anderes Xcode als das als Standard konfigurierte verwenden wollen, müssen Sie Appium den entsprechenden Pfad über die Umgebungsvariable ''DEVELOPER_DIR'' angeben.
Wenn Sie Xcode z. B. in ''/Applications/Xcode-11.3.app'' installiert haben, müssten Sie Appium so starten:

DEVELOPER_DIR="/Applications/Xcode-11.3.app/Contents/Developer" Mobile_Testing_Supplement/bin/start-appium-1.16.0-rc.1

Was als Standard-Xcode-Installation gesetzt ist, zeigt der Befehl:

xcode-select -p

Wenn Appium Ihre Xcode-Installation nicht findet, erscheint beim Verbinden eine Fehlermeldung in der Art:
''<blockquote>org.openqa.selenium.SessionNotCreatedException - A new session could not be created. (Original error: Could not find path to Xcode, environment variable DEVELOPER_DIR set to: /Applications/Xcode.app but no Xcode found)</blockquote>''
Starten Sie in diesem Fall Appium erneut, unter Angabe eines gültigen ''DEVELOPER_DIR''.

==== WebDriverAgent-Signierung ====
Zur Automatisierung lädt Appium eine App namens WebDriverAgent auf das Gerät und muss sie dafür signieren können. Dazu brauchen Sie einen Apple-Account und ein entsprechendes Zertifikat. Zur Evaluierung können Sie einen kostenlosen Account verwenden. Dieser hat den Nachteil, dass erstellte Profile nur eine Woche gültig sind und danach neu erstellt werden müssen. Seien Sie auch vorsichtig, wenn Sie sich den Account teilen, da es vorkommen kann, dass Zertifikate widerrufen werden oder durch automatische Generierung ungültig werden. Als Folge können bereits signierte Apps nicht mehr verwendet werden.

Wenn Sie bereits ein entsprechendes Zertifikat mit dem zugehörigen privaten Schlüssel in Ihrer [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac haben, können Sie den WebDriverAgent automatisch signieren lassen. Ansonsten empfiehlt es sich, die Signierung über Xcode einzustellen und zu verwalten.

Schließen Sie zuerst das Gerät, das Sie verwenden möchten, über USB an den Mac an. Stellen Sie sicher, dass sich der Mac und das Gerät im selben Netzwerk befinden, ansonsten kann es beim Verbindungsaufbau mit Appium zu Problemen kommen. Starten Sie Xcode und öffnen Sie ''Preferences''. Wechseln Sie zur Seite der Accounts und legen Sie einen Eintrag mit Ihrem Account an. Anschließend können Sie auf ''Manage Certificates...'' klicken, um die Zertifikate zu sehen, die zu diesem Account gehören. Zum Ausführen von Tests benötigen Sie ein iOS-Development-Zertifikat und den dazugehörigen privaten Schlüssel. Wenn Sie noch keines besitzen, erstellen Sie eines. Wenn Sie bereits eines haben, aber es nicht in Ihrem Schlüsselbund vorhanden ist (erkennbar an dem Hinweis "Not in Keychain"), können Sie es importieren. Das können Sie über die [https://support.apple.com/de-de/guide/keychain-access/welcome/mac Schlüsselbundverwaltung] auf dem Mac machen, wenn Sie es zuvor aus dem Schlüsselbund exportiert haben, in dem es sich befindet. Das Zertifikat mit dem zugehörigen Schlüssel sollte sich im Schlüsselbund ''Anmeldung'' befinden. Dort kann es als PKCS#12-Datei (Endung typischerweise .p12) exportiert werden. Um ein Zertifikat in Ihren Schlüsselbund zu importieren, wählen Sie im Menü ''Ablage'' die Option ''Objekte importieren''. Falls Sie nicht wissen, wo das Zertifikat gespeichert ist, können Sie es in Xcode auch widerrufen und in Ihrem Schlüsselbund neu anlegen. Machen Sie das jedoch nur, wenn Sie wissen, dass das alte Zertifikat nicht mehr in Verwendung ist, da es danach nicht mehr benutzt werden kann. Nun sollte Ihr Schlüsselbund ein iOS-Development-Zertifikat enthalten.


Öffnen Sie nun das WebDriverAgent-Projekt in Xcode. Wenn Sie das Mobile Testing Supplement installiert haben, finden Sie es in dessen Verzeichnis unter
''<nowiki>Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj</nowiki>''
Wenn Sie Appium Desktop installier haben, finden Sie es unter
''<nowiki>/Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj</nowiki>''
Sie können einfach im Finder zu der Xcode-Project-Datei navigieren und Sie über einen Doppelklick öffnen. Beachten Sie dabei, dass Sie dabei auf die Anwendung Appium Server GUI einen Kontextklick (Rechtsklick bzw. Strg + Klick) machen und im Menü ''Paketinhalt anzeigen'' auswählen müssen, um in deren Unterverzeichnis zu gelangen.

[[Datei:MobileTestingWebDriverAgentXcode.png]]

Wählen Sie ''WebDriverAgentLib'' und die Seite ''Signing & Capabilities'' aus. Setzen Sie dort im Abschnitt ''Signing'' die Option ''Automatically manage signing'' und wählen Sie dann ein Team aus. Wechseln Sie nun zu ''WebDriverAgentRunner'' und tun Sie dort dasselbe.

Durch das Setzen des Teams sollten die Fehler für den WebDriverAgentRunner verschwinden. Sollte Xcode kein passendes Provisioning Profile für die Bundle ID ''com.facebook.WebDriverAgentRunner'' erstellen können, können Sie diese anpassen, dass sie zu Ihrem Zertifikat passt. Danach können Sie Xcode beenden oder auch, wie weiter unten beschrieben, direkt den Build über Xcode starten, damit das Projekt bereits gebaut ist, wenn Appium es verwenden möchte.

Wenn Sie sich nun von expecco eine Verbindung zu Ihrem Gerät aufbauen, wird der WebDriverAgent darauf installiert und gestartet, um anschließend zur zu testenden App zu wechseln. Eventuell muss auf dem Gerät muss der Ausführung des WebDriverAgents vertraut noch werden. Ein Anzeichnen dafür kann sein, dass die App WebDriverAgent zwar auf dem Gerät erscheint und zu starten versucht, danach aber wieder deinstalliert wird. Öffnen Sie dazu während des Verbindungsaufbaus auf dem Gerät in die Einstellungen und dort unter ''Allgemein'' den Eintrag ''Geräteverwaltung''. Dieser Eintrag ist nur sichtbar, wenn eine Entwickler-App auf dem Gerät installiert ist. Sie müssen daher möglicherweise warten, bis der WebDriverAgent installiert ist, bevor der Eintrag erscheint. Wählen Sie dort den Eintrag Ihres Apple-Accounts und vertrauen Sie ihm. Da der WebDriverAgent wieder deinstalliert wird, wenn der Start nicht funktioniert hat, müssen Sie dies während des Verbindungsaufbaus tun. Falls Ihnen das zu hektisch ist, können Sie auch folgenden Code ausführen:

<nowiki>xcodebuild -project Mobile_Testing_Supplement/lib/node_modules/appium-1.16.0-rc.1/node_modules/appium-xcuitest-driver/WebDriverAgent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test</nowiki>
bzw.
xcodebuild -project /Applications/Appium\ Server\ GUI.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test

Damit wird der WebDriverAgent auf dem Gerät installiert ohne dass er wieder gelöscht wird.

Wenn es Probleme beim Installieren des WebDriverAgents gibt, können Sie auch versuchen, den Build über Xcode zu starten. Stellen Sie sicher, dass das richtige Target ''WebDriverAgent'' ausgewählt ist. Fehlermeldungen in Xcode zeigen vielleicht einfacher, wo das Problem liegt. Manchmal hilft es auch, es ein zweites Mal zu versuchen, weil es möglicherweise beim ersten Mal zu lange gedauert hat und abgebrochen wurde. Es kann sein, dass Sie während des Builds mehrmals aufgefordert werden, das Passwort für Ihren Schlüsselbund anzugeben.

[[Datei:WebDriverAgentCodesign.png]]

Lesen Sie auch die Dokumentation von Appium zum [https://github.com/appium/appium-xcuitest-driver/blob/master/docs/real-device-config.md Aufsetzen von Tests mit iOS-Geräten]. In der [https://support.apple.com/en-us/HT204460 Dokumentation von Apple] finden Sie nähere Informationen zum Installieren und Vertrauen von Apps.

Ist der WebDriverAgent einmal auf dem Gerät installiert, wird er für spätere Verbindungen wieder verwendet und der Verbindungsaufbau sollte schneller funktionieren. Ebenso liegt dann die signierte Version bereits auf Ihrem Mac und muss nicht erneut gebaut werden, was die Verbindung zu weiteren Geräten ebenfalls beschleunigt. Wenn Sie wissen, dass bei Ihrem Verbindungsaufbau der WebDriverAgent erst noch signiert und gebaut werden muss, ist es ratsam, die Capability ''wdaLaunchTimeout'' zu setzen. Dieser Timeout, wie lange auf den Start der WebDriverAgents auf dem Gerät gewartet werden soll, liegt standardmäßig bei 60000 ms. Der Build dauert aber häufig über eine Minute, sodass der Versuch zum Verbindungsaufbau dann abgebrochen wird. Ein Wert von 120000 hat sich hier als besser erwiesen.

== Konfiguration des Plugins ==
Bevor Sie loslegen, sollten Sie die Einstellungen des Mobile Testing Plugins überprüfen und ggf. anpassen.

Öffnen Sie im Menü den Punkt "''Extras''" → "''Einstellungen''" und dort unter "''Erweiterungen''" den Eintrag "''Mobile Testing''" (s. Abb.). Standardmäßig werden diese Pfade automatisch gefunden (1). Um einen Pfad manuell anzupassen, deaktivieren Sie den entsprechenden Haken rechts davon. Sie erhalten in einer Drop-down-Liste einige Pfade zur Auswahl. Ist ein eingetragener Pfad falsch oder kann er nicht gefunden werden, wird das Feld rot markiert und es erscheint ein diesbezüglicher Hinweis. Stellen Sie sicher, dass alle Pfade richtig angegeben sind.

[[Datei:MobileTestingEinstellungen.png | thumb | 400px | Konfiguration des Plugins]]

*'''appium''': Geben Sie hier den Pfad zur ausführbaren Datei an mit der Appium in der Kommandozeile gestartet werden kann. Unter Windows wird diese Datei in der Regel "<code>appium.cmd</code>" heißen. Dieser Pfad wird benutzt, wenn expecco einen Appium-Server startet.
*'''node''': Geben Sie hier den Pfad zur ausführbaren Datei an, die Node (auch "Node.js") startet. Dieser Pfad wird beim Starten eines Servers an Appium weitergegeben, damit Appium ihn unabhängig von der PATH-Variablen findet. Unter Windows heißt diese Datei in der Regel "<code>node.exe</code>".
*'''JAVA_HOME''': Geben Sie hier den Pfad zu einem JDK an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden. Um einzustellen, welches Java von expecco verwendet werden soll, setzen Sie diesen Pfad in den Einstellungen für die Java Bridge.
*'''ANDROID_HOME''': Geben Sie hier den Pfad zu einem SDK von Android an. Dieser Pfad wird an jeden Appium-Server weitergegeben. Lassen Sie das Feld frei, um den Wert aus der Umgebungsvariablen zu verwenden.
*'''adb''': Hier steht der Pfad zum adb-Befehl. Unter Windows heißt die Datei adb.exe. Diese wird von expecco beispielsweise verwendet, um die Liste der angeschlossenen Geräte zu erhalten. Diesen Pfad sollten Sie automatisch wählen lassen, da dann der Befehl im ANDROID_HOME-Verzeichnis verwendet wird. Dieser wird auch von Appium verwendet. Falls expecco und Appium jedoch verschiedene Versionen von adb verwenden kann es zu Konflikten kommen.
*'''android.bat''': Diese Datei wird nur benötigt, um damit den AVD und den SDK Manager zu starten. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.
*'''aapt''': Geben Sie hier den Pfad zum aapt-Befehl an. Unter Windows heißt diese Datei ''aapt.exe''. expecco verwendet aapt nur im Verbindungseditor, um das Paket und die Activities einer apk-Datei zu lesen. Automatisch wird hier die Datei im ANDROID_HOME-Verzeichnis gesucht.

[[Datei:MobileTestingJavaBridgeEinstellungen.png | thumb | 400px | Konfiguration des JDKs]]

Ab expecco 2.11 gibt es das Feld ''Team-ID''. Wenn Sie iOS-Tests ausführen, tragen Sie hier die Team-ID Ihres Zertifikats ein. Diese wird für jede iOS-Verbindung verwendet, außer Sie setzen den Wert im Einzelfall in den Verbindungseinstellungen um. Wie Sie die Team-ID erhalten, lesen Sie im Abschnitt zur [[#Signierung|Signierung]] ber der Installation auf Mac OS. Mit expecco 2.10 können Sie die Team-ID nur für jede Verbindungseinstellung extra als Capability eintragen. Dazu müssen Sie jedoch die [[#Erweiterte_Ansicht|erweiterte Ansicht]] verwenden. Geben Sie hier die Capability ''xcodeOrgId'' an und setzen Sie als Wert die Team-ID des Zertifikats.

Die Einstellung zur Serveradresse unten auf der Seite bezieht sich auf das Verhalten des Verbindungseditors. Dieser prüft am Ende, ob die Serveradresse auf ''/wd/hub'' endet, da dies die übliche Form ist. Falls nicht, wird in einem Dialog gefragt, wie darauf reagiert werden soll. Das festgelegte Verhalten kann hier eingesehen und verändert werden.

Wechseln Sie ebenfalls zum Eintrag ''Java Bridge'' (s. Abb.). Hier muss der Pfad zu Ihrer Java-Installation angegeben werden, die von expecco benutzt wird. Tragen Sie hier ein JDK ein. Falls Sie unter Windows das aus dem Mobile Testing Supplement verwenden möchten, lautet der Pfad
<nowiki>C:\Program Files (x86)\exept\Mobile Testing Supplement\jdk</nowiki>
Sie können auch die Systemeinstellungen verwenden.

== Android-Gerät vorbereiten ==
Wenn Sie ein Android-Gerät unter Windows anschließen benötigen Sie möglicherweise noch einen adb-Treiber für das Gerät. Einen passenden Treiber finden Sie üblicherweise auf der jeweiligen Webseite des Herstellers. Haben Sie den Universal-Treiber aus dem Mobile Testing Supplement installiert, sollte für die meisten Geräte bereits alles funktionieren. In einigen Fällen versucht auch Windows automatisch einen Treiber zu installieren, wenn Sie das Gerät zum ersten mal anschließen.
 
===USB-Debugging Einschalten===
'''Achtung:'''
Bevor Sie ein Mobilgerät mit dem Appium-Plugin ansteuern können, müssen Sie für dieses Debugging erlauben!

Für Android-Geräte finden Sie diese Option in den Einstellungen unter ''[https://www.droidwiki.org/wiki/Entwickleroptionen Entwickleroptionen]'' mit dem Namen ''[https://www.droidwiki.org/USB-Debugging USB-Debugging]''. Falls die Entwickleroptionen nicht angezeigt werden, können Sie diese freischalten, indem Sie unter "''Über das Telefon''" siebenmal auf "''Build-Nummer''" tippen.

===Wach bleiben Aktivieren===
Aktivieren Sie auch die Funktion ''Wach bleiben'', damit das Gerät nicht während der Testerstellung oder -ausführung den Bildschirm abschaltet.

Aus Sicherheitsgründen muss USB-Debugging für jeden Computer einzeln zugelassen werden. Beim Verbinden des Geräts mit dem PC über USB müssen Sie dabei am Gerät der Verbindung zustimmen. Falls Sie dies für Ihren Computer noch nicht getan haben, aber auf dem Gerät kein entsprechender Dialog erscheint, kann es helfen, das Gerät aus- und wieder einzustecken. Das kann insbesondere dann passieren, wenn Sie den ADB-Treiber installiert haben während das Gerät bereits über USB angeschlossen war. Falls auch das nicht hilft, öffnen Sie die Benachrichtigungen, indem Sie sie vom oberen Bildschirmrand herunter ziehen. Dort finden Sie die USB-Verbindung und Sie können die Optionen dazu öffnen. Wählen Sie einen anderen Verbindungstypen aus; in der Regel sollten MTP oder PTP funktionieren.

Sie können auch auf einem Emulator testen. Dieser muss nicht gesondert vorbereitet werden, da er bereits für USB-Debugging ausgelegt ist. Es ist sogar möglich, einen Emulator bei Testbeginn zu starten.

Um zu überprüfen, ob ein Gerät, das Sie an Ihren Rechner angeschlossen haben, verwendet werden kann, öffnen Sie den [[#Verbindungseditor|Verbindungseditor]]. Das Gerät sollte dort angezeigt werden.

=== Verbindung über WLAN ===
Es ist auch möglich, Android-Geräte über WLAN zu verbinden. Für Geräte mit Android 11 oder neuer ist dies direkt über WLAN möglich, im anderen Fall müssen Sie das Gerät zuerst über USB verbinden. Ab expecco 22.1 können Sie eine WLAN-Verbindung über den [[Mobile Testing Plugin#Verbindungseditor|Verbindungseditor]] aufbauen. Ansonsten ist es auch über die Eingabeaufforderung möglich.
==== Drahtlos verbinden über die Eingabeaufforderung mit expecco Versionen vor 22.1 (ab Android 11) ====
Mit expecco ab Version 22.1 funktioniert das einfacher über den Verbindungseditor.

Erlauben Sie in den Entwickleroptionen des Geräts Debugging über WLAN und öffnen Sie dessen Optionen. Sie müssen zuerst das Gerät mit dem Rechner koppeln. Wählen Sie dazu "''Gerät mit einem Kopplungscode koppeln''", um einen Kopplungscode und eine IP-Adresse mit Port zu erhalten. Öffnen Sie dann auf dem Rechner die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb pair <IP-Adresse des Geräts>:<Kopplungsport></nowiki>
wobei Sie <tt><IP-Adresse des Geräts>:<Kopplungsport></tt> durch die auf dem Gerät angezeigte IP-Adresse & Port ersetzen. Danach werden Sie aufgefordert, den Kopplungscode einzugeben. Wenn alles geklappt hat, sollte sich das Popup auf dem Gerät schließen und der Rechner als gekoppeltes Gerät angezeigt werden. Geben Sie dann in der Eingabeaufforderung ein:
<nowiki>adb connect <IP-Adresse des Geräts>:<Debug-Port></nowiki>
Die IP-Adresse ist hier noch die gleiche wie beim Koppeln, aber der Port ist ein anderer. Beides wird als IP-Adresse & Port auf dem Gerät angezeigt. Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie entweder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden. Häufig wird beim Neustart des Geräts auch die Erlaubnis für das Debugging über WLAN wieder zurückgesetzt und der verwendete Port ändert sich. Die Kopplung bleibt aber bestehen und muss beim nächsten Verbinden nicht noch einmal durchgeführt werden.

==== WLAN Verbindung über USB starten (Android 10 und früher) ====
Verbinden Sie zunächst das Gerät über USB mit dem Rechner. Öffnen Sie dann die Eingabeaufforderung und geben Sie dort ein:
<nowiki>adb tcpip 5555</nowiki>
Damit lauscht das Gerät auf eine TCP/IP-Verbindung an Port 5555. Sollten Sie mehrere Geräte angeschlossen oder Emulatoren laufen haben, müssen Sie genauer angeben, welches Gerät Sie meinen. Geben Sie in diesem Fall ein:
<nowiki>adb devices -l</nowiki>
Sie erhalten eine Liste aller Geräte, wobei die erste Spalte deren Kennung ist. Schreiben Sie dann stattdessen
<nowiki>adb -s <Gerätekennung> tcpip 5555</nowiki>
mit der Gerätekennung des gewünschten Geräts. Sie können die USB-Verbindung nun trennen. Jetzt müssen Sie die IP-Adresse Ihres Gerätes in Erfahrung bringen. Sie finden diese üblicherweise irgendwo in den Einstellungen des Geräts, beispielsweise beim Status oder in den WLAN-Einstellungen. Geben Sie dann ein:
<nowiki>adb connect <IP-Adresse des Geräts></nowiki>
Damit sollte das Gerät nun über WLAN verbunden sein und kann genauso verwendet werden, wie mit USB-Verbindung. Sie können dies überprüfen, indem Sie wieder <tt>adb devices -l</tt> eingeben oder in expecco den Verbindungsdialog öffnen. In der Liste taucht das Gerät mit seiner IP-Adresse und dem Port auf. Bedenken Sie, dass die WLAN-Verbindung nicht mehr besteht, wenn der ADB-Server oder das Gerät neu gestartet werden.

=== Verbindung zu einem Emulator ===
Sie benötigen dazu den Emulator selbst, sowie mindestens ein AVD (Android Virtual Device). Hinweise zu Installation finden Sie in der [https://developer.android.com/studio/run/emulator Android Studio Dokumentation].

Wenn Sie Android Studio bereits mit den Defaulteinstellungen installiert haben 1), sollte der Emulator bereits mitinstalliert sein. Falls nicht, wählen Sie in Android Studio "''Configure''" - "''SDK Manager''" - "''Android SDK''" - "''SDK Tools''" - ''Android Emulator''", sowie dort die "''Platform Tools''".
Alternativ geht das auch über die Kommandzeile mit dem "sdkmanager" Kommando.

Als nächstes benötigen Sie mindestens ein AVD; auch dies geht am einfachsten über den Dialog in Android Studio:
wählen sie "''Configure''" - "''AVD Manager''" und folgen den Anweisungen (Deviceauswahl, Platform und Android Version).

Auch wenn Sie den Emulator automatisieren benötigen sie Appium; installieren Sie dieses entweder mit dem Mobile Testing Supplement, oder direkt von der Appium homepage (https://github.com/appium/appium-desktop/releases).

1)Android Studio selbst wird nicht von expecco benötigt; es bietet aber kompfortable Dialoge zum Installieren von Paketen und AVDs.

== iOS-Gerät und App vorbereiten ==
Das Ansteuern von iOS-Geräten ist nur über einen Mac möglich. Lesen Sie daher auch den Abschnitt zur [[#Mac_OS|Installation unter Mac OS]].

Bevor Sie ein Mobilgerät mit dem Mobile Testing Plugin ansteuern können, müssen Sie für iOS-Geräte ab iOS 8 Debugging erlauben. Aktivieren Sie dazu die Option ''Enable UI Automation'' unter dem Menüpunkt ''Entwickler'' in den Einstellungen des Geräts. Falls Sie den Eintrag ''Entwickler'' in den Einstellungen nicht finden, gehen Sie wie folgt vor: Schließen Sie das Gerät über USB an den Mac an. Dabei müssen Sie ggf. am Gerät noch der Verbindung zustimmen. Starten Sie Xcode und wählen Sie dann in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie dort Ihr Gerät aus. Danach sollte der Eintrag ''Entwickler'' in den Einstellungen auf dem Gerät auftauchen. Dazu müssen Sie möglicherweise die Einstellungen beenden und neu starten.

[[Datei:Alert.png | thumb | 270px | Beispiel für einen Alert unter iOS]]
Ein Verbindungsaufbau zu dem Gerät ist nicht möglich solange es bestimmte Alerts zeigt. Ein solcher Alert kann z. B. erscheinen wenn FaceTime aktiviert ist, indem ein Hinweis auf anfallende SMS-Gebühren angezeigt wird (siehe Screenshot). Achten Sie darauf, das Gerät so zu konfigurieren, dass es im Leerlauf keine solchen Alerts zeigt.

=== expecco 2.11 und später ===
Sie können beliebige Apps testen, die auf dem verwendeten Gerät lauffähig oder bereits installiert sind. Wenn die App als Development-Build vorliegt, muss die UDID des Geräts in der App hinterlegt sein. In jedem Fall muss der WebDriverAgent für das Gerät signiert werden. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]] unter Mac OS.

Falls Sie in einem Test den Home-Button verwenden wollen, müssen Sie auf dem Gerät AssistiveTouch aktivieren. Sie finden diese Option in den Einstellungen unter ''Allgemein'' > ''Bedienungshilfen'' > ''AssistiveTouch''. Platzieren Sie dann das Menü in der Mitte des oberen Bildschirmrands. Sie können das Drücken des Home-Buttons dann mit dem entsprechenden Menüeintrag im Recorder aufzeichnen oder direkt den Baustein ''Press Home Button'' benutzen.

=== expecco 2.10 ===
Die App, die Sie verwenden wollen, muss als Development-Build vorliegen. Außerdem muss die UDID des Geräts in der App hinterlegt sein.

=== Development-Build signieren ===
Ein Development-Build einer App ist nur für eine begrenzte Zahl von Geräten zugelassen und kann auf anderen Geräten nicht gestartet werden. Es ist aber möglich, das Zertifikat und die verwendbaren Geräte in einem Development-Build auszutauschen.

* Evaluierung mit Demo-App von eXept:
:Gerne stellen wir Ihnen eine Demo-App zur Verfügung, die als Development-Build vorliegt und die wir für Ihr Gerät signieren können. Senden Sie dazu bitte Ihrem eXept-Ansprechpartner die UDID Ihres Gerätes zu. Wie Sie die UDID Ihres Gerätes ermitteln können, ist im folgenden Abschnitt beschrieben.

* Eigene App für Ihr Testgerät verwenden:
:Wenn Sie von den App-Entwicklern einen Development-Build (IPA-Datei) erhalten, der für Ihr Testgerät zugelassen ist, können Sie diesen direkt verwenden. Dazu müssen Sie den Entwicklern die UDID Ihres Geräts mitteilen, damit sie diese eintragen können. '''Sie können die UDID eines Gerätes mithilfe von Xcode auslesen'''. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü ''Window'' den Eintrag ''Devices''. Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wählen Sie Ihr Gerät aus und suchen Sie in Eigenschaften den Eintrag ''Identifier''. Die UDID ist eine 40-stellige Hexadezimalzahl.

* Extern entwickelte App für Ihr Testgerät umsignieren:
:Es können auch Apps umsigniert werden, damit Sie auf anderen Geräten lauffähig sind. Dieser Vorgang ist jedoch kompliziert und setzt insbesondere einen Zugang zu einem Apple-Developer-Account voraus. Eine Dokumentation zur Vorgehensweise ist derzeit in Vorbereitung.

:Für die Evaluierung unterstützen wir Sie gerne beim Umsignieren Ihrer App.


Weitere Informationen zur Verwendung von iOS-Geräten finden Sie auch in der [http://appium.io/slate/en/master/?java#appium-on-real-ios-devices Dokumentation von Appium].

=== Native iOS-Apps ===
Sie können auch Apps verwenden, die bereits nativ auf dem Gerät vorhanden sind. Dazu müssen Sie deren Bundle-ID kennen und diese dann in die Verbindungseinstellungen eintragen. Hier eine kleine Auswahl gängiger Apps:
{| style="text-align:left"
! App
!
! Bundle-ID
|-
| App Store
|
| com.apple.AppStore
|-
| Calculator
|
| com.apple.calculator
|-
| Calendar
|
| com.apple.mobilecal
|-
| Camera
|
| com.apple.camera
|-
| Contacts
|
| com.apple.MobileAddressBook
|-
| iTunes Store
|
| com.apple.MobileStore
|-
| Mail
|
| com.apple.mobilemail
|-
| Maps
|
| com.apple.Maps
|-
| Messages
|
| com.apple.MobileSMS
|-
| Phone
|
| com.apple.mobilephone
|-
| Photos
|
| com.apple.mobileslideshow
|-
| Settings
|
| com.apple.Preferences
|}

Weitere Bundle-IDs finden Sie [https://github.com/joeblau/apple-bundle-identifiers hier].

= Beispiele =
Bei den Demo-Testsuiten für expecco finden Sie auch Beispiele für Tests mit dem Mobile Testing Plugin. Wählen Sie dazu auf dem Startbildschirm die Option "''Beispiel aus Datei''" und öffnen Sie den Ordner "''mobile''".

== ''m01_MobileTestingDemo.ets'' ==
Die Testsuite enthält zwei einfache Testpläne: "''Simple CalculatorTest''" und "''Complex Calculator and Messaging Test''". Beide Tests verwenden einen Android-Emulator, den Sie vor Beginn starten müssen. Die Apps, die im Test verwendet werden, gehören zur Grundausstattung des Emulators und müssen daher nicht mehr installiert werden. Da sich die Apps unter jeder Android-Version unterscheiden können, ist es wichtig, dass Ihr Emulator unter Android 6.0 läuft. Außerdem muss die Sprache auf Englisch gestellt sein.

; Simple CalculatorTest
: Dieser Test verbindet sich mit dem Taschenrechner und gibt die Formel ''2+3'' ein. Das Ergebnis des Rechners wird mit dem erwarteten Wert ''5'' verglichen.

; Complex Calculator and Messaging Test
: Dieser Test verbindet sich mit dem Taschenrechner und öffnet anschließend den Nachrichtendienst. Dort wartet er auf eine einkommende Nachricht von der Nummer ''15555215556'', in der eine zu berechnende Formel gesendet wird. Die Nachricht wird zuvor über einen Socket beim Emulator erzeugt. Nach dem Eintreffen der Nachricht wird diese vom Test geöffnet und deren Inhalt gelesen. Danach wird wieder der Taschenrechner geöffnet, die erhaltene Formel eingegeben und das Ergebnis gelesen. Anschließend wechselt der Test wieder zum Nachrichtendienst und sendet das Ergebnis als Antwort.

== ''m02_expeccoMobileDemo.ets'' und ''m03_expeccoMobileDemoIOS.ets'' ==
Diese sind Bestandteil des Tutorials zum Mobile Testing Plugin. Der jeweils enthaltene Testfall ist unvollständig und wird im Zuge des Tutorials ergänzt. Lesen Sie dazu den Abschnitt [[#Tutorial|Tutorial]].

= Tutorial =
Es gibt ein Tutorial, das das grundsätzliche Vorgehen zur Erstellung von Tests mit dem Mobile Testing Plugin beschreibt. Grundlage dafür ist ein mitgeliefertes Beispiel, bestehend aus einer einfachen App und einer expecco-Testsuite.

Sie finden es auf der Seite [[Mobile_Testing_Tutorial|Mobile Testing Tutorial]] in zwei Versionen für Android und für iOS.
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_Android|Erste Schritte mit Android]]
* [[Mobile_Testing_Tutorial#Erste_Schritte_mit_iOS|Erste Schritte mit iOS]]

= Dialoge des Mobile Testing Plugins =
== Verbindungseditor ==
Mithilfe des Verbindungseditors können Sie schnell Verbindungen definieren, ändern oder aufbauen. Je nach Aufgabe weist der Dialog kleine Unterschiede auf und wird unterschiedlich geöffnet:
*Um eine Verbindung aufzubauen, klicken Sie im GUI-Browser auf "''Verbinden'"' klicken und wählen dann "''Mobile Testing''".
*Um eine bestehende Verbindung im GUI-Browser zu ändern oder zu kopieren, wählen Sie diese aus, machen einen Rechtsklick und wählen im Kontextmenü "''Verbindung bearbeiten''" oder "''Verbindung kopieren''" aus.
*Wollen Sie Verbindungseinstellungen nicht für den GUI-Browser sondern zur Verwendung in einem Test erstellen, wählen Sie im Menü des Mobile Testing Plugins den Punkt "''Verbindungseinstellungen erstellen...''". Darüber können nur die Einstellungen für eine Verbindung erstellt werden, ohne dass eine Verbindung tatsächlich angelegt wird.

Einige der Schaltflächen sind nur beim Erstellen von Verbindungseinstellungen sichtbar:
[[Datei:MobileTestingVerbindungseditorMenu.png]]
#"''Einstellungen löschen''": Setzt alle Einträge zurück. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Einstellungen aus Datei laden''": Erlaubt das Öffnen einer gespeicherten Einstellungsdatei (*.csf). Deren Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen aus Anhang laden''": Erlaubt das Öffnen eines Anhangs mit Verbindungseinstellungen aus einem geöffneten Projekt. Diese Einstellungen werden in den Dialog übernommen. Bereits getätigte Eingaben ohne Konflikt bleiben dabei erhalten.
#"''Einstellungen in Datei speichern''" sowie
#"''Einstellungen in Anhang speichern''": Hier können Sie die eingetragenen Einstellungen in eine Datei (*.csf) speichern oder als Anhang in einem geöffneten Projekt anlegen. Beide Optionen besitzen ein verzögertes Menü, in dem Sie auswählen können, nur einen bestimmten Teil der Einstellungen zu speichern. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Erweiterte Ansicht''": Damit können Sie in die erweiterte Ansicht wechseln, um zusätzliche Einstellungen vorzunehmen. Lesen Sie dazu mehr am Ende des Kapitels. (Nur beim Erstellen von Einstellungen sichtbar.)
#"''Hilfe''": An der rechten Seite wird ein Hilfetext zum jeweiligen Schritt ein- oder ausgeblendet.

Der Dialog ist in drei Schritte unterteilt. Im ersten Schritt wählen Sie das Gerät, das Sie verwenden möchten, im zweiten Schritt wählen Sie aus, welche App verwendet werden soll und im letzten Schritt erfolgen die Einstellungen zum Appium-Server.

===Schritt 1: Gerät auswählen===
Im oberen Teil erhalten Sie eine Liste aller angeschlossenen Appium-Geräte, die erkannt werden. Mit der Checkbox darunter können Sie die Geräte ausblenden, die zwar erkannt werden, aber nicht bereit sind. Falls Sie ein Gerät eintragen wollen, das nicht angeschlossen ist, können Sie dies mit dem entsprechenden Knopf "''Android-Gerät eingeben''" bzw. "''iOS-Gerät eingeben''" anlegen. Dazu müssen Sie jedoch die benötigten Eigenschaften Ihres Geräts kennen. Das Gerät wird dann in einer zweiten Geräteliste angelegt und kann dort ausgewählt werden. Wenn keine Liste mit angeschlossenen Elementen angezeigt werden kann, werden stattdessen verschiedene Meldungen angezeigt:
*Keine Geräte gefunden
*:expecco konnte kein Android-Geräte finden.
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*Keine verfügbaren Geräte gefunden
*:expecco konnte keine verfügbaren Android-Geräte finden. Es wurden aber nicht verfügbare gefunden, z.B. mit dem Status "unauthorized".
*:Um eine Verbindung zu einem Gerät automatisch zu konfigurieren, stellen Sie sicher, dass es
*:*angeschlossen ist
*:*eingeschaltet ist
*:*einen passenden adb-Treiber installiert hat
*:*für Debugging freigeschaltet ist (siehe unten).
*:Um nicht verfügbare Geräte anzuzeigen, aktivieren Sie unten diese Option.
*Verbindung verloren
*:expecco hat die Verbindung zum adb-Server verloren. Versuchen Sie die Verbindung wieder herzustellen, indem Sie auf den Button klicken.
*Verbindung fehlgeschlagen
*:expecco konnte sich nicht mit dem adb-Server verbinden. Möglicherweise läuft er nicht oder der angegebene Pfad stimmt nicht.
*:Überprüfen Sie die adb-Konfiguration in den Einstellungen und versuchen Sie den adb-Server zu starten und eine Verbindung herzustellen indem Sie auf den Knopf klicken.
*Verbinden ...
*:expecco verbindet sich mit dem adb-Server. Dies kann einige Sekunden dauern.
*adb-Server starten ...
*:expecco startet den adb-Server. Dies kann einige Sekunden dauern.

Mit "''Weiter''" gelangen Sie zum nächsten Schritt. Wenn Sie Einstellungen für den GUI-Browser eingeben, ist das erst möglich, wenn ein Gerät ausgewählt wurde.

Anmerkung zum Freischalten: In jüngeren Android Versionen werden die Entwickleroptionen zunächst nicht mehr in den Einstellungen angeboten. Falls ihr Android Gerät in den Einstellungen keinen Eintrag zu "''Entwickleroptionen''" zeigt, wählen Sie zunächst den Eintrag "''Telefoninfo''", dann "''SoftwareVersionsInfo''" und klicken darin mehrfach auf den Eintrag "''BuildVersion''".

==== Chromedriver verwalten ====
Wenn die App, die Sie bedienen wollen, WebViews mit Chrome benutzt, benötigt Appium Zugriff auf einen passenden Chromedriver. Wenn Sie ein Gerät in der Liste auswählen, können Sie über "''Chromedriver verwalten''" sehen, welche Chrome-Versionen auf dem Gerät vorhanden sind und welche Chromedriver-Versionen durch expecco zur Verfügung stehen. Über diesen Dialog können Sie auch benötigte Chromedriver-Versionen herunterladen. Beachten Sie, dass auf dem Gerät verschiedene Chrome-Versionen vorhanden sein können, da die Apps in ihren WebViews nicht die gleiche Chrome-Version verwenden müssen, wie die als Browser installierte. Damit alles funktioniert, sollte der verwendete Chromedriver zur entsprechenden App passen. Sie können den Pfad zum Chromedriver auch am Ende des Verbindungsdialogs in den erstellten Capabilities ändern.

==== WLAN-Android-Geräte verbinden ====
Sie können sich auch über WLAN zu Android-Geräten verbinden. Dazu muss das Gerät zunächst mit adb verbunden werden, siehe [[Mobile_Testing_Plugin#Verbindung_.C3.BCber_WLAN|Verbindung über WLAN]]. Ab expecco 22.1 bietet der Verbindungseditor hierfür einen Dialog, der Ihnen dabei hilft und den Sie anstatt der Eingabeaufforderung verwenden können. Für Geräte mit Android 11 oder höher können Sie hier das Gerät mit dem Rechner zu koppeln, indem Sie die entsprechenden Parameter angeben und anschließend die Verbindung unter Angabe von IP-Adresse und Port aufbauen. Sie können damit auch für Geräte, die über USB verbunden sind, eine WLAN-Verbindung aufbauen. Wenn Sie das entsprechende Gerät in der Liste auswählen, werden die benötigten Angaben automatisch ausgelesen.

Beachten Sie, dass der Aufbau einer WLAN-Verbindung nicht Teil der Verbindungseinstellungen ist. Wenn Sie mit den erzeugten Einstellungen eine neue Verbindung aufbauen wollen, müssen Sie sicherstellen, dass das Gerät über mit der angegebenen IP-Adresse und dem Port mit adb verbunden ist, damit es gefunden wird. Die ADB-Verbindung geht verloren, wenn der ADB-Server oder das Gerät neu gestartet werden. Die Erlaubnis für das WLAN-Debugging wird beim Neustart des Geräts auch häufig zurückgesetzt und der Debug-Port kann dann wechseln. Daher muss eine WLAN-Verbindung immer manuell hergestellt werden.

===Schritt 2: App auswählen===
Hier können Sie Angaben zur App machen, die getestet werden soll. Dabei können Sie entscheiden, ob Sie eine App verwenden wollen, die bereits auf dem Gerät installiert ist, oder ob für den Test eine App installiert werden soll. Wählen Sie oben den entsprechenden Reiter aus. Je nachdem, ob Sie im vorigen Schritt ein Android- oder ein iOS-Gerät ausgewählt haben, ändert sich die erforderte Eingabe.

*'''Android'''
**''App auf dem Gerät''
**:Wenn Sie im ersten Schritt ein angeschlossenes Gerät ausgewählt haben, werden die Pakete aller installierten Apps automatisch abgerufen und Sie können die Auswahl aus den Drop-down-Listen treffen. Die installierten Apps sind in Fremdpakete und Systempakete unterteilt; wählen Sie die entsprechende Paketliste aus. Diese Auswahl gehört nicht zu den Einstellungen, sondern stellt nur die entsprechende Paketliste zur Verfügung. Sie können den Filter benutzen, um die Liste weiter einzuschränken und dann das gewünschte Paket auswählen. Die Activities des ausgwählten Pakets werden ebenfalls automatisch abgerufen und als Drop-down-Liste zur Verfügung gestellt. Wählen Sie die Activity aus, die gestartet werden soll. In der Regel wird automatisch eine Activity aus der Liste eingetragen. Falls Sie kein verbundenes Gerät verwenden, müssen Sie die Eingabe des Pakets und der Activity von Hand vornehmen.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Benutzen Sie einen lokalen Appium-Server, können Sie den rechten Butten benutzen, um zu der Installationsdatei der App zu navigieren und diesen Pfad einzutragen. Wenn möglich werden dabei auch das entsprechende Paket und die Activity in den Feldern darunter eingetragen. Diese Angabe ist aber nicht notwendig.

*'''iOS'''
**''App auf dem Gerät''
**:Geben Sie die Bundle-ID einer installierten App an. Sie können die IDs der installierten Apps bspw. mithilfe von Xcode erfahren. Starten Sie dazu Xcode und wählen Sie in der Menüleiste am oberen Bildschirmrand im Menü "''Window''" den Eintrag "''Devices''". Es öffnet sich ein Fenster, in dem eine Liste der angeschlossenen Geräte angezeigt wird. Wenn Sie Ihr Gerät auswählen, sehen Sie in der Übersicht eine Auflistung der von Ihnen installierten Apps.
**''App installieren''
**:Geben Sie bei "''App''" den Pfad zu einer App an. Der Pfad muss für den Appium-Server gültig sein, der verwendet wird. Sie können auch eine URL angeben. Zu den Vorraussetzungen an Apps für reale Geräte lesen Sie bitte den Abschnitt [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Geräte und App vorbereiten]].

Im unteren Teil können Sie festlegen, ob die App beim Verbindungsabbau zurückgesetzt bzw. deinstalliert werden soll, und ob sie initial zurückgesetzt werden soll. Auch hier wird die entsprechende Capability gar nicht gesetzt, wenn Sie "''(Default)''" auswählen. Mit "''Weiter''" gelangen Sie zum nächsten Schritt.

===Schritt 3: Servereinstellungen===
Im letzten Schritt befindet sich zunächst im oberen Teil eine Liste aller Capabilities, die sich aus Ihren Angaben der vorigen Schritte ergeben. Wenn Sie sich mit Appium auskennen und noch zusätzliche Capabilities setzen möchten, die der Verbindungseditor nicht abdeckt, können Sie durch Klicken auf "''Bearbeiten''" in die erweiterte Ansicht gelangen. Lesen Sie dazu den Abschnitt weiter unten.

Wenn Sie Einstellungen für den GUI-Browser eingeben, können Sie den ''Verbindungsnamen'' eintragen, mit dem die Verbindung angezeigt wird. Dies ist auch der Name unter dem Bausteine diese Verbindung verwenden können, wenn sie aufgebaut ist. Wenn Sie das Feld frei lassen, wird ein Name generiert. Wenn der Haken für "''Von expecco gesteuert''" gesetzt ist, wird expecco einen lokalen Appium-Server an einem freien Port starten, oder einen bereits gestarteten freien Server verwenden. Um einen eigenen Server zu verwenden, schalten Sie diese Funktion ab und geben Sie die entsprechende Adresse ein. Sie erhalten die lokale Standard-Adresse und bereits verwendete Adressen zur Auswahl.

In älteren expecco-Versionen ist der Haken mit "''Bei Bedarf starten''" beschriftet. In diesem Fall müssen Sie auch eine Adresse angeben, wenn expecco den Server starten soll. expecco versucht dann beim Verbinden einen Appium-Server an der angegebenen Adresse zu starten, wenn dort noch keiner läuft. Dieser Server wird dann beim Beenden der Verbindung ebenfalls heruntergefahren. Dies funktioniert nur für lokale Adressen. Achten Sie darauf, nur Portnummern zu verwenden, die auch frei sind. Verwenden Sie am besten nur ungerade Portnummern ab dem Standardport 4723. Beim Verbindungsaufbau wird ebenfalls die folgende Portnummer verwendet, wodurch es sonst zu Konflikten kommen könnte.

Je nachdem, wie Sie den Dialog geöffnet haben, gibt es nun verschiedene Schaltflächen um ihn abzuschließen. In jedem Fall haben Sie die Option zu speichern. Dabei öffnet sich ein Dialog, indem Sie entweder ein geöffnet Projekt auswählen können, um die Einstellungen dort als Anhang zu speichern, oder auswählen es in einer Datei zu speichern, die Sie anschließend angeben können. Durch das Speichern wird der Dialog nicht beendet, wodurch Sie anschließend noch eine andere Option auswählen könnten.

Wenn Sie den Editor zum Verbindungsaufbau geöffnet haben, können Sie abschließend auf "''Verbinden''" oder "''Server starten und verbinden''" klicken, je nachdem, ob der Haken für den Serverstart gesetzt ist. Für das Ändern oder Kopieren einer Verbindung im GUI-Brower heißt diese Option "''Übernehmen''", da in diesem Fall nur der Verbindungseintrag geändert bzw. neu angelegt wird, der Verbindungsaufbau aber nicht gestartet wird. Das können Sie bei Bedarf anschließend über das Kontextmenü tun. Falls Sie Capabilities einer bestehenden Verbindung geändert haben, fordert Sie anschließend ein Dialog auf zu entscheiden, ob diese Änderungen direkt übernommen werden sollen, indem die Verbindung abgebaut und mit den neuen Verbindungen aufgebaut wird, oder nicht. In diesem Fall werden die Änderungen erst wirksam, nachdem Sie die Verbindung neu aufbauen.

Zur Verwendung des Verbindungseditors lesen Sie auch den entsprechenden Abschnitt im jeweiligen Tutorial in Schritt 1 (Android: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren|Demo ausführen]], iOS: [[Mobile_Testing_Tutorial#Schritt_1:_Demo_ausf.C3.BChren_.28iOS.29|Demo ausführen (iOS)]]).

===Erweiterte Ansicht===
Die erweiterte Ansicht des Verbindungseditors erhalten Sie entweder durch Klicken auf "''Bearbeiten''" im dritten Schritt oder jederzeit über den entsprechenden Menüeintrag, wenn Sie den Editor über das Plugin-Menü gestartet haben. In dieser Ansicht erhalten Sie eine Liste aller eingestellten Appium-Capabilities. Zu dieser können Sie weitere hinzufügen, Einträge ändern oder entfernen. Um eine Capability hinzuzufügen, wählen Sie diese aus der Drop-down-Liste des Eingabefelds aus. In dieser befinden sich alle bekannten Capabilities sortiert in die Kategorien ''Common'', ''Android'' und ''iOS''. Haben Sie eine Capability ausgewählt, wird ein kurzer Informationstext dazu angezeigt. Sie können in das Feld auch von Hand eine Capability eingeben. Klicken Sie dann auf "''Hinzufügen''", um die Capabilitiy in die Liste einzutragen. Dort können Sie in der rechten Spalte den Wert setzen. Um einen Entrag zu löschen, wählen Sie diesen aus und klicken Sie auf "''Entfernen''". Mit "''Zurück''" verlassen Sie die erweiterte Ansicht.

[[Datei:MobileTestingErweiterteAnsicht.png]]

== Laufende Appium-Server ==
Im Menü des Mobile Testing Plugins finden Sie den Eintrag "''Appium-Server...''". Mit diesem öffnen Sie ein Fenster mit einer Übersicht aller Appium-Server, die von expecco gestartet wurden und auf welchem Port diese laufen. Durch Klicken auf das Icon in der Spalte "''Log anzeigen''" können Sie das Logfile des entsprechenden Servers anschauen. Dieses wird beim Beenden des Servers wieder gelöscht. Mit den Icons in der Spalte "''Beenden''" kann der entsprechenden Server beendet werden. Allerdings wird dies verhindert, wenn expecco über diesen Server noch eine offene Verbindung hat. Für welche Verbindung ein Server verwendet wird, sehen Sie in der rechten Spalte. Steht dort ''<idle>'' wird er zur Zeit nicht von expecco verwendet.

[[Datei:MobileTestingAppiumServer.png]]

Beim Öffnen des Editors um eine Appium-Verbindung aufzubauen, wird direkt ein Appium-Server gestartet, um den folgenden Verbindungsaufbau zu beschleunigen. Zu diesem Zweck hält sich expecco auch immer einen freien Appium-Server offen. Weitere laufende Server, die nicht mehr verwendet werden, werden jedoch nach einiger Zeit automatisch beendet.

Im Menü des Mobile Testing Plugins finden Sie auch den Eintrag "''Alle Verbindungen und Server beenden''". Dies ist für den Fall gedacht, dass Verbindungen oder Server auf andere Weise nicht beendet werden können. Beenden Sie Verbindungen wenn möglich immer im GUI-Browser oder durch Ausführen eines entsprechenden Bausteins. Server, die Sie in der Server-Übersicht gestartet haben, beenden Sie dort; Server, die mit einer Verbindung gestartet wurden, werden automatisch mit dieser beendet.

Beachten Sie, dass in der Übersicht nur Server aufgelistet sind, die von expecco gestartet und verwaltet werden. Mögliche andere Appium-Server, die auf andere Art gestartet wurden, werden nicht erkannt.

== Recorder ==
Besteht im GUI-Browser eine Verbindung zu einem Gerät, kann der integrierte Recorder verwendet werden, um mit diesem Gerät einen Testabschnitt aufzunehmen. Sie starten den Recorder, indem Sie im GUI-Browser die entsprechende Verbindung auswählen und dann auf den Aufnahme-Knopf klicken. Für den Recorder öffnet sich ein neues Fenster. Die aufgezeichneten Aktionen werden im Arbeitsbereich des GUI-Browsers angelegt. Daher ist es möglich, das Aufgenommene parallel zu editieren.

[[Datei:MobileTestingRecorder.png|caption|]]

====Komponenten des Recorderfensters====
#'''Aufnahme fortsetzen/pausieren''': Über das rechte Symbol können Sie die Aufnahme pausieren. Sie sehen dann ein großes Pause-Symbol in der Anzeige. Alle Aktionen, die Sie währenddessen im Recorder machen werden zwar ausgeführt, es werden aber keine Bausteine aufgezeichnet. Über das linke Symbol können Sie dann wieder in den normalen Aufnahmemodus wechseln.
#'''Aufnahme stoppen''': Stoppt die Aufnahme und schließt das Recorderfenster.
#'''Aktualisieren''': Holt das aktuelle Bild und den aktuellen Elementbaum vom Gerät. Dies wird nötig, wenn das Gerät zur Ausführung einer Aktion länger braucht oder sich etwas ohne das Anstoßen durch den Recorder ändert. Seit expecco 21.2 gibt es hier zusätzlich ein Untermenü, mit dem automatisches Aktualisieren angeschaltet werden kann, indem im Hintergrund auf Änderungen geprüft wird (siehe auch ''Automatisches Aktualisieren'' weiter unten).
#'''Follow-Mouse''': Das Element unter dem Mauszeiger wird im GUI-Browser ausgewählt.
#'''Element-Highlighting''': Das Element unter dem Mauszeiger wird rot umrandet.
#'''Elemente einzeichnen''': Die Rahmen aller Elemente der Ansicht werden angezeigt.
#'''Werkzeuge''': Auswahl, mit welchem Werkzeug aufgenommen werden soll. Die gewählte Aktion wird bei einem Klick auf die Anzeige ausgelöst. Dabei stehen folgende Aktionen zur Verfügung:
#*Aktionen auf Elemente:
#**Klicken: Kurzer Klick auf das Element, über dem der Cursor steht. Zur genaueren Bestimmung, welches Element verwendet wird, benutzen Sie die Funktion Follow-Mouse oder Element-Highlighting.
#**Antippen mit Dauer (Element): Ähnlich zum Klicken, nur dass zusätzlich die Dauer des Klicks aufgezeichnet wird. Dadurch sind auch längere Klicks möglich.
#**Antippen mit Position (Element): Ähnlich zum Klicken, aber zusätzlich wird die Position innerhalb des Elements aufgenommen. Die Position kann relativ zur Größe des Elements aufgenommen werden oder, wenn Sie dabei Strg gedrückt halten, absolut zur linken oberen Ecke des Elements.
#**Text setzen: Ermöglicht das Setzen eines Textes in Eingabefelder.
#**Text löschen: Löscht den Text eines Eingabefelds.
#*Aktionen auf das Gerät:
#**Antippen (Bildschirm): Löst einen Klick auf die Bildschirmposition aus.
#**Antippen mit Dauer (Bildschirm): Löst einen Klick auf die Bildschirmposition aus, bei dem auch die Dauer berücksichtigt wird.
#**Wischen: Wischen in einer geraden Linie vom Punkt des Drückens des Mausknopfes bis zum Loslassen. Die Dauer wird ebenfalls aufgezeichnet.
#:Beachten Sie bei diesen Aktionen, dass das Ergebnis sich auf verschiedenen Geräten unterscheiden kann, bspw. bei verschiedenen Bildschirmauflösungen.
#*Erstellen von Testablauf-Bausteinen
#**Attribut prüfen: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Das Ergebnis triggert den entsprechenden Ausgang.
#**Attribut zusichern: Vergleicht den Wert eines festgelegten Attributs des Elements mit einem vorgegebenen Wert. Bei Ungleichheit schlägt der Test fehl.
#**Attribut holen: Liest den aktuellen Wert eines Attributs aus.
#*Automatisch
#:Ist das Auto-Werkzeug ausgewählt, können alle Aktionen durch spezifische Eingabeweise benutzt werden: ''Klicken'', ''Element antippen'' und ''Wischen'' funktionieren weiterhin durch Klicken, wobei sie anhand der Dauer und der Bewegung des Cursors unterschieden werden. Um ein ''Antippen'' auszulösen, halten Sie beim Klicken Strg gedrückt. Die übrigen Aktionen erhalten Sie durch einen Rechtsklick auf das Element in einem Kontextmenü.
#'''Kontext-Aktionen''': Hier können Sie Aktionen aufzeichnen, die Kontexte betreffen:
#*Zu Kontext wechseln: Bietet eine Liste der aktuell verfügbaren Kontexte und Sie können auswählen, zu welchem gewechselt werden soll.
#*Aktuellen Kontext holen: Holt den Handle des aktuellen Kontexts.
#*Kontext-Handles holen: Holt eine Liste aller aktuell verfügbaren Kontext-Handles.
#'''Softkeys''': Nur unter Android. Simuliert das Drücken der Knöpfe Zurück, Home, Fensterliste und Power.
#'''Home-Button''': Nur unter iOS ab expecco 2.11. Ermöglicht das Drücken des Home-Buttons. Vor expecco 19.2 funktioniert es nur, wenn AssistiveTouch aktiviert ist und sich das Menü in der Mitte des oberen Bildschirmrands befindet. Ab expecco 19.2 verwendet die Funktion kein AssistiveTouch mehr.
#'''Hilfe''': Öffnet diese Online-Dokumentation auf der allgemeinen Seite zu [[GuiBrowser_Recorder|GUI-Browser Recordern]].
#'''Anzeige''': Zeigt einen Screenshot des Geräts. Aktionen werden mit der Maus je nach Werkzeug ausgelöst. Wenn eine neue Aktion eingegeben werden kann, hat das Fenster einen grünen Rahmen, sonst ist er rot.
#'''Fenster an Bild anpassen''': Ändert die Größe des Fensters so, dass der Screenshot vollständig angezeigt werden kann.
#'''Bild an Fenster anpassen''': Skaliert den Screenshot auf eine Größe, mit der er die volle Größe des Fensters ausnutzt.
#'''Ansicht anpassen''': Öffnet einen Dialog um die Ansicht anzupassen, falls expecco das Bild nicht richtig darstellt. Sie können die Skalierung anpassen oder das Bild um 90° drehen.
#'''Ausrichtung anpassen''': Korrigiert das Bild, falls dieses auf dem Kopf stehen sollte. Über den Pfeil rechts daneben kann das Bild auch um 90° gedreht werden, falls dies einmal nötig sein sollte. Ab expecco 19.1 finden Sie diese Funktion in ''Ansicht anpassen''. Die Ausrichtung des Bildes ist für die Funktion des Recorders unerheblich, dieser arbeitet ausschließlich auf den erhaltenen Elementen.
#'''Skalierung''': Ändert die Skalierung des Screenshots.
#'''Meldungen''': Zeigt den Pfad des ausgewählten Elements oder andere Meldungen an. Es gibt ein Kontextmenü, um eine Liste der vorigen Meldungen zu sehen.

====Verwendung====
Mit jedem Klick im Fenster wird eine Aktion ausgelöst und im Arbeitsbereich des GUI-Browsers aufgezeichnet. Dort können Sie das Aufgenommene abspielen, editieren oder daraus einen neuen Baustein erstellen.
Aktionen zum Auslösen von Sofkeys finden Sie direkt in der Menüleiste (s.o.). Um Aktionen auf Elemente aufzuzeichen, ändern Sie entweder die Auswahl des Werkzeugs in der Menüleiste (s.o.) und klicken dann auf das Element oder wählen Sie die entsprechende Aktion aus dem Kontextmenü durch einen Rechtsklick auf das entsprechende Element aus. Für Texteingabe ist es zudem möglich, den Cursor über dem Element zu platzieren und den Text einzugeben. Dabei öffnet sich der Eingabedialog für diese Aktion.
Zur Verwendung des Recorders lesen Sie auch Schritt 2 im Tutorial ([[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen|Android]] bzw. [[Mobile_Testing_Tutorial#Schritt_2:_Einen_Baustein_mit_dem_Recorder_erstellen_.28iOS.29|iOS]]).

====Elemente verbergen====
Ab expecco 21.2 gibt es im Kontextmenü außerdem die Möglichkeit, das ausgewählte Element im Recorder zu verbergen. Das bedeutet, dass dieses Element fortan nicht mehr ausgewählt werden kann. Diese Funktion eignet sich dazu, Elemente zu ignorieren, die im Vordergrund liegen, um auf Elemente darunter zugreifen zu können. Um diesen Zustand wieder rückgängig zu machen, müssen Sie das entsprechende Element im Baum des GUI-Browsers finden, dort gibt es im Kontextmenü ebenfalls einen solchen Eintrag.

====Automatisches Aktualisieren====
Der Recorder zeigt kein Livebild des Geräts sondern nur eine Momentaufnahme. Um mit der Anzeige auf dem Gerät übereinzustimmen muss daher nach Änderungen aktualisiert werden. Der Recorder aktualisiert sich automatisch, nachdem er eine Aktion ausgeführt hat. Ab expecco 20.2 sind zudem weitere automatische Updates möglich. Sie können Sie im Menü ''Fenster'' aktivieren.

Zum einen kann kurze Zeit nach dem Ausführen einer Aktion überprüft werden, ob es noch Änderungen nach der ersten Aktualisierung gegeben hat, damit in diesem Fall eine zweite Aktualisierung stattfinden kann. Dies soll das Problem beheben, dass der Recorder nach einer Aktion nicht aktuell ist, weil die Aktualisierung zu früh stattgefunden hat.

Zum anderen kann eine periodische Aktualisierung eingeschaltet werden. Nach einem einstellbaren Interval wird der Recorder automatisch aktualisiert, sollte es Änderungen geben. Dadurch ist die Anzeige im Recorder immer weitgehend aktuell, allerdings entsteht dadurch auch ein Mehraufwand was die Kommunikation mit dem Gerät betrifft.

== AVD Manager und SDK Manager ==
AVD Manager und SDK Manager sind beides Anwendungen von Android. Im Menü des Mobile Testing Plugins bietet expecco die Möglichkeit, diese zu starten. Ansonsten finden Sie diese Programme bei Ihrer Android-Installation. Mit dem AVD Manager können Sie AVDs, also Konfigurationen für Emulatoren, erstellen, bearbeiten und starten. Mit dem SDK Manager erhalten Sie einen Überblick über Ihre Android-Installation und können diese bei Bedarf erweitern.

= Hybrid-Apps und WebViews =

'''!!! WICHTIGER HINWEIS - Wenn Sie Probleme haben, auf den Webview zu wechseln, geben Sie bitte unter den Android Einstellungen - Apps -Standard Apps "Chrome" als "Browser-App" an !!!
'''

Hybrid-Apps enthalten neben den Plattform-nativen Elementen weitere Elemente, die in einen WebView eingebunden sind. Diese Elemente können ebenfalls bedient werden, allerdings muss zuvor in den entsprechenden Kontext gewechselt werden. Mit dem Baustein "''Get Current Context''" erhalten Sie den aktuellen Kontext. Zu Beginn ist dies "''NATIVE_APP''", also der Kontext der nativen Elemente. Mit dem Baustein "''Get Context Handles''" bekommen Sie eine Collection aller vorhandenen Kontexte. Gibt es einen WebView-Kontext, so heißt dieser "''WEBVIEW_1''" oder "''WEBVIEW_<package>''" mit dem Paket des WebViews. Es kann auch mehrere WebView-Kontexte geben. Zu jedem WebView-Kontext gibt es im nativen Kontext ein entsprechendes WebView-Element. Mit dem Baustein "''Switch to Context''" können Sie in einen solchen Kontext wechseln und haben fortan nur Zugriff auf die Elemente in diesem Kontext.

Im GUI-Browser werden zum einen oben im Baum die vorhandenen Kontexte angezeigt, zum anderen wird der Baum eines Kontexts unterhalb des entsprechenden WebView-Elements eingefügt.

= XPath anpassen mithilfe des GUI-Browsers =
Bausteine, die auf einem Gerät fehlerfrei funktionieren, tun dies auf anderen Geräten möglicherweise nicht. Auch können kleine Änderungen der App dazu führen, dass ein Baustein nicht mehr den gewünschten Effekt hat. Man sollte einen Baustein daher so robust formulieren, dass er für eine Vielzahl von Geräten verwendet werden kann und kleine Anpassungen an der App verkraftet. Dazu muss man das grundlegende Funktionsprinzip der Adressierung verstehen. Dies wird im Folgenden am Beispiel der App aus dem Tutorial erläutert.

Die Ansicht der App setzt sich aus einzelnen Elementen zusammen. Dazu gehören die Schaltflächen "''GTIN-13 (EAN-13)''" und "''Verify''", das Eingabefeld der Zahl "''4006381333986''" und das Ergebnisfeld, in dem OK erscheint, wie auch alle anderen auf der Anzeige sichtbaren Dinge. Diese sichtbaren Elemente sind in unsichtbare Strukturelemente eingebettet. Alle Elemente zusammen sind in einer zusammenhängenden Hierarchie, dem Elementbaum, organisiert.

[[Datei:MobileTestingGUIBrowser.png | frame | left | Abb. 1: Funktionen des GUI-Browsers]]
 
Sie können sich diesen Baum im GUI-Browser ansehen. Wechseln Sie dazu in den GUI-Browser (Abb. 1) und starten Sie eine beliebige Verbindung. Sobald die Verbindung aufgebaut ist, können Sie den gesamten Baum aufklappen (1) (Klick bei gedrückter Strg-Taste). Er enthält alle Elemente der aktuellen Seite der App.

Ein Baustein, der nun ein bestimmtes Element verwendet, muss dieses eindeutig angeben, indem er dessen Position im Elementbaum mit einem Pfad im XPath-Format beschreibt. Dieses Format ist ein verbreiteter Web-Standard für XML-Dokumente und -Datenbanken, eignet sich aber genauso für Pfade im Elementbaum.

Wenn Sie ein Element im Baum auswählen, wird unten der von expecco automatisch generierte XPath (2) für das Element angezeigt, der auch beim Aufzeichnen verwendet wird. Oberhalb davon in der Mitte des Fensters befindet sich eine Liste der Eigenschaften (3) des ausgewählten Elements. Man nennt diese Eigenschaften auch Attribute. Sie beschreiben das Element näher wie beispielsweise seinen Typ, seinen Text oder andere Informationen zu seinem Zustand. Links unten können Sie zur besseren Orientierung im Baum die ''Vorschau'' (4) aktivieren, um sich den Bildausschnitt des Elements anzeigen zu lassen.

Der Elementbaum für gleiche Ansicht einer App kann sich je nach Gerät unterscheiden. Es sind diese Unterschiede, die verhindern, eine Aufnahme von einem Gerät unverändert auch auf allen anderen Geräten abzuspielen: Ein XPath, der im einen Elementbaum ein bestimmtes Element identifiziert, beschreibt nicht unbedingt das gleiche Element im Elementbaum auf einem anderen Gerät. Es kann stattdessen passieren, dass der XPath auf kein Element, auf ein falsches Element oder auf mehrere Elemente passt. Dann schlägt der Test fehl oder er verhält sich unerwartet.

Man könnte natürlich für jedes Gerät einen eigenen Testfall schreiben. Das brächte aber unverhältnismäßigen Aufwand bei Testerstellung und -wartung mit sich. Das Problem lässt sich auch anders lösen, da ein jeweiliges Element nicht nur durch genau einen XPath beschrieben wird. Vielmehr erlaubt der Standard mithilfe verschiedener Merkmale unterschiedliche Beschreibungen für ein und dasselbe Element zu formulieren. Das Ziel ist daher, einen Pfad zu finden, der auf allen für den Test verwendeten Geräten funktioniert und überall eindeutig zum richtigen Element führt.

Im Beispiel besteht die Verbindung zur Android-App aus dem Tutorial und der Eintrag des "''GTIN-13''"-Buttons ist ausgewählt (5). Dessen automatisch generierter XPath (2) kann beispielsweise so aussehen:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.view.ViewGroup/android.widget.FrameLayout[@resource id='android:id/content']/android.widget.RelativeLayout/android.widget.Button[@resource-id='de.exept.expeccomobiledemo:id/gtin_13']</blockquote>

Er ist offensichtlich lang und unübersichtlich. Der sehr viel kürzere Pfad

<blockquote>//*[@text='GTIN-13 (EAN-13)']</blockquote>

führt zum selben Element.

Für die iOS-App lautet der automatisch generierte XPath für diesen Button beispielsweise

<blockquote>//AppiumAUT/XCUIElementTypeApplication/XCUIElementTypeWindow[1]/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeOther/XCUIElementTypeButton[2]</blockquote>
bzw.
<blockquote>//AppiumAUT/UIAApplication/UIAWindow[1]/UIAButton[2]</blockquote>

und kann kürzer als

<blockquote>//*[@name='GTIN-13 (EAN-13)']</blockquote>

geschrieben werden.

Sie können den Pfad entsprechend im GUI-Browser ändern und durch "''Pfad überprüfen''" (6) feststellen, ob er weiterhin auf das ausgewählte Element zeigt, was expecco mit "''Verify Path: OK''" (7) bestätigen sollte. Der erste, sehr viel längere Pfad, beschreibt den gesamten Weg vom obersten Element des Baumes bis hin zum gesuchten Button. Der zweite Pfad hingegen wählt mit "*" zunächst sämtliche Elemente des Baumes und schränkt die Auswahl dann auf genau die Elemente ein, die ein ''text''- bzw. ''name''-Attribut mit dem Wert "''GTIN-13 (EAN-13)''" besitzen, in unserem Fall also genau der eine Button, den wir suchen.

Im folgenden werden Android-ähnliche Pfade zur Veranschaulichung verwendet. Die Elemente in iOS-Apps heißen zwar anders, wodurch andere Pfade entstehen; das Prinzip ist jedoch das gleiche.

[[Datei:MobileTestingBaum1.png | frame | Abb. 2: Elementbaum einer fiktiven App]]

Sie können solche Pfade mit Hilfe weniger Regeln selbst formulieren. Sehen Sie sich den einfachen Baum einer fiktiven Android-App in Abb. 2 an: Die Einrückungen innerhalb des Baumes geben die Hierarchie der Elemente wieder. Ein Element ist ein ''Kind'' eines anderen Elementes, wenn jenes andere Element das nächsthöhere Element mit einem um eins geringeren Einzug ist. Jenes Element ist das ''Elternelement'' des Kindes. Sind mehrere untereinander stehende Elemente gleich eingerückt, so sind sie also alle Kinder desselben Elternelements.

Ein Pfad durch alle Ebenen der Hierarchie zum TextView-Element ist nun:

<blockquote>//hierarchy/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.FrameLayout/android.widget.LinearLayout/android.widget.TextView</blockquote>

Die Elemente sind mit Schrägstrichen voneinander getrennt. Es fällt auf, dass der Name des ersten Elements nicht mit dem im Baum übereinstimmt. Das oberste Element in der Hierarchie heißt immer "''hierarchy''" (für iOS wäre es "''AppiumAUT''"), expecco zeigt im Baum stattdessen den Namen der Verbindung an, damit man mehrere Verbindungen voneinander unterscheiden kann. Die weiteren Elemente tragen jeweils das Präfix "''android.widget.''", das im Baum zur besseren Übersicht nicht angezeigt wird. Bei IOS gibt es kein Präfix, das durch einen Punkt abgetrennt wäre, expecco 2.11 blendet aber entsprechend "''XCUIElementType''" am Anfang aus. Mit jedem Schrägstrich führt der Pfad über eine Eltern-Kind-Beziehung in eine tiefere Hierarchie-Ebene, d. h. "''FrameLayout''" ist ein Kindelement von "''hierarchy''", "''LinearLayout''" ist ein Kind von "''FrameLayout''" usw. Die in eckigen Klammern geschriebenen Wörter dienen nur als Orientierungshilfe im Baum. Sie gehören nicht zum Typ.

Ein Pfad muss nicht beim Element "''hierarchy''" beginnen. Man kann den Pfad beginnend mit einem beliebigen Element des Baumes bilden. Man kann also verkürzt auch

<blockquote>//android.widget.TextView</blockquote>

schreiben. Der Pfad führt zum selben "''TextView''"-Element, da es nur ein Element dieses Typs gibt. Anders verhält es sich bei dem Pfad

<blockquote>//android.widget.Button.</blockquote>

Da es zwei Elemente vom Typ "''Button''" gibt, passt dieser Pfad auf zwei Elemente, nämlich den Button, der mit "''An''" markiert ist, und den ''Button'', der mit "''Aus''" markiert ist. Es würde an dieser Stelle aber auch nicht helfen den langen Pfad von ''hierarchy'' aus beginnend anzugeben. Um einen mehrdeutigen Pfad weiter zu differenzieren, kann man explizit ein Element aus einer Menge wählen, indem man den numerischen Index in eckigen Klammern dahinter schreibt. Der Pfad aus dem obigen Beispiel lässt sich damit so anpassen, dass er eindeutig auf den ''Button'' mit der Markierung "''Aus''" weist:

<blockquote>//android.widget.Button[1].</blockquote>

Ihnen fällt sicher auf, dass der Index eine 1 ist obwohl das zweite Element gemeint ist. Das kommt daher, dass die Zählung bei 0 beginnt. Der Button mit der Markierung "An" hat also die Nummer 0 und der ''Button'' mit der Markierung "''Aus''" hat die Nummer 1.

Dieser Ansatz, einen expliziten Index zu verwenden, hat zwei Nachteile: Zum einen lässt sich an dem Pfad nur schwer ablesen welches Element gemeint ist, zum andern ist der Pfad sehr empfindlich schon gegenüber kleinsten Änderungen, wie zum Beispiel dem Vertauschen der beiden ''Button''-Elemente oder dem Einfügen eines weiteren ''Button''-Elements in der App.

Es wäre daher wünschenswert, das gemeinte Element über eine ihm charakteristische Eigenschaft wie einen Attributwert, zu adressieren. Für Android-Apps eignet sich hierfür häufig das Attribut "''resource-id''". Im Idealfall muss bei der Entwicklung der App darauf geachtet werden, dass jedes Element eine eindeutige Id erhält. Die ''resource-id'' hat den großen Vorteil, dass sie unabhängig vom Text des Elements oder der Spracheinstellung des Geräts ist. Für iOS-Apps kann entsprechend das Attribut "''name''" verwendet werden, wenn es von der App sinnvoll gesetzt wird. Der XPath-Standard erlaubt solche Auswahlbedingungen zu einem Element anzugeben. Angenommen, der ''Button'' mit der Markierung "''Aus''" hat die Eigenschaft ''resource-id'' mit dem Wert ''off'' und der ''Button'' mit der Markierung "''An''" hat als ''resource-id'' den Wert ''on'', dann kann man als eindeutigen Pfad für den "Aus"-''Button''

<blockquote>//android.widget.Button[@resource-id='off']</blockquote>

formulieren. Wie an dem Beispiel zu sehen werden solche Bedingungen wie ein Index in eckigen Klammern an den Elementtyp angehängt. Der Name eines Attributes wird mit einem "@" eingeleitet und der Wert mit einem "=" in Anführungszeichen angehängt. Ist der Attributwert global eindeutig, kann man den vorausgehenden Pfad sogar durch den globalen Platzhalter * ersetzen, der auf jedes Element passt. Das obige Beispiel mit dem GTIN-13-''Button'' war ein solcher Fall.

[[Datei:MobileTestingBaum2.png | frame | Abb. 3: Elementbaum einer fiktiven App mit Erweiterungen]]

Abb. 3 zeigt eine Erweiterung des Beispiels aus Abb. 2. Die App hat nun ein weiteres, nahezu identisches ''LinearLayout'' bekommen. Die ''Buttons'' sind in ihren Attributen jeweils ununterscheidbar. Deshalb funktioniert der vorige Ansatz nicht, einen eindeutigen Pfad nur mithilfe eines Attributwerts zu formulieren. Offensichtlich unterscheiden sich aber ihre benachbarten ''TextViews''. Es ist möglich die jeweilige ''TextView'' in den Pfad mit aufzunehmen, um einen ''Button'' dennoch eindeutig zu adressieren. Ein Pfad zum ''Button'' mit der Markierung "''An''" unterhalb der ''TextView'' mit der Markierung "''Druckschalter''" kann dabei wie folgt aussehen:

<blockquote>//android.widget.TextView[@resource-id='push']/../android.widget.Button[@resource-id='on']</blockquote>

Der erste Teil beschreibt den Pfad zu der ''TextView'' mit der Markierung "''Druckschalter''" und der ''resource-id'' mit dem Wert ''push''. Danach folgt ein Schrägstrich gefolgt von zwei Punkten. Die zwei Punkte sind eine spezielle Elementbezeichnung, die nicht ein Kindelement benennt, sondern zum Elternelement wechselt, in diesem Fall also das ''LinearLayout'', in dem die ''TextView'' eingebettet ist. Im Kontext dieses ''LinearLayout'' ist der restliche Pfad, nämlich der ''Button'' mit der ''resource-id'' mit dem Wert ''on'', eindeutig.

Der XPath-Standard bietet noch sehr viel mehr Ausdrucksmittel. Mit der hier knapp vorgestellten Auswahl ist es aber bereits möglich für die meisten praktischen Testfälle gute Pfade zu formulieren. Eine vollständige Einführung in XPath ginge über den Umfang dieser Einführung weit hinaus. Sie finden zahlreiche weiterführende Dokumentationen im Web und in Büchern.

Eine universelle Strategie zum Erstellen guter XPaths gibt es nicht, da sie von den Testanforderungen abhängt. In der Regel ist es sinnvoll, den XPath kurz und dennoch eindeutig zu halten. Häufig lassen sich Elemente über Eigenschaften identifizieren wie beispielsweise ihren Text. Will man aber gerade den Text eines Elements auslesen, kann dieser natürlich nicht im Pfad verwendet werden, da er vorher nicht bekannt ist. Ebenso wird der Text variieren, wenn die App mit verschiedenen Sprachen gestartet wird.

Jeder Baustein, der auf einem Element arbeitet, hat einen Eingangspin für den XPath. Im GUI-Browser finden Sie in der Mitte oben eine Liste von Bausteinen mit Aktionen, die Sie auf das ausgewählte Element anwenden können. Suchen Sie den Baustein ''Click'' (8) im Ordner Elements und wählen Sie ihn aus (Abb. 1). Er wird im rechten Teil unter "''Test''" eingefügt, der Pin für den XPath ist mit dem automatisch generierten Pfad des Elements vorbelegt (9). Sie können den Baustein hier auch ausführen. Die Ansicht wechselt dann auf "''Lauf''". Ändert sich durch die Aktion der Zustand Ihrer App, müssen Sie den Baum anschließend aktualisieren (10).

Wenn Sie in der unteren Liste eine Eigenschaft auswählen, wechselt die Anzeige der Bausteine zu "''Eigenschaften''", wo Sie die eigenschaftsbezogenen Bausteine finden. Wie bei den Aktionen können Sie auch hier einen Baustein auswählen, der dann rechts in Test mit dem Pfad des Elements und der ausgewählten Eigenschaft eingetragen wird, sodass Sie ihn direkt ausführen können.

== Weitere Locator-Strategien ==
Appium bietet neben XPath noch weitere Strategien zur Adressierung von Elementen an. Einige davon stehen Ihnen '''ab Version 20.1''' ebenfalls mit expecco zur Verfügung. Diese sind nicht ganz so mächtig wie XPath, dafür aber häufig schneller bei der Auflösung auf dem Gerät. Insbesondere bei der Verwendung mit iPhones, wo die Hierarchie bei jeder XPath-Auflösung erst aufgebaut werden muss, bieten alternative Strategien einen Vorteil für die Laufzeit.

XPath ist weiterhin der Standard, das heißt alle Locator ohne besondere Angabe werden als XPath interpretiert. Um eine der anderen Strategien zu verwenden, schreiben Sie diese mit einem Gleichzeichen vor den gewünschten Locator. Diese Technik können Sie sowohl an den Blöcken verwenden, als auch im GUI-Browser testen.

{|
|-
| style="vertical-align:top" | AccessibilityId || style="padding-bottom:0.5em" | Verwendet den Wert des Elements, der dazu dient, die App barrierefrei zu machen. Für iOS ist das das Attribut '''Accessibility-id''', für Android das Attribut '''content-descr'''. ''Beispiel: accessibilityId=Löschen''
|-
| style="vertical-align:top" | className || style="padding-bottom:0.5em" | Verwendet den Namen der Klasse des Elements. ''Beispiel: className=android.widget.FrameLayout''
|-
| style="vertical-align:top" | id || style="padding-bottom:0.5em" | Verwendet die Kennung des Elements. Für iOS ist das das Attribut '''name''', für Android das Attribut '''resource-id'''. ''Beispiel: id=android:id/text1''
|-
| style="vertical-align:top" | iOSClassChain1 || style="padding-bottom:0.5em" | Verwendet die Hierarchie der Elemente ähnlich wie bei XPath. Eine Erklärung zum Aufbau finden Sie [https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules hier]. ''Beispiel: iOSClassChain=XCUIElementTypeWindow/XCUIElementTypeButton[`label == "Ok"`]''
|-
| style="vertical-align:top; padding-right:1em" | iOSNsPredicateString1 || style="padding-bottom:0.5em" | Verwendet einfache Kriterien, wie Attribute, die auch kombiniert werden können. ''Beispiel: iOSNsPredicateString=type == 'XCUIElementTypeButton' AND name == 'Weiter'''
|-
| style="vertical-align:top" | name1 || style="padding-bottom:0.5em" | Verwendet den Namen des Elements. ''Beispiel: name=Bestätigen''
|-
|}

:1 ''nur für iOS''

Um eine direkte Beschleunigung mit iOS zu erzielen, ohne dass Sie Ihre bisherigen Pfade anpassen müssen, wandelt expecco zudem Pfade, die nur aus einem Element mit Klasse und name-Attribut bestehen, zur Laufzeit automatisch in einen entsprechenden Locator der Strategie iOSNsPredicateString um. Wenn Sie einen Pfad explizit als XPath markieren, wird diese Anpassung nicht vorgenommen.

=Probleme und Lösungen=
== Locator sind versionsabhängig oder variabel ==
Dann sollten Sie die Locator (xPath) entweder in einer Variablen halten oder ein Locator-Mapping in einem Screenplay Anhang definieren. Es ist auch möglich, lediglich Teile des Locators (z.B. Locator-Pfad eines Elternelements oder Attributwert) in einer Variable zu halten und im Freezevalue des Locator-Pins mit "''$(varName)''" einzufügen.

==Unsichtbare UI-Elemente==
Beachten Sie, dass im [[#Recorder|Recorder]] auch Elemente berücksichtigt werden, die Sie auf dem Bildschirm nicht sehen. Schalten Sie daher das Element-Highlighting an oder nutzen Sie die Follow-Mouse-Funktion und den Elementbaum im GUI-Browser, um festzustellen, ob das richtige Element verwendet wird. Es kann vorkommen, dass unsichtbare Elemente vor anderen Elementen liegen und diese verdecken, so dass die gewünschten Elemente im Recorder nicht ausgewählt werden können. Lesen Sie dazu den Abschnitt [[#Elemente_verbergen|Elemente verbergen]].

==iOS: Kabel nicht zertifiziert==
In manchen Fällen erscheint beim Verbinden eines iOS-Geräts über USB der Hinweis, das verwendete Kabel sei nicht zertifiziert. In diesem Fall hilft es nur, das entsprechende Kabel auszutauschen.
==iOS: Alerts beim Verbindungsaufbau==
Stellen Sie sicher, dass beim Verbindungsaufbau mit einem iOS-Gerät keine Alerts geöffnet sind. Der Aufbau schlägt sonst fehl, da die App nicht in den Vordergrund kommen kann. Siehe auch [[#iOS-Ger.C3.A4t_und_App_vorbereiten|iOS-Gerät und App vorbereiten]].

==iOS: .ipa installieren nicht möglich==
Beachten Sie, dass auf iOS-Simulatoren keine ''.ipa''-Dateien sondern nur ''.app''-Dateien installiert werden können.
==Android: Gerät nicht im Verbindungsdialog==
Wenn ein über USB angeschlossenes Android-Gerät nicht im Verbindungsdialog auftaucht, versuchen Sie, den USB-Verbindungstyp zu ändern. In der Regel sollten MTP oder PTP funktionieren. Prüfen Sie nochmal, ob "USB Debugging" in den Entwicklereinstellungen des Geräts aktiviert ist (diese Einstellungen sind bei manchen Geräten zunächst unsichtbar, und müssen durch einen Trick zugänglich gemacht werden). Siehe auch [[#Android-Ger.C3.A4t_vorbereiten|Android-Gerät vorbereiten]].

==Android: Abgeschnittene Elemente unten==
Bei Android-Geräten, die die Steuerungsleiste bzw. Softkeys automatisch ein- und ausblenden, kann es vorkommen, dass der Recorder im unteren Bereich Elemente abschneidet, die durch die Softkeys verdeckt würden, auch wenn sie zu diesem Zeitpunkt gar nicht angezeigt werden. In diesem Fall hift es, die Softkeys so einzustellen, dass sie in einer permanenten Leiste angezeigt werden.

Bei neueren Android-Versionen gibt es eine solche Einstellung in der Regel nicht. Auch wenn die Steuerelemente permanent eingeblendet sind, liegen sie auf keiner extra Leiste, sondern vor dem Inhalt der App. Es gibt dann im unteren Teil einen Bereich, der nicht bedient werden kann, weil er nicht zum aktiven Bereich der App gezählt wird, weshalb die Elemente von Appium abgeschnitten werden. Dieser Bereich kann auch größer sein als von den Steuerungselementen beansprucht. Bekannt ist dies für Samsung-Geräte mit Android 11. Da die Information über die Größe des App-Bereichs bereits auf Android-Ebene so geliefert wird, können wir hierfür keine Lösung anbieten, sondern können nur hoffen, dass das Problem vom Hersteller behoben wird. Sie können versuchen, ob Sie mit der Einstellung von Gestensteuerung bessere Ergebnisse bekommen, allerdings gibt es hier das gleiche Problem.

== Android: Test hängt beim Suchen eines Elements==
Der Baustein ''Find Element by XPath'' und alle Element-Bausteine warten bis ein Element zum angegebenen Pfad auftaucht. Den Timeout dafür kann man entweder am Baustein direkt oder in den Umgebungsvariablen ändern. Wenn das Element aber bereits da sein sollte und es dennoch sehr lange dauert, bis der Test weitergeht, kann das am UIAutomator/UIAutomator2 liegen. Dieser wartet, bis die App in den Idle-Zustand geht, bevor er überhaupt nach Elementen sucht. Dies kann länger dauern, wenn die App z.B. im Hintergrund noch Animationen abspielt oder andere Aktionen ausführt. Auch das Holen des Page-Sources z.B. beim Aktualisieren im GUI-Browser oder im Recorder kann dadurch länger dauern. Standardmäßig gibt es hierfür einen Timeout von 10 Sekunden, nach dem nicht weiter auf den Idle-Zustand gewartet wird. Dieser Timeout lässt sich durch eine Einstellung in Appium anpassen (waitForIdleTimeout). Falls Sie einen anderen Wert für diesen Timeout setzen möchten, ist dies ab expecco 21.2 möglich, indem Sie vor dem Test den Smalltalk-Code <code>AppiumTestRunner::TestRunConnection waitForIdleTimeout:2000</code> ausführen. Der Timeout wird in Millisekunden angegeben, das Beispiel setzt ihn also auf 2 Sekunden.

==Android: Aktualisieren des Trees oder Wechseln zum Webview-Kontext braucht zu lange==
Speziell mit älteren Geräten kann es vorkommen, dass neuere Chromedriver nicht initialisiert werden können. Das führt dann dazu, dass nicht in den Webview-Kontext gewechselt werden kann. Dies wird von Appium allerdings nur über einen Timeout festgestellt, der standardmäßig bei 4 Minuten liegt. Da expecco auch beim Aufbauen des Trees im GUI-Browser versucht in den Webview-Kontext zu wechseln, kann das zu sehr langen Ladezeiten führen. Da es in Appium keine Möglichkeit gibt, diesen Timeout herunter zu setzen, haben wir die Version, die wir im MobileTestingSupplement bereitstellen, um eine entsprechende Capability erweitert. Ab der Version 1.13.1.0 des [[#Windows|MobileTestingSupplements]] kann mit ''chromedriverStartTimeout'' der Timeout in Millisekunden gesetzt werden. Der Wechsel funktioniert dadurch zwar trotzdem nicht, aber expecco braucht dann nicht mehr so lange beim Aktualisieren des Trees und der Baustein zum Wechseln des Kontextes schlägt schneller fehl. Der Verbindungsdialog fügt diese Capability ab expecco 22.1 automatisch hinzu.

==Keine Aktion bei Klick==
Der Baustein zum Klicken auf ein Element ist erfolgreich, aber auf dem Gerät wurde keine Aktion ausgeführt.
:Dies kann vorkommen, wenn das Element von einem anderen Element verdeckt ist und ein Klick auf das Element deshalb nicht möglich ist. In diesem Fall wird von Appium kein Fehler geworfen, sondern es passiert einfach nichts. Wenn Sie dennoch einen Klick an der Position des Elements machen möchten, auch wenn es verdeckt ist, benutzen Sie stattdessen den Baustein ''Tap'' und übergeben Sie diesem die Position des Elements (''Get Location''). Wenn Sie stattdessen vor einem Klick prüfen möchten, ob das Element zu diesem Zeitpunkt verdeckt ist, versuchen Sie, ob Ihnen die Eigenschaften ''Is Displayed'' oder ''Is Enabled'' weiterhelfen.

==Kein Update nach Aktion==
Über den Recorder wurde eine Aktion ausgeführt, für die auch ein Baustein aufgezeichnet wurde, der Recorder zeigt aber immer noch das alte Bild.
:Der Recorder zeigt kein Livebild des Geräts, sondern immer nur eine Momentaufnahme. Nachdem eine Aktion ausgeführt wurde, aktualisiert sich der Recorder automatisch. Es kann aber vorkommen, dass das Bild schon aktualisiert wurde, bevor die Auswirkungen der Aktion auf dem Gerät vollständig abgeschlossen sind. In diesem Fall sollten Sie den Recorder von Hand aktualisieren über das Symbol mit den blauen Pfeilen. Ab expecco 20.2 können Sie für diesen Fall auch automatisches Aktualisieren einstellen. Siehe auch Beschreibung zum [[#Recorder|Recorder]].

=="clickable" Attribut falsch==
Ein Element hat im "''clickable''" Attribut/Property den Wert "''false''", ist aber dennoch anklickbar.
:Das "''clickable''" Attribute muss explizit vom App-Programmierer gesetzt werden, und hat tatsächlich keine Relevanz für das tatsächliche Verhalten der App. Sie sollten dieses Attribut i.A. in Ihren Tests nicht beachten. Leider existieren viele Apps, bei denen der Programmierer hier "lazy" war.

==Verbindungsaufbau schlägt fehl==
Schlägt der Verbindungsaufbau mit dem Appium-Server fehl, erhalten Sie in expecco eine Fehlermeldung ähnlicher der unten abgebildeten.

[[Datei:MobileTestingVerbindungsfehler.png]]

Hier sehen Sie die Art des aufgetretenen Fehlers. Klicken Sie auf "''Details''" um nähere Informationen zu erhalten. Mögliche Fehler sind:
*''org.openqa.selenium.remote.UnreachableBrowserException''
:Der angegebene Server läuft nicht oder ist nicht erreichbar. Überprüfen Sie die Serveradresse.
*''org.openqa.selenium.WebDriverException''
:Lesen Sie in den Details in der ersten Zeile die Meldung hinter ''Original Error'':
:*''Unknown device or simulator UDID''
::Entweder ist das Gerät nicht richtig angeschlossen oder die udid stimmt nicht.
:*''Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65''
::Dieser Fehler kann verschiedene Ursachen haben. Entweder konnte tatsächlich der WebDriverAgent nicht gebaut werden, weil die Signierungseinstellungen falsch sind oder das passende Provisioning Profile fehlt. Lesen Sie dazu den Abschnitt zur [[#Signierung|Signierung]]. Es kann auch sein, dass der WebDriverAgent auf dem Gerät nicht gestartet werden kann, weil sich beispielsweise ein Alert im Vordergrund befindet oder Sie dem Entwickler nicht vertraut haben.
:*''Could not install app: 'Command 'ios-deploy [...] exited with code 253'''
::Die angegebene App kann nicht auf dem iOS-Gerät installiert werden, weil es nicht im Provisioning Profile der App eingetragen ist.
:*''Bad app: [...] App paths need to be absolute, or relative to the appium server install dir, or a URL to compressed file, or a special app name.'''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die Datei unter dem angegebenen Pfad auf dem Mac befindet.
:*''packageAndLaunchActivityFromManifest failed.''
::Die angegebene ''apk''-Datei ist vermutlich kaputt.
:*''Could not find app apk at [...]''
::Der Pfad zur App ist falsch. Stellen Sie sicher, dass sich die ''apk''-Datei am angegebenen Pfad befindet.

Falls der Fehler nicht durch eine der oben gelisteten Ursachen bedingt ist, kann es sein, dass die auf dem Gerät befindlichen Automation-Anwendungen nicht mehr richtig funktionieren. Hier hilft es, diese vom Mobilgerät zu deinstallieren. Beim nächsten Verbindungsaufbau werden sie dann automatisch neu installiert.

*Für iOS-Geräte ist das der WebDriverAgent, den Sie einfach vom Home-Screen deinstallieren können. Dies behebt in der Regel Probleme durch den Wechsel des verwendeten Macs oder der Xcode-Version.

*Für Android-Geräte ist es der UIAutomator2; hier tritt auf einigen Geräten sporadisch ein Problem auf, die Ursache dafür ist uns z.Z. noch nicht bekannt. Zur Deinstallation navigieren Sie auf dem Gerät zu "''Einstellungen''" > "''Anwendungen''"* und suchen in der Liste nach folgenden Einträgen:
Appium Settings
io.appium.uiautomator2.server
io.appium.uiautomator2.server.test
:Klicken Sie auf die jeweilige Anwendung und dann auf "''Deinstallieren''".
*''Der entsprechende Eintrag heißt auf manchen Geräten möglicherweise etwas anders.''

Falls dies nicht hilft, kann eventuell die Ausgabe des Appium-Servers weiterhelfen. Für einen von expecco gestarteten Server finden Sie das Log in der Liste der [[#Laufende_Appium-Server|laufenden Appium-Server]].

==Ich habe keinen Mac==
Vielleicht hilft Ihnen diese Webseite weiter: [https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10 https://www.howtogeek.com/289594/how-to-install-macos-sierra-in-virtualbox-on-windows-10]