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

Expecco API/en

2026-08-18T10:30:31Z

Matilk: /* Interaction with Expecco (Python) */

== How to Program ==

You can write elementary actions (actions with program code) in many languages. Actions can be executed as:
==== Builtin Languages ====
Smalltalk and Javascript these are executed directly inside expecco (i.e. expecco contains a compiler for those languages); when defined, they are compiled to a bytecode intermediate language and compiled to machine code when first executed (JIT - "just in time" compilation). The compilation to bytecode happens when the code is "accepted" or loaded from the ".ets" file. And jitted to machine code when first executed. Calls are fast and pin values are passed in and out by reference. These are executed with the lowest overhead.

==== Bridged Languages ====
Python, Groova (Java), Ruby, NodeJS (Javascript), C, C#, Scheme, Octave (Matlab) the are loaded into a running language interpreter which remains running between actions. Frameworks and packages can be loaded/imported, allowing for any existing code to be executed. Execution incurs a larger overhead compared to internally executed actions, because pin values have to be interchanged via interprocess communication mechanisms.

==== Scripted Languages ====
Shell, Batch, Powershell, Python, Ruby, Octave/Matlab, TCL, etc. Basically any other language is even possible by calling it via a shell or batch script. The code is stored as a script file on which an interpreter is started. For every such script action, the interpreter is started anew. Existing scripts can be called with minimal porting effort (and even automatically imported). These incur a higher call overhead.

This document describes builtin and bridged language actions. Scripted actions are described [[ElementaryBlock_Element/en#Script_Action_Blocks | elsewhere]].

=== Builtin Smalltalk and Javascript ===
Before you start programming in the builtin Smalltalk or builtin Javascript, please read the [[How_to_Program/en | "How to Program"]] document, which describes how program code is handled in expecco.
Unless you are familiar with the dynamics of a Smalltalk development environment, some of it may be unknown to you, and you will have more fun and be more productive, if you know the power of the tools. For the best development experience, take a look at the debugger, workspace (notepad) and data inspectors.

The rest of this document describes the syntax and semantics of the elementary action languages. For tool usage, please read the [[How_to_Program/en | HowTo]] document.

== expecco API ==

The expecco API provides functions and access to the underlying class library for the use in [[Elementary Block|elementary blocks]] written in Smalltalk and JavaScript (i.e. for code which is executed inside expecco itself). This API is not available for elementary blocks written in other languages which are executed by external script engines (Shell, Batch, Python, Node.js etc.) or inside a different Java or CLR Virtual Machine (Groovy, VBScript, IronPython). However, a subset of the functions are supported as RPC (remote procedure calls) in bridged elementary actions.

For a short introduction to the Smalltalk programming language,
please read the [http://live.exept.de/doc/online/english/getstart/tut_2.html Smalltalk tutorial in the Smalltalk/X online manual].
For a full book on learning Smalltalk, read [http://live.exept.de/doc/books/JoyOfST/JoyOfST.pdf "The joy of Smalltalk, An introduction to Smalltalk" by Ivan Tomek].

The [[#Groovy Elementary Blocks|API for Groovy elementary blocks]] is different and described below.
 The API for bridged Node.js actions is described [[#Node.js_.28Bridged.29_Elementary_Blocks|here]].
 The API for bridged Python and Jython actions is described [[#Bridged Python Elementary Blocks|here]].
 The API for bridged Ruby actions is described [[#Bridged Ruby Elementary Blocks|here]].
 The API for bridged C actions is described [[#Bridged C Elementary Blocks|here]].

==JavaScript and Smalltalk Elementary Blocks ==

The expecco JavaScript and the Smalltalk API consist of the same functions - both call into the underlying [http://www.smalltalk-x.de Smalltalk/X] system, for which extensive documentation is available as
[http://live.exept.de/doc/online/english/TOP.html Online Documentation] and
as [http://live.exept.de/ClassDoc Class Reference].

The Smalltalk/X language and class library are [http://wiki.squeak.org/squeak/uploads/172/standard_v1_9-indexed.pdf ANSI compatible]; therefore the official ANSI documents, Smalltalk literature and tutorials are also valuable sources of information (for example, the online tutorials you may find in youtube).

:- If you wonder "why Smalltalk?", you should know that [https://insights.stackoverflow.com/survey/2017#most-loved-dreaded-and-wanted Smalltalk ranked nr. 2 in a 2017 survey of "most loved languages"] - admittedly, this ranking may be subjective (in that Smalltalk programmers might be more loyal), but it should at least raise your eyebrows.
:- It is not among the most used languages - but that decision is usually made by people who do not even know Smalltalk or who think that language does not matter.
:- If you think it is outdated, be reminded that Smalltalk has the most consistent object model and reflection facilities of all OO languages, and that modern clones like Ruby and Python only provide a subset of Smalltalk's facilities. If you don't know it, don't judge it.
:- The underlying virtual machine (VM) is feature rich and provides many mechanisms which are not possible in most 'modern' languages. For example, in most (if not all) of the current languages it is not possible to interrupt a thread which blocks in a system call (eg. in a read). In none of them, are exceptions proceedable. In none of them can you interrupt other threads in any situation (again: especially not if it is inside a blocking read).
:- The set of integrated tools is massive in Smalltalk: full access to classes, threads, semaphores, any object's internals are all provided by graphical tools which can be opened by double clicks or via menus.

Expecco's JavaScript is implemented by compiling JavaScript syntax to the underlying Smalltalk bytecode. It is not fully compatible with a "real" JavaScript: it is class based, and the underlying object model and class library are actually the Smalltalk/X object model and class library. Thus, expecco's JavaScript can be seen as "a Smalltalk with JavaScript syntax".

Please be not confused by two JavaScript-based elementary actions: the builtin JavaScript described here is executed within expecco itself whereas Node-actions are executed in a separate Node.js virtual machine. These Node actions are "real JavaScript" and are described in a separate [[#Node.js_.28Bridged.29_Elementary_Blocks |chapter below]].

===Smalltalk / JavaScript Short Syntax Overview===
Expecco's builtin JavaScript and Smalltalk only differ in their syntax - semantically they are very similar:
{| class="wikitable"
! JavaScript
! Smalltalk
!
|-
|style="width: 15em"|this
|style="width: 15em"|self
| the current activity (inside an elementary action)
|-
|this.functionName()
|self functionName
| a call without arguments
|-
|this.''functionName''(''arg'')
|self ''functionName'':''arg''
| a call with one argument
|-
|this.''namePart1_part2''(''arg1'',''arg2'')
|self ''namePart1'':''arg1'' ''part2'':''arg2''
| two arguments Notice that in Smalltalk, the arguments are ''sliced'' into the name parts, and that the concatenation of the parts is the actual name (incl. the colons). Thus, in "<code>x at:5 put:10</code>" the name of the called method is "at:put:" and it gets two arguments: 5 and 10. Whereas "<code>(x at:5) put:10</code>" would first send an "at:" message, then send a"put:" message to the object returned from "at:". In JavaScript, ":" is not a valid character in a function name, and a translation mechanism is applied which replaces ":" by underline, and drops the final colon.
|-
| ''functionName''(...)
| self ''functionName''...
| implicit ''this'' receiver in JS explicit in Smalltalk
|-
| ''accessor''
| self ''accessor''
| slot access - implicit this receiver in JS explicit in Smalltalk
|-
| ''stat1'' ; ''stat2'' ;
| ''stat1'' . ''stat2''
| statement terminator / separator in ST: to '''separate''' statements in JS: to '''terminate''' a statement. In Smalltalk, the last period "." inside a method or block can be and often is omitted.
|-
| if (''cond'') {     ''ifStats'' } else {     ''elseStats'' }
| ''cond'' ifTrue:[     ''ifStats'' ] ifFalse:[     ''elseStats'' ]
| conditional execution. Notice the square brackets in Smalltalk
|-
| while (''cond'') {     ''stats'' }
| [ ''cond'' ] whileTrue:[     ''stats'' ]
| while-loop. Notice the brackets around the condition in Smalltalk
|-
| for (i=''start''; i<=''end''; i++) {     ''stats using i'' }
| ''start'' to:''end'' do:[:i |     ''stats using i'' ]
| counting-loop. Seldom used in Smalltalk
|-
| foreach (''el'' in ''collection'') {     ''stats using el'' }
| ''collection'' do:[:el |     ''stats using el'' ]
| loop over collection elements. Very often used in Smalltalk
|-
| function () { ''stats'' }
| [ ''stats'' ]
| an anonymous (inner) function (called "block" in ST). JS: return value via explicit return ST: return value is last expression's value
|-
| function (''a1'', ''a2'',...) { ''stats'' }
| [:''a1'' :''a2'' ...| ''stats'' ]
| in ST: blocks are references to anonymous function
|-
| var ''v1'', ''v2'', ... ;
| | ''v1'' ''v2'' ... |
| local variables inside a function (or block). Semantically, these are "let" variables (i.e. only seen in the current scope)
|-
| return ''expr'';
| ^ ''expr''
| return a value. In ST: a return from within a block returns the enclosing '''top-level''' method In JS: a return returns from the '''inner''' function
|-
|
| '...'
| String constant without c-escapes
|-
| "..." or '...'
| c'...'
| String constant with c-escapes (\n, \t, etc.)
|-
| `...${ expr1 } .. ${ expr2 } ...`
| e'..{ expr1 } .. { expr2 } ...'
| String with sliced in expressions (exprs will be converted to string). Also known as ''TemplateStrings''.
|-
| 0xXXX, 0bXXX, 0XXX
| 0xXXX, 0bXXX, 0oXXX or 16rXXX, 2rXXX, 8rXXX (notice: 0177 is a decimal in Smalltalk, but octal in JS)
| Integer constants (hex, binary, octal)
|-
|
| #(el1 ... el2)
| literal (constant) array constructed at compile time. Notice that elements are separated by spaces
|-
| [ex1 , ex2 , ... , exN]
| {ex1 . ex2 . ... . exN}
| literal (constant) array constructed at execution time. Notice that in Smalltalk, expressions are separated by periods (must be, because "," is an operator to concatenate collections)
|-
| /* ... */
| " ... "
| comment
|-
| // ...
| "/ ...
| end of line comment
|-
|
| "<<TOKEN ... TOKEN
| token comment
|}

==== Smalltalk Operator Precedence ====
Smalltalk beginners may be irritated by the missing binary operator precedence rules: in Smalltalk, all operators have the same precedence and are evaluated left to right. Thus if you write:
a + b * 5
the JavaScript semantic is:
a + (b * 5)
whereas in Smalltalk, it is evaluated as:
(a + b) * 5
(i.e. left to right).

Therefore, as a guideline (and actually a good convention), all Smalltalk binary expressions with more than one operator should be parenthesized to make the intention clear. It make clear that it is intended, that should be done even if the left-to-right order matches the mathematical precedences.

==== Smalltalk Operators ====
Another uncommon feature of the Smalltalk language is that there are only 6 keywords in the language
("<code>self</code>", "<code>super</code>", "<code>true</code>", "<code>false</code>", "<code>nil</code>" and "<code>thisContext</code>").
 Every other word is either the name of a variable or the name of a message to be sent to an object (aka a "''virtual function call''" or "''method invocation''").

Every sequence of special characters (except "<code>:</code>" (colon), "<code>.</code>" (period), "<code>(</code>" (left), "<code>)</code>" (right parenthesis), "<code>[</code>" (left), "<code>]</code>" (right bracket), <code>{</code>" (left),<code>}</code>" (right brace), "<code>:=</code>" (assign), "<code>^</code>" (return) and "<code>;</code>" (semicolon) ) is interpreted as operator (or in other words: as the name of a message/virtual function call).

Thus, the sequences "<code>-></code>", "<code>=</code>", "<code>=></code>", "<code><-</code>" and especially the comma ("<code>,</code>") are operators which are treated like "<code>+</code>", "<code>-</code>" etc.

Finally, message sends ("''function calls''") with arguments are always written with keyword arguments. I.e. the arguments are prefixed by a keyword (which is an identifier with a colon). Smalltalk does not allow positional arguments in a message send.

==== Calling Functions and Invoking Methods (aka "Sending Messages") ====
All functions are actually implemented in Smalltalk and follow the standard Smalltalk naming conventions. The same function names are used for JavaScript. As seen above, this scheme works well for functions without or with a single argument, but requires a name translation for functions with more than one argument. This translation is done by the JavaScript compiler by replacing every colon (:) of the Smalltalk name by an underline (_) character, except for the last colon if there are more than one. Thus for example, the Smalltalk name "<code>at:put:</code>" will be named "<code>at_put</code>" in JavaScript.

In JavaScript, a function-name alone (i.e. without explicit receiver) is translated into a self-send; thus "<code>this.foo()</code>" and "<code>foo()</code>" are equivalent.



For example, the JavaScript call:
this.'''environmentAt'''("foo")
is written in Smalltalk as:
self '''environmentAt:''''foo'

and, to demonstrate the multi-argument translation rule, the Smalltalk code:
self '''environmentAt:''''foo' '''put:'''1234
is written in JavaScript as:
this.'''environmentAt_put'''("foo", 1234)
or (because of the implicit receiver being "this"), alternatively:
'''environmentAt_put'''("foo", 1234)

=== Syntax Summary ===
For a formal specification of the JavaScript and Smalltalk languages, see the appendixes below.
The following gives a rough overview over the most common syntactic constructs.

{| class="wikitable"
! JavaScript
! Smalltalk
! Notes
|-
|style="width: 10em"| this
|style="width: 10em"| self
| the current activity
|-
| null
| nil
| a null reference (UndefinedObject)
|-
| ;
| .
| statement terminator/separator In JavaScript it is a terminator, meaning that every statement (except brace-blocks) must be terminated by a semicolon. In Smalltalk, it is a separator, meaning that the last statement in a block or method does not need one.
|-
| "..."
| '...'
| a String constant (JavaScript allows single quotes too); no C-escapes in Smalltalk
|-
|
| c'...'
| a Smalltalk String constant with c-escapes
|-
|
| e'..{ expr } ..'
| a Smalltalk String with embedded expressions (sliced-in)
|-
|
| #'...'
| a Symbol constant (not available in JavaScript; use "xxx".asSymbol() in JS)
|-
|
| #...
| also a Symbol constant (not available in JavaScript; use "xxx".asSymbol() in JS)
|-
| [ el1 , el2 , ... ]
| #( el1 el2 ... )
| an Array constant (elements must be constant literals) Notice the separating comma in JS, but space-separated elements in Smalltalk. In Smalltalk, the array is created at compile time (i.e. runtime cost is zero); the array is immutable, whereas in JS it is created mutable at runtime
|-
| [ expr1 , expr2 , ... ]
| { expr1 . expr2 . ... }
| a computed Array (elements are expressions) notice the expression terminators in ST (periods), and that "," (comma) is an operator in ST. The array is created at runtime; the array is mutable
|-
|
| #[ el1 el2 ... ]
| an immutable ByteArray constant (not available in JavaScript)
|-
| 1234
| 1234
| an Integer constant (arbitrary precision)
|-
| 0x1234
| 0x1234 or 16r1234
| a hexadecimal Integer constant (radix is 16) (arbitrary precision)
|-
| 0b10001010
| 0b10001010 or 2r10001010
| a binary Integer constant (radix is 2) (arbitrary precision)
|-
| 0177
| 8r177
| an octal Integer constant (radix is 8) (arbitrary precision)
|-
|
| 3r10001010
| a ternary Integer constant (radix is 3); not available in JavaScript
|-
|
| <N>rxxxx
| an N-ary Integer constant (radix is N); not available in JavaScript
|-
|
| ( num / den )
| a Fraction constant (not available in JavaScript); both numerator and denominator must be integers
|-
| 1.234 1e5
| 1.234 1e5
| Floating Point constants (double precision)
|-
| v = expression
| v := expression
| assignment to a variable
|-
| expr1 == expr2
| expr1 = expr2
| compare for equal value
|-
| expr1 === expr2
| expr1 == expr2
| compare for identity be careful: 1.0 (the float) is NOT identical to 1 (the integer) However, they are equal in value.
|-
| rcvr.f ()
| rcvr f
| function call (always a "virtual function call")
|-
| rcvr.f (arg)
| rcvr f: arg
| with 1 arg
|-
| rcvr.a_b (arg1, arg2)
| rcvr a: arg1 b: arg2
| with args notice the different names of the function "a_b" vs."a:b:"
|-
| return;
| ^ self
| without return value ST: from enclosing method; JS: from current function
|-
| return expr;
| ^ expr
| with return value ST: from enclosing method; JS: from current function
|-
| return from execute;
| ^ self
| return from execute activity from within an inner function
|-
| ! expr
| expr not
|
|-
| e1 && e2
| (e1 and:[ e2 ])
| non evaluating and (e2 is not evaluated if e1 is false)
|-
| e1 || e2
| (e1 or:[ e2 ])
| non evaluating or (e2 is not evaluated if e1 is true)
|-
|
| pin <- value
| only for output pins: writes value to the pin (same as "pin value(val)")
|}

=== Syntactic Sugar ===

Some syntactic constructs of the JavaScript language are implemented as library functions in Smalltalk. Among others, most noteworthy are conditional execution (if-the-else) and loops.

Non-Smalltalkers should be aware that in Smalltalk all control structures are implemented as library functions (i.e. method invocations) to corresponding receiver objects. They get a block (=closure or anonymous function) as argument, which is then possibly evaluated. The Smalltalk block syntax "<code>[...]</code>" makes this extremely convenient and easy to use.

It is the responsibility of the Smalltalk compiler and runtime system, to care for optimized execution of such code (typically by inlining the code). However, it is still possible to put a block into a variable, to pass it as argument, or to return it as value from a method or block. Thus, in Smalltalk, variables or computed blocks may also be used as arguments to messages like "<code>ifTrue:</code>", "<code>whileTrue:</code>", "<code>do:</code>" etc.

 The JavaScript syntax for control structures is mapped to corresponding Smalltalk library functions as follows:
{| class="wikitable"
! JavaScript
! Smalltalk
! Notes
|
|-
|style="width: 15em"|if (''expr'') { ... }
|style="width: 15em"| (''expr'') ifTrue:[ ... ]
| Notice the square brackets
|-
|if (! ''expr'') { ... }
| (''expr'') ifFalse:[ ... ]
|
|-
| if (''expr'') { ... } else { ... }
| (''expr'') ifTrue:[ ... ] ifFalse:[ ... ]
|
|-
| if (!''expr'') { .. } else { ... }
| (''expr'') ifFalse:[ ... ] ifTrue:[ ... ]
|
|-
| while (''expr'') { .. }
| [''expr''] whileTrue:[ ... ]
| Notice the square brackets around the condition
|-
| for (''expr1'';''expr2'';''expr3'') { .. }
| ''expr1''. [''expr2''] whileTrue:[ ... . ''expr3'' ]
|
|-
| for (var i=''start''; i<=''stop''; i++) { .. }
| ''start'' to:''stop'' do:[:i | ... ]
|
|-
| for (var i=''start''; i<=''stop''; i+=''incr'') { .. }
| ''start'' to:''stop'' by:''incr'' do:[:i | ... ]
|
|-
| try { .. } finally { ... }
| [ ... ] ensure:[ ... ]
|
|-
| try { .. } catch(e) { ... }
| [ ... ] on:Error do:[:e | ... ]
|
|-
| try { .. } catch(e) { ... } finally { ... }
| [ ... ] on:Error do:[:e | ... ] ensure:[ ... ]
|
|-
| ''var''++
| ''var'' := ''var'' + 1
|
|-
| ''var''--
| ''var'' := ''var'' - 1
|
|-
| ''arr''[ ''idx'' ]
| ''arr'' at:''idx'' ''arr''[ ''idx'' ]
| Array and Dictionary indexed fetch Notice that real JavaScript uses 0-based indexing, whereas Smalltalk and expecco JavaScript is 1-based. Smalltalk/X also allows the bracket notation for indexed access.
|-
| ''arr''[ ''idx'' ] = ''expr''
| ''arr'' at:''idx'' put:''expr'' ''arr''[ ''idx'' ] := ''expr''
| Array and Dictionary indexed store Smalltalk/X also allows the bracket notation for indexed access.
|}

=== Operators ===
{| Border
! JavaScript
! Smalltalk
! Notes
|-
| %
| \\ %
| modulu operator
|-
| <<
| leftShift:
| left-shift negative shift count is right-shift
|-
| >>
| rightShift:
| right-shift negative shift count is left-shift
|-
|
| bitShift:
| left or right shift; negative shift count is right-shift positive is left shift (not available in JavaScript)
|}

More details are in the [[Smalltalk Syntax Cheat Sheet]].

=== Array Indexing ===

A big potential pitfall is the different indexing base used in Smalltalk vs. (standard) JavaScript: in Smalltalk, array indices start at 1 and end at the array's size. In (standard) JavaScript, indices start at 0 and end at the array's size minus 1.

This also affects some character- and substring search functions, which return 0 (zero) in Smalltalk, whereas some of the standard JavaScript functions return -1 if nothing is found.

The following functions expect or return 0-based indices if used in JavaScript:
* ''collection''.<code>'''indexOf:'''</code>(''element'') attention: there exists a corresponding Smalltalk method, which returns a 1-based index
* ''collection''.<code>'''lastIndexOf:'''</code>(''element'') attention: there exists a corresponding Smalltalk method, which returns a 1-based index

* ''collection''.<code>'''indexOf:'''</code>(''element'', ''startIndex'') the corresponding Smalltalk method "<code>indexOf:</code>''element'' <code>startingAt:</code>''startIndex''" uses 1-based indices
* ''collection''.<code>'''lastIndexOf:'''</code>(''element'', ''startIndex'') ditto

We admit that this is a little confusing at times, but there is no easy solution to this: and we decided to neither change the Smalltalk nor the JavaScript scripting languages inside expecco.

To make your intentions explicit, you can use variants of the "<code>indexOf"/"lastIndexOf</code>" functions which make these implicit differences more explicit: "<code>indexOf0()</code>" / "<code>lastIndexOf0()</code>" and "<code>indexOf1()</code>" / "<code>lastIndexOf1()</code>" are available for both languages.

Shame on us: 
the above array indexing behavior was changed for <code>indexOf:</code> between 2.7 and 2.8 (due to a missing translation, the 2.7 versions used 1-based indices in both languages).
This leads to a problem, if you run any old 2.7 suite in newer expecco versions without reimporting the StandardLibrary or if you used those functions in your own elementary code.
To avoid a need to touch those old suites, we have added a backward-bug-compatibility mode, which is described in a separate note of the release notes.

=== Inner Functions ===
==== Inner Functions in JavaScript ====

It is possible to create functions within the elementary block's code. This example shows how to do so:
execute() {
...
function f(arg1, arg2) {
return(arg1 + arg2);
}
...
}
An inner function "f" is created with two arguments ("arg1" and "arg2"), which returns the sum of both. The function is called like this:
f(3,5)
Inner functions can be used for example to filter specific elements from collections, as in:
function isEven(n) { return n.even(); }

var numbers = [1,2,3,4,5,6,7];
var evenNumbers = numbers.select( isEven );

Inner functions are '''first class objects''': they can be stored in variables, collections, passed as argument or returned from functions. They can even be passed to other blocks via input- and output pins or via environment variables. Functions can be anonymous; the above example could also be written as:
execute() {
var f;
...
f = function (arg1, arg2) {
return(arg1 + arg2);
}
...
}
(notice the missing function name after the "function" keyword).

Notice, that there is a difference in the behavior of the return statement between JavaScript inner functions and Smalltalk blocks:
a JavaScript "return" statement inside an inner function returns from that inner function only, whereas a return in Smalltalk always returns from the outer-most method.

To return from the outermost function in JavaScript, use the "<CODE>return from <''fnName''></CODE>" statement form.

In expecco, where the outermost function is always named "''execute''", write:
execute() {
...
function myFunction() {
...
return from execute;
}
...
}
(notice that the execute function is not supposed to return a value)

===== Lambda Expressions in JavaScript =====

JavaScript functions can also be written in a slightly shorter lambda notation as:
(arg1, ... argN) => { statement; ... return expression; }
or (with a single argument) as:
arg => { statement; ... return expression; }
or (without arguments) as:
() => { statement; ... return expression; }
and results in a function object comparable to:
function (arg1, ... argN) { statement; ... return expression; }

The function's body may also be a single expression (without braces), as:
arg => expression
For example:
aCollection.map( el => el ** 2 )
returns a collection of squared numbers,
the same as the corresponding Smalltalk code:
aCollection map:[:el | el ** 2 ]
This is plain "syntactic sugar" - it does not give any new semantic functionality, but makes the code shorter and possibly easier to read.

==== Inner Functions in Smalltalk (Blocks) ====

In Smalltalk, inner functions are called "''block''", and are defined as:
f := [:arg1 :arg2 | arg1 + arg2 ].
This block can be called by sending at a "<code>value:value:</code>" message (i.e. one "<code>value:</code>" for each argument) (1):
f value:3 value:5
or by passing an array of argument values with "<code>valueWithArguments:</code>" as in:
args := #(3 5). "/ an array constant
f valueWithArguments:args
or:
args := { 3 . 5 }. "/ a computed array
f valueWithArguments:args

The returned value is the value of the last expression inside the block. Thus, blocks can contain multiple expressions separated by a period:
f := [:arg1 :arg2 |
Transcript showCR: e'my first arg is: {arg1}'.
Transcript showCR: e'my second arg is: {arg2}'.
arg1 + arg2 "/ the block's return value
].
This is in contrast to a JavaScript inner function, where an explicit "return" statement is needed. The return value of JavaScript inner function without an explicit return will be void.
Therefore, the above inner function in JavaScript has to have a return:
f = function(arg1, arg2) {
Transcript.showCR('my first arg is: '+arg1);
Transcript showCR('my second arg is: '+arg2);
return (arg1 + arg2); // the function's return value
};

Blocks without argument are defined as:
f := [ Transcript showCR:'blabla: Euler was great' ].
and invoked with a simple "<code>value</code>" message.

In both JavaScript and Smalltalk code, it is an error to invoke an inner function/block with a wrong number of arguments (2).

Smalltalk blocks and JavaScript inner functions can be used interchangeable - i.e. it is possible to pass a JS inner function to a collection method such as "<code>collect:</code>" or "<code>select:</code>". It is also possible, to pass either via input/output pins to other activities (which is not considered good style, as it could make the program quite hard to understand, if not used with caution).

Notice again, that the behavior of the Smalltalk return ("^") is different from a JavaScript return ("''return-Statement''") inside inner functions. The JavaScript return returns a value from the inner function, whereas the Smalltalk return forces a return from the containing method (the block's "execute" method). The Smalltalk return always behaves like the "return from execute" JavaScript special form.

1) Smalltalk/X allows for a non-standard block evaluation message using the "normal" parentheses notation. I.e. you can call a block with its arguments in parentheses as in "<code>f(1, 2, 3)</code>. This is syntactic sugar for the standard <code>f value:1 value:2 value:3</code>.

2) in Smalltalk, you can define "''varargs blocks''" with the "<code>asVarArgBlock</code>" message. The block will then receive its arguments as a vector, and fetch them using collection protocol (i.e. "size", "at:" or enumeration messages like "do:"). For example,
b := [:args | Transcript showCR: e'my arguments are {args}' ] asVarArgBlock
can be called with any number of arguments.

==== Example uses for Inner Functions ====

In Smalltalk, blocks are very often used when enumerating collections.
 For example, code corresponding to a C# 3.0 collection "<code>select (where(x => ...))</code>" is written in Smalltalk as:
|names namesStartingWithA|

names := #( 'Alice' 'Ann' 'Bob' 'Mallory' ).
namesStartingWithA := names select:[:n | n startsWith:'A'].

or in JavaSript as:
var names, namesStartingWithA;

names = [ "Alice" , "Ann" , "Bob" , "Mallory" ];
namesStartingWithA = names.select( function(n) { n.startsWith("A"); } );
or alternative using lambda expressions as:
var names, namesStartingWithA;

names = [ "Alice" , "Ann" , "Bob" , "Mallory" ];
namesStartingWithA = names.select( n => n.startsWith("A") );

To find the first element in a collection, for which some condition is true, use:
|names firstNameContainingAnO|

names := #( 'Alice' 'Ann' 'Bob' 'Mallory' ).
firstNameContainingAnO:= names detect:[:n | n includesString:'o'].

or in JavaSript as:
var names, firstNameContainingAnO;

names = [ "Alice" , "Ann" , "Bob" , "Mallory" ];
firstNameContainingAnO = names.detect( function(n) { n.includesString("o"); } );

For more information on the Smalltalk syntax, see [[http://live.exept.de/doc/online/english/getstart/tut_2.html Smalltalk Basics]] in the [[http://live.exept.de/doc/online/english/getstart/tutorial.html Smalltalk Online Tutorial]].

=== Builtin Data Types ===

The builtin types below and user defined primary types are mapped to corresponding classes of the underlying Smalltalk runtime system.
An introductory overview and links to the detailed documentation of individual classes is found in the
[http://live.exept.de/doc/online/english/classDoc/TOP.html Smalltalk Class Documentation] of the [http://live.exept.de/doc/online/english/TOP.html Smalltalk/X online documentation]. The following gives a rough summary of the main concepts. A good entry point for further learning is the [http://live.exept.de/doc/online/english/overview/basicClasses/TOP.html Smalltalk/X Basic Classes Overview Document], which provides links to the most heavily used classes and more detailed information.

==== Numeric Types ====

The underlying numeric type implementation supports multiple number representations. These can be used transparently in mixed-operations, and values are automatically converted as required. For example, the division of two integers returns another integer iff the division does not produce a remainder. Otherwise, a fraction object is returned.
Although very very rarely required in practice,
values can be converted explicitly, via one of the "<code>asXXX</code>" messages:
* <code>asFloat64()</code> - to convert to a double precision IEEE 64bit float
* <code>asFloat32()</code> - to convert to a single precision IEEE 32bit float
* <code>asFloat80()</code> - to convert to an extended precision IEEE 80bit float
* <code>asFloat128()</code> - to convert to an extended precision IEEE 128bit float
* <code>asInteger()</code>
* <code>asFraction()</code>
* <code>asScaledDecimal(scale)</code>
the older API is still supported, but less self explanatory:
* <code>asFloat()</code> - to convert to a double precision IEEE 64bit float
* <code>asShortFloat()</code> - to convert to a single precision IEEE 32bit float
* <code>asLongFloat()</code> - to convert to an extended precision IEEE 80bit float

Thus, if you want to avoid fractions (why would you?), process the result of an integer division using one of the <code>asFloat()</code>, <code>truncated()</code>, <code>floor()</code>, <code>ceiling()</code> or <code>rounded()</code> functions. But be aware that fractions provide an exact result, whereas float arithmetic is inherently imprecise, rounds on the the last bit and that such rounding errors accumulate.

===== Integer =====

This represents arbitrary precision integral numbers. Conversion and memory allocation is completely automatic.
 Thus, without danger of overflow, you can write:
x = 1234567890 * 12345678901234567890 / 10
to get:
1524157875171467887501905210

or:
x = 100.factorial();
to get the huge number:
933262154439441526816992388562667004907159682643816214685929638952175999932299156089
41463976156518286253697920827223758251185210916864000000000000000000000000

Small integer values (smaller than 32 or 64bit, depending in the underlying hardware's native word length) are stored more efficiently than large integers - however, the conversion and representation as used by the system is transparent and automatic.
The same is true for mixed mode arithmetic between small and large integers.

Occasionally it is required to perform modulo arithmetic in 32 or 64bit; for example to reproduce or check values as generated by C or Java programs. For this, use methods from the "''special modulo''" category, such as "<code>add_32()</code>", "<code>add_32u()</code>", "<code>mul_32()</code>" etc. Use a [[Tools_ClassBrowser|class browser]] to find those methods.

Integer constants (of arbitrary size) can be given in hexadecimal (Smalltalk: 16rxxx, JavaScript 0xXXXX), octal (Smalltalk: 8rxxx, JavaScript 0XXXX), and binary (Smalltalk: 2rxxx, JavaScript 0bXXXX). In fact, Smalltalk supports any base from 2 to 36 written as rxxx, where is the base. Thus 3r100 is the ternary representation of the integer 9.
For ease of use, Smalltalk also supports 0x, 0o and 0b radix prefixes (hex, octal and binary).

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#INTEGER More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Integer Class Documentation]

===== Float =====

Float represents double precision IEEE floating point numbers (64bit).
Although seldom needed, conversion to single precision (32bit) and high precision (80bit/128bit, depending on the underlying hardware) is possible via the ''asShortFloat()'' and ''asLongFloat()'' conversion functions. Notice that the actual precision of longFloat numbers depends on the CPU: x86 and x86_64 provide 80bits, Sparc and a few other CPUs provide 128 bits.

For more precision, additional classes called "<code>QDouble</code>" and "<code>LargeFloat</code>" are provided: QDouble provides roughly 200 bits (70 digits) of precision, and LargeFloat offers an arbitrary (configurable) precision. Both are described in the [[Numeric Limits/en|Numeric Limits]] and [[Number_API_Functions|Number API Functions]] documents.

 [[Number_API_Functions|Number API Functions]]
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#FLOAT More Info] in the Smalltalk/X online documentation
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Float Class Documentation]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,ShortFloat ShortFloat],
[http://live.exept.de/ClassDoc/classDocOf:,LongFloat LongFloat],
[http://live.exept.de/ClassDoc/classDocOf:,QDouble QDouble]

Class Documentation
 Details on QDoubles in [https://www.davidhbailey.com/dhbpapers/qd.pdf https:/www.davidhbailey.com/dhbpapers/qd.pdf].

====== Float Rounding Errors ======
Be reminded that floating point arithmetic is inherently inaccurate: there will almost always be rounding errors on the last bit. The reason is inherent in that most rational numbers simply cannot be represented as the sum of powers of two. For example, 0.1 and 0.3 are two of them: no sum of powers of two (1/2, 1/4, 1/8, ...) is able to represent these numbers exactly. Thus, there will definitely be an error in the last bit of the stored float value.

Typically, print functions (which convert floating point values to a string representation) will "cheat" and round on the last bit. However, if you operate with such numbers (i.e. add, multiply, etc.) these rounding errors will accumulate and may finally add up to more than one bit of error. When this happens, the print function will no longer round up, and you will get the typical ".999999" result strings.

As an example, try adding 0.3 a thousand times, as in:

|t|
t := 0.3.
1000 timesRepeat:[t := t + 0.3].
t print
may give "300.300000000006" as a result.

As a consequence, NEVER ever compare floating point values for equality. In the above case, the comparison with "300.3" would return false!

Floating point numbers should always be compared by giving a range (i.e. between x-delta and x+delta) or by giving a number of valid digits or bits, by which to compare.
expecco provides a number of action blocks for this kind of "''almost-equal''" comparisons.

Of course, there are also similar functions in the Float class, in case you need this in elementary Smalltalk or JavaScript code.

And also: NEVER ever compute monetary values using floating point - or your legal advisor will blame you for missing Cents in the invoice. Monetary values should never be processed with floats (expecco provides a ScaledDecimal number type for that, as described below).

Problems with numbers are discussed in detail in "[[Numeric Limits/en|Numeric Limits]]".

===== Fraction =====

Fractions are arbitrary-precision rational numbers. You will get them when dividing two integers and the result is not integral. Fractions represent an exact result, in contrast to floats, which are only approximations.

For example:
1 / 3
returns a fractional result with a numerator of 1 and a denominator of 3 (as opposed to the Smalltalk // operator, which truncates the result of the division to an integer).

Fractions have the advantage of avoiding rounding errors. Thus, when the above fraction is divided by 3, you will get ''(1/9)'', which we can multiply by 9 to get the exact ''1'' (an integer) without any rounding error. Be reminded that this is typically not the case with Float or Double precision numbers. Due to rounding errors on the last bit, you will often get 0.9999999 as a result there (even though printf may "cheat" and round it to "1.0", as long as the error is in the last bit only; however, when doing multiple operations in a row, these errors accumulate into the next bit, and rounding will no longer generate a "nice looking" output).

Fraction results are automatically reduced - therefore, when adding ''(1/3) + (2/6)'', you will get ''(2/3)''.
 And if you add another ''(1/3)'' to it, you will get an exact ''1''.

Be aware that fractional arithmetic is done by software, whereas floating point arithmetic is done by CPU instructions.
Therefore, floating point arithmetic is usually faster.

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#FRACTION More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Fraction Class Documentation]

===== ScaledDecimal =====

ScaledDecimal (also called "''FixedPoint''") numbers are decimals, with a configurable number of post-decimal digits. They are typically used when dealing with money. Like fractions, they avoid rounding errors. When printed, they round in their last digit, however, the exact information is always kept for further processing. ScaledDecimal numbers are perfect to represent money and other fractional data, which must be represented with a fixed number of post-decimal digits. Internally, fixed point numbers are represented as fractions with a power-of-10 denominator.
 
ScaledDecimal numbers are also great to print tabular data; for example: <code>someNumber as ScaledDecimal:3</code> will print the number with and rounded to 3 post-decimal digits.

 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#FIXEDPOINT More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,FixedPoint Class Documentation]

===== Complex=====

Complex numbers with real and imaginary part are sometimes used in technical/physical applications.
They can be read as "<code>a * b i</code>", for example: "<code>5 + 3i</code>" represents the complex number with 5 as real and 3 as imaginary part.

Complex numbers can result from math functions such as sqrt and log (by default, these raise an error, which can be ignored for a complex result)

 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Complex Class Documentation]

===== Number =====

The Number type is an abstract union type which includes all of the above types. Thus, a variable or pin declared as being of "<code>Number</code>" type can take any of the above values. Due to the polymorphic implementation of the underlying numeric class library, most operations can be passed any of the above values (even mixing arguments is possible). For example, the "[Add]" elementary block, which is implemented by simply calling the Smalltalk "+" operation, is able to deal with any combination of argument types.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#NUMBER More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Number Class Documentation]

==== String Types ====

Strings can come in three flavours (subclasses of CharacterArray), depending on how many bits are required to encode the character's code point. In general, Unicode is used internally as the encoding. However, converters are available to translate into other encodings, such as JIS or ISO 8859-x.

[[Datei:bulb.png|16px]] Notice that ASCII (0..127) and ISO 8859-1 (0..255) are proper subsets of the Unicode set.
Do not confuse Unicode with UTF-8: Unicode is the numeric value associated to a character and used everywhere within expecco.
UTF-8 is an encoding format for data interchange of Unicode characters. UTF-8 is NOT used inside expecco, only for data exchange with the external world (see "[[String_API_Functions#Encoding_.2F_Decoding|Encoding and Decoding]]" in the String API doc).

In most situations, you do not need to care for the actual number of bits required to store the characters, and expecco/Smalltalk takes care of the actual representation in memory. However, when dealing with the external world (files, sockets, devices), it may be required to perform explicit conversions to/from wider formats or different encodings (UTF-8, UTF-16, etc.)

===== String=====

This is used to represent character strings, where each individual character has a one-byte encoding. I.e. the values are 0..255.
Individual characters of a string can be accessed by an integral index starting with 1 in both Smalltalk and JavaScript. The String class provides many useful functions for substring searching, matching, concatenation/replacing etc.
Also, because String inherits all functions from the Collection superclass hierarchy, all enumeration, mapping, filtering functions are also applicable to strings.
 See also: [[String API Functions | ''Most Useful String Functions'']] and [[Collection API Functions | ''Most Useful Collection Functions'']]
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#STRING More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,String Class Documentation]

===== Unicode16String =====

This is used to represent character strings, where at least one character needs a two-byte encoding. I.e. any character's code point is in the range 0x0100 .. 0xFFFF. In fact, there is even a Unicode32String class (see below), which supports the full four-byte Unicode character set. But in practice, such strings are very rarely ever encountered or needed.

===== Unicode32String =====

This is used to represent character strings, where at least one character needs more than a two-byte encoding. I.e. any character's code point is above 0xFFFF. Such strings are very rarely ever encountered or needed.

===== Character =====
Individual characters (as extracted from a string or possibly read from a file) are represented as instances of the Character class. Queries are available to ask the character for its type (isLetter, isDigit etc.) or its Unicode encoding (codePoint). There is virtually no limit and every character from the full Unicode set (e.g. even above 0xFFFF) can be represented by instances of the Character class.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#CHARACTER More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Character Class Documentation]

==== Collection Types ====

Smalltalk and therefore also expecco provides a very complete set of collection types which are tuned for different access patterns or memory consumption.
An introductory overview on the collection classes is found in the
 Most Useful API: [[Collection API Functions | Most Useful Collection Functions]]
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html Collections Overview] of the [http://live.exept.de/doc/online/english/TOP.html Smalltalk/X online documentation].
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Collection Class Documentation]

The following paragraphs list the most used collection classes.
Notice, that Smalltalk provides many more container classes, so please take a look at the online documentation or take a life tour with the browser.

===== Array =====

Ordered, fixed size, indexed by an integral index starting with 1 in both Smalltalk and JavaScript.
Can store any type of object, and storage requirements are 1 machine word per element (i.e. arrays store pointers to the elements). As the size is fixed (when created), adding and removing of
elements is not possible. Use one of the other collections (OrderedCollection, Set or Dictionary) if the number
of elements needs to change later or is not known in advance.
 When accessing elements by index, access time complexity is constant O(1). A search for an element in an Array (using <code>includes:</code>, <code>indexOf:</code>, <code>findFirst:</code> or similar methods) has O(N) time complexity (because the search is linear through all elements of the array).
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#ARRAY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Array Class Documentation]

===== ByteArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 ByteArrays can only store very small byte-valued unsigned integers (0..255), and allocate 1 byte per element. Access time and complexity are like with ordinary arrays, but the required memory is much less. ByteArrays are used to represent the contents of binary data, binary files, bitmap images, protocol elements (data packets) or low level memory dumps.
 UInt8Array is an alias for ByteArray.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#BYTEARRAY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,ByteArray Class Documentation]

===== SignedByteArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 These store very small 8bit signed integer values (-128..127), requiring 1 byte of storage per element.
 Int8Array is an alias for SignedByteArray.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SignedByteArray Class Documentation]

===== BitArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 BitArrays can only store tiny bit-valued unsigned integers (0..1), but only need one byte of storage for every 8 elements.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,BitArray Class Documentation]

===== BooleanArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
 BooleanArrays can only store booleans (false..true), but only need 1 byte for every 8 stored boolean elements.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,BooleanArray Class Documentation]

===== FloatArray (Float32Array) =====
Ordered, fixed size, indexed by an integral index starting with 1.
 FloatArrays store short IEEE floats (32bit) and allocate 4 bytes per element.
Access times and complexity are like those of regular arrays, but they require much less memory. FloatArrays are often used for data interchange with C language functions or in data acquisition scenarios (series of measurement values).
 Float32Array is an alias for FloatArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#FLOATARRAY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,FloatArray Class Documentation]

===== DoubleArray (Float64Array) =====
Ordered, fixed size, indexed by an integral index starting with 1.
 DoubleArrays store IEEE doubles (64bit) and allocate 8 bytes per element.
These are used in similar situations as FloatArrays.
 Float64Array is an alias for DoubleArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#FLOATARRAY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,DoubleArray Class Documentation]

===== HalfFloatArray (Float16Array) =====
Ordered, fixed size, indexed by an integral index starting with 1.
 HalfFloatArray can only store IEEE half floats (16bit) and allocate 2 bytes per element.
: [[Datei:bulb.png|16px]] Notice that half floats have a very low precision and are seldom used.
: Exceptions are game programs and 3D graphics accelerators which preserve memory by using this very compact format for depth information, texture attributes and some audio formats. They are also used with AI programs in neural networks.
Float16Array is an alias for HalfFloatArray , and preferable, as it makes the precision explicit, und thus the code more readable.

===== IntegerArray / UInt32Array =====
Ordered, fixed size, indexed by an integral index starting with 1.
 These store small 32bit unsigned integer values (0..0xFFFFFFFF) and require 4 bytes of storage per element.
 UInt32Array is an alias for IntegerArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,IntegerArray Class Documentation]

===== SignedIntegerArray / Int32Array =====
Ordered, fixed size, indexed by an integral index starting with 1.
 They store small 32bit signed integer values (-0x800000000..0x7FFFFFFF), requiring 4 bytes of storage per element.
 Int32Array is an alias for SignedIntegerArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SignedIntegerArray Class Documentation]

===== WordArray / UInt16Array =====
Ordered, fixed size, indexed by an integral index starting with 1.
 They store small 16bit unsigned integer values (0..0xFFFF), allocating 2 bytes per element.
 UInt16Array is an alias for WordArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,WordArray Class Documentation]

===== SignedWordArray / Int16Array =====
Ordered, fixed size, indexed by an integral index starting with 1.
 They store small 16bit signed integer values (-0x8000..0x7FFF), allocating 2 bytes per element.
 Int16Array is an alias for SignedWordArray, and preferable, as it makes the precision explicit, und thus the code more readable.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SignedWordArray Class Documentation]

===== LongIntegerArray / UInt64Array =====
Ordered, fixed size, indexed by an integral index starting with 1.
 They store small 64bit unsigned integer values (0..0xFFFFFFFFFFFFFF), allocating 8 bytes per element.
 UInt64Array is an alias.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,LongIntegerArray Class Documentation]

===== SignedLongIntegerArray / Int64Array =====
Ordered, fixed size, indexed by an integral index starting with 1.
 These store small 64bit signed integer values (-0x80000000000000000..0x7FFFFFFFFFFFFFFF), allocating 8 bytes per element.
 Int64Array is an alias.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SignedLongIntegerArray Class Documentation]

===== ComplexFloatArray / Complex32Array, ComplexDoubleArray / Complex64Array, ComplexHalfFloatArray / Complex16Array=====
Ordered, fixed size, indexed by an integral index starting with 1.
 These store complex numbers as pairs of IEEE floats (32bit), doubles (64bit) or half floats (16bit). They allocate 8/16/4 bytes per element (4+4 / 8+8 / 2+2).
 These are used in similar situations as FloatArrays and DoubleArrays.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,ComplexFloatArray] [http://live.exept.de/ClassDoc/classDocOf:,ComplexDoubleArray]

===== OrderedCollection =====
Ordered, variable size, indexed by an integral index starting with 1.
 OrderedCollections can store any type of object and are specifically tuned for adding/removing elements at either end.
 Access time to elements by index has a time complexity of O(1).
 Insertion and remove at either end approach O(1), but is O(n) for inner elements, because the elements are moved inside a linear container.
When searching for an element in an OrderedCollection (using <code>includes:</code>, <code>indexOf:</code> or similar methods), time complexity is O(n) (because a linear search is done).

Java users will recognize the similarity to "''ArrayLists''".

Note: For very big or lightly sparse collections, you can use a [http://live.exept.de/ClassDoc/classDocOf:,SegmentedOrderedCollection SegmentedOrderedCollection]. This uses a hierarchy of buckets and does not need storage for big unused regions inside the collection. However, due to the additional computations, the breakeven in performance compared to regular OrderedCollections is usually at around 100K to 1M elements.

Note: For very very big collections (millions of elements) which are very lightly filled, use a [http://live.exept.de/ClassDoc/classDocOf:,SparseArray SparseArray]. This only keeps the filled slots, and is great, if you have only a few valid elements inside a virtually huge index space.

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#ORDCOLL More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,OrderedCollection Class Documentation]

===== SortedCollection =====
Sorts itself, variable size, indexed by an integral index starting with 1.
 SortedCollections can store any type of object for which a order relationship is either implicit (i.e. the elements responds to the "<code><</code>" (less) message) or for which an explicit comparison block can is given (i.e. you provide a sort-block, which takes two elements and returns a boolean depending on the ordering).

By default, sorting is by ascending order based on the "<code><</code>"-message. However, the sort order can be arbitrarily changed by setting the sortBlock, a two-argument JS-function or a two-argument Smalltalk block which should return true, if its first argument is to be "''considered''" smaller than the order (i.e. the default sort block is "<code>[:a :b | a < b]</code>" or in Javascript: "<code>(a,b) => a < b</code>).

Access time complexity by numeric index is O(1). When searching for an element in a SortedCollection (using <code>includes:</code>, <code>indexOf:</code> or similar methods); time complexity is O(log n), because a binary search can be done. Insertion and remove is O(1) for the first and last element, O(log n + n) for inner elements, because the insert index is first searched, then elements are moved inside a linear container.

When a big sorted collection is created, it is faster to first create it as a non-sorted collection (OrderedCollection) and then converting the whole collection via <code>asSortedCollection</code>, instead of adding individual elements one-by-one. If elements are to be added individually, it is probably better to use a tree like collection.

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#SORTCOLL More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SortedCollection Class Documentation]

===== Set =====
Unordered, variable size, keeps a single reference only, per equal element.
 Sets can store any type of object.
When searching a Set for an element (eg. using the <code>includes:</code> method), time complexity approaches O(1), because the search can be done based on a hashing algorithm in asymptotic constant time (however, the time to compute the hash of an element may affect the effective execution time; it should not be too slow). For very small sets, the hash-computation time might be long compared to the time it takes to compare elements. It may then be faster to simply use an Array or OrderedCollection and do a sequential search (use eg. "includes:", "indexOf:" or "anySatisfy:").

 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#SET More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Set Class Documentation]
 In addition to the unordered Set, useful classes are also <code>[http://live.exept.de/ClassDoc/classDocOf:,OrderedSet OrderedSet]</code> and <code>[http://live.exept.de/ClassDoc/classDocOf:,SortedSet SortedSet]</code>.

===== Bag =====
Unordered, variable size, keeps a count, per equal element. Adding, removing and insertion check all run in O(1).
Can store any type of object.
 Bags are similar to Sets, but keep the number of occurrences of each element. Thus, bags are perfect to count the number of elements in a collection, for example words and word counts in a document.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Bag Class Documentation]

===== Dictionary =====
Unordered, variable size, implements arbitrary key-value mappings.
 Dictionaries can store any type of object and use any kind of object as key.
When accessing or searching an element in a Dictionary (using <code>at:</code>, <code>includesKey:</code> and similar methods), the time complexity asymptotically approaches O(1), because the key search is based on a hashing algorithm. Notice, that the same value may be stored multiple times in a dictionary (i.e. stored under multiple keys).
Asking for the presence of a particular '''value''' in the dictionary (i.e. the reverse query without key) still has O(N) time complexity.

If you need fast access both via the key and the value, either use an additional reverse mapping dictionary, or store
an additional ''value''->''key'' mapping in the same dictionary (if the key and value spaces are disjoint).

Java users will know a subset of the dictionary functionality as "''Hashtable''".

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#DICTIONARY More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Dictionary Class Documentation]

===== OrderedDictionary =====
Ordered, variable size, implements arbitrary key-value mappings.
Can store any type of object and use any kind of object as key.
Being similar to dictionaries, these remember the order by which elements were added. It provides both access by hash-key and access by index (which is the order in which elements have been added). When enumerated, elements are processed in that order. Creation of an OrderedDictionary is somewhat slower than for Dictionary or OrderedCollection, but access by either numeric or hashkey is fast with O(1) time complexity.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,OrderedDictionary Class Documentation]

===== OrderedSet =====
This is very similar to a Set, but remembers the order in which elements were added, and provides index read access methods. When enumerated, the elements are generated in this order.

===== Queue =====
Ordered, variable size.
Can store any type of object. Queues are especially tuned for adding elements at one end, and removing them at the other. The internal representation uses a buffer in round-robin fashion. Both adding and removal are done on O(1) time.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#QUEUE More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Queue Class Documentation]

If multiple processes are accessing the same queue concurrently, use a <code>[http://live.exept.de/ClassDoc/classDocOf:,SharedQueue SharedQueue]</code>, which is implicitly synchronized.

===== SharedCollection =====
Any collection can be wrapped into a ''SharedCollection'' to add synchronization locks around its access functions. These should be used if multiple processes (threads) are going to access (i.e: update) the collection simultaneously.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SharedCollection Class Documentation]

===== BTree, AATree, BinaryTree =====
Combining the functionality of <code>Dictionary</code> and <code>SortedCollection</code>, these keep their elements in a sorted order, indexed by a key, both of which can be arbitrary objects.
In contrast to dictionaries, which use hashing, these use a tree-like representation and guarantee both asymptotic O(log N) worst case and average runtime. (Dictionaries have a much better typical time complexity of O(C), but also a worst case of O(N), if the hash keys are badly distributed). These trees are self balancing to avoid the linear worst case access time of non balanced trees. [[http://live.exept.de/ClassDoc/classDocOf:,BTree Class Documentation]]

There is also a non-balancing BinaryTree, which is slightly faster (by not balancing), but its worst case access times may degenerate to O(N), if elements are added non-randomly. Reference: [http://live.exept.de/ClassDoc/classDocOf:,BinaryTree Class Documentation]

===== Interval, GeometricSeries and NumberSet =====

An interval represents a range of numbers as in "<CODE>(1 to:5)</CODE>" or "<CODE>(1 to:10 by:2)</CODE>" or "<CODE>(7 to:4 by:-1)</CODE>"; these represent collections of numbers [1,2,3,4,5], [1,3,5,7,9] and [7,6,5,4] respectively.

GeometricSeries are similar, but have a constant factor between elements, instead of a constant difference. For example, the "<CODE>(GeometricSeries from:1 to:64 byFactor:2)</CODE>" represents the collection [1,2,4,8,16,32,64].

NumberSets are optimized for collections of integer number ranges. For example "<CODE>(NumberSet new add:1; add:3; addAll:(10 to:13)</CODE>" represents the collection [1,3,10,11,12,13].

Intervals, GeometricSeries and NumberSets can be used wherever a readonly collection can be used.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Interval Interval Class Documentation] and [http://live.exept.de/ClassDoc/classDocOf:,GeometricSeries GeometricSeries Class Documentation]

==== Stream Types ====

Streams are accessors for either internal collections or external files, sockets and other character oriented I/O devices.
They are created by either "''opening''" a file or device or by creation "''on''" a numerical indexable collection object (String, Array, OrderedCollection etc.).
Once created, readstreams deliver the next element via a "''next''()" operation, writestreams append elements via the "''nextPut(e)''" operation.
In addition to the above elementary functions, bulk read/write and linewise read/write and various other functionality is provided.

An introductory overview on the stream classes is found in the
[[http://live.exept.de/doc/online/english/overview/basicClasses/streams.html Streams Overview]] of the [[http://live.exept.de/doc/online/english/TOP.html Smalltalk/X online documentation]].

===== ExternalStream =====
A common superclass providing bytewise, blockwise and linewise access to any stream of the underlying operating system. Concrete subclasses are Socket, Filestream, Console Streams, PTYStream etc.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/streams.html#FILESTREAM More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,ExternalStream Class Documentation]

===== FileStream =====
Provide bytewise, blockwise or linewise access to the underlying file system.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/streams.html#FILESTREAM More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,FileStream Class Documentation]

===== CharacterWriteStream =====
A special stream usable for mixed single- and multibyte characters (i.e. Unicode). This stream starts to collect into a single byte string buffer, but switches automatically to a multibyte character string as required.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,CharacterWriteStream Class Documentation]

===== Socket =====
Provides low level bytewise, blockwise or linewise access to a communication socket. Typically, but not limited to TCP/IP connections.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/streams.html#FILESTREAM More Info]

Reference: [http://live.exept.de/ClassDoc/classDocOf:,Socket Class Documentation]

There are a number of useful companion classes which deal with host addresses:
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,SocketAddress SocketAddress],
[http://live.exept.de/ClassDoc/classDocOf:,SocketAddress IPSocketAddress] and
[http://live.exept.de/ClassDoc/classDocOf:,SocketAddress IPv6SocketAddress].

===== PipeStream =====
These are used to read/write from/to another program's standard input or standard output. For details, consult a Unix programmer's manual.
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,PipeStream Class Documentation]

===== Filename =====
Represents names of files in the filesystem. Provides many useful query functions for file size, access- and modification time, parent directory, children, path queries etc.
 Most Useful API: [[Filename API Functions]]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Filename Class Documentation]

==== Encoders / Decoders ====

The
[http://live.exept.de/ClassDoc/classDocOf:,CharacterEncoder CharacterEncoder] class provides a number of functions to encode/decode strings into various other encodings;
for example, to read an ISO 8859-7 encoded string,
use:
decodedString :=
(CharacterEncoder encoderFor:#'ISO8859-7')
decodeFrom:encodedString.
and vice versa:
encodedString :=
(CharacterEncoder encoderFor:#'ISO8859-7')
encodeFrom:originalString.

By the time of writing, the following encodings are supported (many are aliases of others):

adobe-fontspecific ansi_x3.4-1968 arabic ascii ascii7 asmo-708
big5
cns11643 cp-037 cp-37 cp-437 cp10000 cp1250 cp1251 cp1252 cp1253 cp1254 cp1255 cp1256 cp1257 cp367 cp437 cp878 cyrillic
ebcdic ebcdic-037 ecma-114 ecma-118
gb2312 gb2312.1980 gb2312.1980-0 greek
hangul hebrew
ibm-367 ibm-437 ibm-819 ibm-cp367 ibm-cp437 ibm-cp819 iso-10646-1 iso-8859-1 iso-8859-10 iso-8859-11 iso-8859-13 iso-8859-14 iso-8859-15 iso-8859-16 iso-8859-2 iso-8859-3 iso-8859-4 iso-8859-5 iso-8859-6 iso-8859-7 iso-8859-8 iso-8859-9 iso-ir-100 iso-ir-101 iso-ir-109 iso-ir-110 iso-ir-126 iso-ir-127 iso-ir-138 iso-ir-144 iso-ir-148 iso-ir-157 iso-ir-203 iso-ir-6 iso10646-1 iso10646_1 iso646-us iso8859 iso8859-1 iso8859-10 iso8859-11 iso8859-13 iso8859-14 iso8859-15 iso8859-16 iso8859-2 iso8859-3 iso8859-4 iso8859-5 iso8859-6 iso8859-7 iso8859-8 iso8859-9 iso8859_1 iso8859_10 iso8859_11 iso8859_13 iso8859_14 iso8859_15 iso8859_16 iso8859_2 iso8859_3 iso8859_4 iso8859_5 iso8859_6 iso8859_7 iso8859_8 iso8859_9
java javaText jis0201 jis0208 jis0212 jisx0201.1976-0 jisx0208 jisx0208.1983-0 jisx0208.1990-0 johab
koi7 koi8-r koi8-u ksc5601
latin-1 latin-10 latin-2 latin-3 latin-4 latin-5 latin-6 latin-7 latin-8 latin-9 latin-celtic latin1 latin10 latin2 latin3 latin4 latin5 latin6 latin7 latin8 latin9
mac-arabic mac-centraleurope mac-centraleuropean mac-croatian mac-cyrillic mac-dingbats mac-farsi mac-greek mac-hebrew mac-iceland mac-japanese mac-korean mac-roman mac-romanian mac-symbol mac-thai mac-turkish macarabic maccentraleurope maccentraleuropean maccroatian maccyrillic macdingbat macdingbats macfarsi macgreek machebrew maciceland macintosh macjapanese mackorean macroman macromanian macsymbol macthai macturkish microsoft-ansi microsoft-arabic microsoft-baltic microsoft-cp1250 microsoft-cp1251 microsoft-cp1252 microsoft-cp1253 microsoft-cp1254 microsoft-cp1255 microsoft-cp1256 microsoft-cp1257 microsoft-cp437 microsoft-cyrillic microsoft-easteuropean microsoft-greek microsoft-hebrew microsoft-turkish ms-ansi ms-arabic ms-baltic ms-cp1250 ms-cp1251 ms-cp1252 ms-cp1253 ms-cp1254 ms-cp1255 ms-cp1256 ms-cp1257 ms-cp367 ms-cp437 ms-cp819 ms-cyrillic ms-default ms-easteuropean ms-ee ms-greek ms-hebrew ms-oem ms-turkish next
nextstep
sgml
thai
us-ascii utf-16b utf-16be utf-16e utf-16le utf-8 utf-8-mac utf16b utf16be utf16l utf16le utf8 utf8-XML utf8-mac
windows-1250 windows-1251 windows-1252 windows-1253 windows-1254 windows-1255 windows-1256 windows-1257 windows-latin1

For base64 encoding, refer to the
[http://live.exept.de/ClassDoc/classDocOf:,Base64Coder Base64Coder]
class, or use the string messages: <code>base64Encoded</code> and <code>base64Decoded</code>.

For utf8 encoding/decoding, use the string messages: <code>utf8Encoded</code> and <code>utf8Decoded</code>.

==== Other useful Types ====

===== Date =====
Represents a calendar date. Instances can be created with eg. "<code>Date today</code>", by giving day/month/year or a calendar day. Instances offer a large number of queries, such as weekday, dayInWeek, leapYear etc.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#DATE More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Date Class Documentation]

===== Time =====
Represents a time-of-day in second resolution. Instances are created with "<code>Time now</CODE>" or by giving hour/minute/seconds.
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#TIME More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Time Class Documentation]

===== Timestamp (Date and Time) =====
Represents a timestamp. With the 18.1 release, the resolution has been improved to sub-nanosecond resolution, although internal timestamps as generated by the operating system will usually not generate such fine grained values (some systems will only generate, 1 millisecond resolution stamps).

Update: now the resolution supported by Timestamps is 1 picosecond, and microsecond times are also supported on Windows systems.

For backward compatibility, the default resolution is 1 millisecond for internally generated stamps, and whatever resolution is provided when stamps are read from an external source. When printed, the default print format includes 3 millisecond digits, but a separate print generator can produce higher resolution strings (in 18.1).

The Timestamp class has been enhanced to support dates before 1.1.1970 and after 2036, which are typical restrictions of systems which represent times as "''seconds since the epoch''" in a 32bit integer. Expecco timestamps handle values before and after those dates, although no calendar adjustments are done for timestamps before the julian/gregorian switch (i.e. this affects weekdays, leap years, etc. before 1582, which are very unlikely to be encountered in technical environments ;-) ).
 Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#TIMESTAMP More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,Timestamp Class Documentation]

===== TimeDuration =====
Represents an amount of time, to represent time intervals in picosecond resolution.

When reading from a string or stream, a unit-specifier character is allowed to specify milliseconds (ms), seconds (s), minutes (m), hours (h) or days (d). For example, "<code>1h 20s</code>" specifies 1 hour and 20 seconds.

As a programmer, you can write (in Smalltalk): "<code>1 hours + 20 seconds</code>"

Creation:
* TimeDuration fromString: '''aString'''
* TimeDuration fromSeconds: '''aNumber'''
* TimeDuration fromMinutes: '''aNumber'''
* TimeDuration fromHours: '''aNumber'''
* TimeDuration fromMilliseconds: '''aNumber'''
* TimeDuration fromMicroseconds: '''aNumber'''
* TimeDuration fromNanoseconds: '''aNumber'''
* TimeDuration fromPicoseconds: '''aNumber'''
* TimeDuration days: '''dayNumber''' hours: '''hourNumber''' minutes: '''minuteNumber''' seconds: '''secondsNumber'''

Overview: [http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#TIMEDURATION More Info]
 Reference: [http://live.exept.de/ClassDoc/classDocOf:,TimeDuration Class Documentation]

===== Delay =====
Delay is a utility providing timed delay functions. Most useful are (written in Smalltalk):
Delay waitForSeconds: n. (arg is a number)
and:
Delay waitFor: n seconds. (arg is a time duration)
and:
Delay waitUntil: timestamp. (arg is a timestamp)

or (written in JavaScript):
"<code>Delay.waitForSeconds(n)</code>";
"<code>Delay.waitFor(n.seconds())</code>";
and
"<code>Delay.waitUntil(timestamp)</code>";

Reference: [http://live.exept.de/ClassDoc/classDocOf:,Delay Class Documentation]

==== CTypes ====

These types describe C-data structures. They are needed when data is exchanged with DLL functions or is to be read/written in binary from/to a file or a communication channel.

CTypes are usually parsed from a string using the C Parser, which is invoked by expecco when a type definition starts with a comment like "/* C: */".
But of course, the C-Parser can also be invoked explicitly in a workspace or programmatically via an elementary block.
The following example would create a C-type from a structure definition string (in JavaScript code):
t = CParser.parseDeclaration("
struct s {
unsigned long DPR_Address;
unsigned long DPR_Length;
unsigned long PortAddress;
struct p {
unsigned char ProtocolID;
union u {
uint16 dpInOutAreaSize;
uint16 dpInAreaSize;
} Parameter;
} Protocol[4];
};
");
the type in variable "<code>t</code>" can then be instantiated by sending it a "<code>new</code>" message:
cDatum = t.new();
or with:
cDatum = t.malloc();
The difference is that "<code>new</code>" allocates the bytes in the regular garbage collected expecco memory (which may move objects),
whereas "<code>malloc</code>" allocates in pinned (not moving) memory on the C heap. Thus references to such malloc'd memory can be passed to DLL code which wants to keep a reference to it, whereas C-data allocated with <code>new</code> can only be used temporarily by C code and will vanish sooner or later after the call returns.

You can inspect the created instance via the inspector (evaluate: "<code>cDatum.inspect()</code>").

Individual fields of the c-datum are accessed via the following functions:
* <code>cDatum.memberAt(fieldName)</code> retrieves a field. If the field is a composite datum (array or structure), a new datum is extracted (i.e. a structure copy is made).

* <code>cDatum.at(index0Based)</code> retrieves an indexed array element as a copy.

* <code>cDatum.memberAtPut(fieldName, value)</code> stores a field. If the field is a composite datum (array or structure), the whole value is copied.

* <code>cDatum.atPut(index0Based)</code> stores an indexed array element.

* <code>CDatum.refMemberAt(fieldName)</code> creates a pointer to a field. This allows for subfields to be modified.

* <code>cDatum.refAt(index0Based)</code> creates a pointer to an array element.

notice that in JavaScript, indexed access can be written more convenient as "<code>cDatum[index0Based]</code>" and that member field access can be written as "<code>cDatum.fieldName</code>".

For the full protocol of CDatum, please refer to the class code in the
[http://live.exept.de/ClassDoc/classDocOf:,Ctype Class Documentation].
 Additional information is also found in the [[Datatype Element/en#CTypes]] documentation.

=== Additional Standard Objects for JavaScript ===

In order for a "''well known''" environment to be provided to those who know JavaScript, but do not know Smalltalk, mimicri classes (Math) and mimicri protocol has been added to the underlying Smalltalk system. These functions simply call corresponding Smalltalk functions and only exist to provide a JavaScript compatible API which is described below.

Notice that this represents only a small fraction (less than 1/100th) of the real functionality of the base system. In order to find out more about all existing classes, you should open a class browser and navigate through the system yourself (eg. Number and subclasses). There is also a more detailed introduction to the basic classes found in the
[http://live.exept.de/doc/online/english/overview/basicClasses/TOP.html Smalltalk/X Base Classes Documentation].

==== Math ====

===== Constants =====

*'''E''' Euler's constant, the base of the natural logarithm (approximately 2.718 as double precision IEEE number). Same as "<code>Float e</code>" in Smalltalk (or "<code>Math E</code>").

*'''LN10''' Natural logarithm of 10 (approximately 2.302 as double). In Smalltalk, you can use "<code>Float ln10</code>" (or "<code>Math LN10</code>").

*'''LN2''' Natural logarithm of 2 (approximately 0.693 as double). Same as "<code>Float ln2</code>" in Smalltalk.

*'''LOG10E''' Base 10 logarithm of E (approximately 0.434 as double)

*'''LOG2E''' Base 2 logarithm of E (approximately 1.442 as double)

*'''PI''' Pi (approximately 3.14159 as double). Same as "<code>Float pi</code>" in Smalltalk.

*'''SQRT1_2''' Square root of 1/2 (approximately 0.707 as double)

*'''SQRT2''' Square root of 2 (approximately 1.414 as double). Same as "<code>Float sqrt2</code>" in Smalltalk.

===== Min & Max =====

*'''max''' (''number1 , number2,...'') Returns the largest of up to 6 arguments

*'''min''' (''number1, number2,...'') Returns the smallest of up to 6 arguments

===== Miscellaneous =====

*'''abs''' (''aNumber'') Returns the absolute value of aNumber

*'''binco''' (''n, k'') Returns the binomial coefficient C(n,k) (aka. "n over k" or "choose k from n")

*'''cbrt''' (''aNumber'') Returns the cubic root of aNumber

*'''ceil''' (''aNumber'') Returns the smallest integer greater than or equal to aNumber

*'''exp''' (''aNumber'') Returns eaNumber, where aNumber is the argument, and e is Euler's constant, the base of the natural logarithm

*'''fac''' (''aNumber'') Returns the factorial of aNumber

*'''floor''' (''aNumber'') Returns the greatest integer less than or equal to aNumber

*'''gcd''' (''a, b'') Returns the greatest common divisor of a and b

*'''log10''' (''aNumber'') Returns the log base 10 of aNumber

*'''log''' (''aNumber'') Returns the log base E of aNumber


*'''pow''' (''base, exp'') Returns base to the exponent power, that is, baseexp

*'''random''' Returns a pseudo random number between 0 and 1

*'''round''' (''aNumber'') Returns the value of aNumber rounded to the nearest integer

*'''sqrt''' (''aNumber'') Returns the square root of aNumber

*'''trunc''' (''aNumber'') Returns the value of aNumber truncated towards zero (that is: the smallest integer greater or equal if aNumber is negative, or the largest integer less or equal if positive)

===== Trigonometric =====

*'''sin''' (''aNumber'') Returns the sine of aNumber (given in radians)

*'''cos''' (''aNumber'') Returns the cosine of aNumber (given in radians)

*'''tan''' (''aNumber'') Returns the tangent of aNumber (given in radians)

*'''cot''' (''aNumber'') Returns the cotangent of aNumber (given in radians)

*'''csc''' (''aNumber'') Returns the cosecant of aNumber (given in radians)

*'''sec''' (''aNumber'') Returns the secant of aNumber (given in radians)

*'''arcSin''' (''aNumber'') Returns the arcsine (in radians) of aNumber

*'''arcCos''' (''aNumber'') Returns the arccosine (in radians) of aNumber

*'''arcTan''' (''aNumber'') Returns the arctangent (in radians) of aNumber

*'''arcTan2''' (''x, y'') Returns the arctangent of the quotient of its arguments (in radians)

*'''sinh''' / '''cosh''' / '''tanh''' / '''arSinh''' / '''arCosh''' etc. Hyperbolic versions of above

*'''degreesToRadians'''(''d'') / '''radiansToDegrees'''(''r'') Conversions

==== Number ====
===== Properties =====

*'''MAX_VALUE''' The largest representable number. The returned number is 0x7FFFFFFFFFFFFFFF, to mimicri a 64 bit limit on numbers for JS programs ported from other systems. In fact, expecco does not impose any such limit in integer values.

*'''MIN_VALUE''' The smallest representable number. The returned number is -0x8000000000000000, to mimicri a 64 bit limit on numbers for JS programs ported from other systems. In fact, expecco does not impose any such limit in integer values.

*'''NEGATIVE_INFINITY''' Returns the special 'negative infinity' value

*'''NaN''' Returns the special 'not a number' value

*'''POSITIVE_INFINITY''' Returns the special 'positive infinity' value

===== Methods =====

*''aNumber''.'''asFloat''' () Returns a floating-point version of the receiver object. For example: "<code>1.asFloat()</code>" yields the (double precision) floating point number: "1.0". You can also use one of "asFloat32", "asFloat64", "asFloat80", "asFloat128" or "asLargeFloat".

*''aNumber''.'''asInteger''' () Returns an integer version of the receiver object (truncating). For example: "<code>1.0.asInteger()</code>" yields the integer number: "1". Alternatives are ceiling(), floor() and rounded().

*''aNumber''.'''ceiling''' () For non-integral values, ceiling returns the smallest integer which is larger than the receiver. For integers, the original value is returned. For example: "<code>1.4.ceiling()</code>" yields the integer number: "2", whereas "<code>1.ceiling()</code>" returns "1". See also: floor() and rounded().

*''aNumber''.'''floor''' () For non-integral values, floor returns the largest integer which is smaller than the receiver. For integers, the original value is returned. For example: "<code>1.4.floor()</code>" yields the integer number: "1", whereas "<code>1.floor()</code>" returns "1". See also: ceiling() and rounded().

*''aNumber''.'''rounded''' () For non-integral values, rounded returns the nearest integer from rounding. For integers, the original value is returned. For example: "<code>1.4.rounded()</code>" yields the integer number: "1", "<code>1.6.rounded()</code>" yields the integer number: "2" and whereas "<code>1.rounded()</code>" returns "1". See also: ceiling() and floor().

*''aNumber''.'''roundTo''' (''r'') Rounds towards the nearest multiple of r. For example, "<code>1.543.roundedTo(0.01)</code>" returns "1.54" and "<code>1.567.roundedTo(0.01)</code>" returns "1.57". See also: ceiling(), floor() and rounded().

*''aNumber''.'''toExponential''' (''nDigits'') Returns a string representing the number in exponential notation, where nDigits is the number of digits to appear after the decimal point

*''aNumber''.'''toExponential''' (''nDigits, nDigitsAfter'') Returns a string representing the number in exponential notation

*''aNumber''.'''toFixed''' (''nDigits'') Returns a string representing the number in fixed notation, where nDigits is the number of digits to appear after the decimal point

==== Random ====

A built in random generator, which generates linear congruential pseudo random numbers itself. On Unix/Linux operating systems, an additional class called "RandomGenerator" uses the operating system's random generator (<code>/dev/rand</code>). In addition, alternative generators are available as "<code>RandomParkMiller</code>" and "<code>RandomTT800</code>". For most applications, the default generator named "<code>Random</code>" should provide a reasonable random sequence (this will be the "/dev/rand"-based generator on Unix/Linux, and a Cryptographic Hash-based generator on other systems).

*''Random''.'''next ()''' Returns a random number between 0 and 1 (float)

*''Random''.'''next (''n'')''' Returns n random numbers between 0 and 1 (float) as an array

*''Random''.'''nextBoolean ()''' Randomly returns either true or false

*''Random''.'''nextBetween_and_''' (''min, max'') Returns a random float between min and max

*''Random''.'''nextIntegerBetween_and_''' (''min, max'') Returns a random integer between min and max (use 1 and 6, to simulate a dice)

==== Time / Date ====

Time and Date instances provide a rich protocol for all kinds of queries. The list below is only a short extract of the most used methods:

*'''Time now''' Returns the current time

*'''Date today''' Returns the current date

*''aDate''.'''getDate'''() Returns the day of the month (1..31)

*''aDate''.'''getDay'''() Returns the day of the week (0..6); Sunday is 0

*''aDate''.'''getMonth'''() Returns the day of the month (1..12)

*''aDate''.'''getFullYear'''() Returns the year

*''aTime''.'''getHours'''() Returns the hours (0..24)

*''aTime''.'''getMinutes'''() Returns the minutes (0..60)

==== String ====

Be reminded that the String class inherits from CharacterArray, ByteArray, SequentialCollection, Collection and Object. Thus all of those methods are also available (and useful) with strings. Use the browser or take a look at the online documentation for the full protocol (which is much larger than what is listed below).

*''aString''.'''charAt0''' (''index'') Returns the n'th character as a Character instance object, using a 0-based indexing scheme

*''aString''.'''charAt1''' (''index'') Returns the n'th character as a Character instance object, using a 1-based indexing scheme

*''aString''.'''charCodeAt0''' (''index'') Returns the code of the n'th character, using a 0-based indexing scheme

*''aString''.'''charCodeAt1''' (''index'') Returns the code of the n'th character, using a 1-based indexing scheme

*''aString''.'''indexOf0''' (''aCharacter'') Returns the index of aCharacter, using a 0-based indexing scheme; -1 if not found

*''aString''.'''indexOf1''' (''aCharacter'') Returns the index of aCharacter, using a 1-based indexing scheme; 0 if not found

*''aString''.'''lastIndexOf0''' (''aCharacter'') Returns the last index of aCharacter, using a 0-based indexing scheme; -1 if not found

*''aString''.'''lastIndexOf1''' (''aCharacter'') Returns the last index of aCharacter, using a 1-based indexing scheme; 0 if not found

*''aString''.'''quote()''' Wraps the receiver into double quotes (")

*''aString''.'''split''' (''separator'') Splits the string into a collection of substrings using the separator. Warning: the JavaScript split(xxx) function and the Smalltalk split: method have different semantics (and argument order)

*''aString''.'''substr0''' (''index, count'') Extracts a substring starting at the index with the given length, using a 0-based indexing scheme

*''aString''.'''substr1''' (''index, count'') Extracts a substring starting at the index with the given length, using a 1-based indexing scheme

*''aString''.'''substring0''' (''index1'') Extracts a substring starting at the index, using a 0-based indexing scheme

*''aString''.'''substring0''' (''index1, index2'') Extracts a substring between the given indices, using a 0-based indexing scheme

*''aString''.'''substring1''' (''index1'') Extracts a substring starting at the index, using a 1-based indexing scheme

*''aString''.'''substring1''' (''index1, index2'') Extracts a substring between the given indices, using a 1-based indexing scheme

*''aString''.'''toLowerCase''' Returns a copy of the receiver with all chars in lower case

*''aString''.'''toUpperCase''' Returns a copy of the receiver with all chars in upper case

*''aString''.'''trim''' Returns a copy of the receiver with all leading and trailing white space removed

*''aString''.'''trimLeft''' Returns a copy of the receiver with all leading white space removed

*''aString''.'''trimRight''' Returns a copy of the receiver with all trailing white space removed
 

==== Collection (Array) ====

Notice that Array, OrderedCollection, ByteArray, String and others are also inheriting the Collection protocol. Thus the below listed messages can also be applied to instances of those.

*''aCollection''.'''concat''' (''aCollection'') Returns a new collection consisting of the concatenation of the receiver and the argument

*''aCollection''.'''every''' (''filterFunction'') Returns true, if "filterFunction" returns true for all elements

*''aCollection''.'''filter''' (''filterFunction'') Selects elements for which "filterFunction" returns true

*''aCollection''.'''forEach''' (''function'') Applies "function" for each element

*''aCollection''.'''join''' (''seperator'') Joins the strings of the receiver into a new single string using the separator

*''aCollection''.'''map''' (''function'') Returns a new collection collecting the results of applying "function" to each element in sequence

*''aCollection''.'''pop''' Removes and returns the last element of the collection. Modifies the receiver collection as a side effect.

*''aCollection''.'''push''' (''value'') Adds an element to the end of the collection. Modifies the receiver collection as a side effect.

*''aCollection''.'''reduce0''' (''filterFunction'') Applies "function" against two values, reducing from left to right. Function must be declared as: f(previousValue, currentValue, index, arr). Pass 0-based indices to the filter.

*''aCollection''.'''reduce0''' (''filterFunction, initialValue'') Applies "function" against two values, reducing from left to right. Function must be declared as: f(previousValue, currentValue, index, arr). Pass 0-based indices to the filter.

*''aCollection''.'''reduce1''' (''filterFunction'') Applies "function" against two values, reducing from left to right. Function must be declared as: f(previousValue, currentValue, index, arr). Pass 1-based indices to the filter.

*''aCollection''.'''reduce1''' (''filterFunction, initialValue'') Applies "function" against two values, reducing from left to right. Function must be declared as: f(previousValue, currentValue, index, arr). Pass 1-based indices to the filter.

*''aCollection''.'''shift''' Removes and returns the first element of the collection. Same as ''removeFirst''. Notice that this modifies the receiver collection as a side effect.

*''aCollection''.'''slice0''' (''index1, index2'') Extracts a subcollection, using a 0-based indexing scheme

*''aCollection''.'''slice1''' (''index1, index2'') Extracts a subcollection, using a 1-based indexing scheme

*''aCollection''.'''some''' (''filterFunction'') Returns true, if "filterFunction" returns true for any element

*''aCollection''.'''unshift''' (''arg'') Adds an element to the beginning of the collection. Same as ''addFirst''. Notice that this modifies the receiver collection as a side effect.
 

==== Transcript ====

The global variable "<code>Transcript</code>" refers to either the Transcript information window (if it is open) or the standard error stream. As such, it implements most of the stream interface functions. Most noteworthy are:

*Transcript.'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

* Transcript.'''show''' (''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

* Transcript.'''show''' (''fmt'', ''arg'',...) Like show, but "%i" (i=1..8) sequences in the format argument are expanded by corresponding argument strings. Up to 8 arguments are allowed.

* Transcript.'''showCR''' (''arg'') A combination of show(), followed by a linebreak.

* Transcript.'''showCR''' (''fmt'', ''arg'',...) Like showCR, but "%i" (i=1..8) sequences in the format argument are expanded by corresponding argument strings. Up to 8 arguments are allowed.

and from the inherited write stream interface:

* Transcript.'''nextPut''' (''aChar'') Sends a single character

* Transcript.'''nextPutAll''' (''aString'') Sends a string

* Transcript.'''nextPutLine''' (''aString'') Sends a string followed by a linebreak

Notice that if a prefix string is defined in a variable named "__Transcript_Prefix__", that string is prepended to the output.

 

==== Logger ====

The global variable "<code>Logger</code>" refers to an object which will handle system log messages. This is the underlying Smalltalk framework's logging mechanism, not to be confused with expecco's ''ActivityLog''.

The Logger will filter messages according to their ''severity'', which is one of {<code>debug, info, warn, error, fatal</code>}. Severities are ordered as <code>debug < info < warn < error < fatal</code>.
For filtering, a severityThreshold can be set, and only messages with a higher severity will be reported.

By default, the Logger sends its output to the ''stderr'' stream, which is usually redirected into a (log-)file when expecco runs unattended as a service or controlled by command line arguments.
This behavior can be changed by assigning a different logger to the global "Logger".
Under Unix systems (OSX and Linux), the defaul logger can also be replaced by one which writes to the syslog facility.
 The Logger supports the following protocol:

*Logger.'''debug''' (''message'') logs a debug message

*Logger.'''info''' (''message'') logs an info message

*Logger.'''warn''' (''message'') logs an warning message

*Logger.'''error''' (''message'') logs an error message

*Logger.'''fatal''' (''message'') logs a fatal message
 

=== Expecco Objects ===
Many objects internal to expecco's execution machinery are reachable via elementary code (i.e. from within an elementary-coded action's code).
A lot of useful and required information can be acquired by consulting these objects.
The anchor to all those objects is the "''current activity''" object.

==== Current Activity ====
Within elementary code the activity instance which is executing this piece of code can be accessed via the variable "<code>this</code>" (in Smalltalk: "<code>self</code>"). For every executed action, a new activity object is created. It is usually alive during the execution only (i.e. it is destroyed and its memory reused automatically, after the block's action has finished).

The current activity object supports the following functions:

===== Reporting =====

*'''error''' () Report a defect (in the test). Stops execution.

*'''error''' (''infoString'') Report a defect (in the test) with infoString to be shown in the activity log. Stops execution.

*'''fail''' ( [''infoString''] ) Report a failure (in the SUT) with optional infoString to be shown in the activity log. Stops execution.

*'''inconclusive''' ( [''infoString''] ) Report an inconclusive test. Stops execution.

*'''success''' ( [''infoString''] ) OBSOLETE - see activitySuccess below Finishes the current activity with success.

*'''activitySuccess''' ( [''infoString''] ) Finishes the current activity with success. Actually not needed, because simply returning from an action's execute method is semantically equivalent (however, this allows for early successful finish). Due to the more descriptive name, use this function instead of "<code>success()</code>".

*'''testPass''' ( [''infoString''] ) Finishes the current test case with success. Notice: this aborts the current activity and all of the callers up to the test case level. This behavior is different from activitySuccess's behavior.

*'''pass''' ( [''infoString''] ) Same as testPass (backward compatibility).
 

===== Logging =====

*'''logData''' (''data'') Adds data to the activity log.

*'''logDataFile''' (''fileName'') Adds a file attachment to the activity log.

*'''logError''' (''messageString'') Adds a error message to the activity log.

*'''logError''' (''messageString'', ''detail'') Adds a error message to the activity log.

*'''logWarning''' (''messageString'') Adds a warning to the activity log.

*'''logWarning''' (''messageString'', ''detail'') Adds a warning to the activity log.

*'''logInfo''' (''messageString'') Adds an info message to the activity log.

*'''logInfo''' (''messageString'', detail) Adds an info message to the activity log.

*'''logImageInfo''' (''messageString'', image) Adds an info message with an image (screendump) to the activity log. There is an option in the report generator to include those in the generated pdf-report.

*'''alert''' (''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "[[Settings_LoggingSettings/en|Execution-Log-Settings]]" dialog (by default, it is disabled).

*'''warn''' (''messageString'') Same as ''alert()'' (for Smalltalk protocol compatibility).

Notice the similarity and difference between "error()" and "logError()": both actually create a log-data entry, but "error()" stops the execution, whereas "logError()" proceeds (maybe, the naming is a bit confusing here...)

 

===== Execution =====

*'''call''' (''calledActionName'') Calls another action without any input values. The called action is specified by the "''calledActionName''" parameter.
*'''call''' (''calledActionName'', ''arg''...) Calls another action with ''argi'' input value(s). The called action is specified by the "''calledActionName''" parameter. Up to 8 arguments are supported.
*'''call_with''' (''calledActionName'', ''inPinValues'') Calls another action passing input values as a collection of values. The called action is specified by the "''calledActionName''" parameter.
*'''call_into''' (''calledActionName'', ''funcReceivingValues'') Not passing any input values (similar to call), for actions with multiple output values or which write multiple values.
*'''call_with_into''' (''calledActionName'', ''inPinValues'', ''funcReceivingValues'') Similar to the above, for actions with multiple output values or which write multiple values.
The called action is specified by the "''calledActionName''" parameter which must be one of:
* a UUID (the called action-block's version- or function-ID),
* a UUID-string (the called action-block's version- or function-ID),
* a name-string (the called action-block's name),
* a direct reference to the action-block object.

Although giving a simple name-string is propably the easiest way to specify the action, it may lead to an error, if multiple actions are found with the same name (which never happens, if a UUID is used). If a UUID is used, this can be either the action's functional- or version-ID. If the version-ID is given, that particular action is called. If a functional-ID is given, the first action which is found to have a matching functional-ID is called. The version-ID is specific, but intolerant to reimports or changes in the called action. Therefore, you should propably use the functional-ID, if you do not want to use the action's name.
 In most "normal" situations, the action's name is unique and good enough.

There is an automatic mechanism, to deal with renaming, in that constant action names are found and replaced.
Also, such action references are found via the "''References''" tree menu item and you'll get a warning if such an action is renamed or removed.

The "''inPinValues''" argument can be either a vector (array) or a dictionary (mapping pin-name to value) of values to be passed to the input pins of the called action. An input value of "Void" ("void" in JavaScript) will be treated like an unconnected pin.

The first variants (without the "into:" argument) return the value of the first output pin (or nil, if there are no output pins). If the output is written multiple times, an error is reported.

The other variant expects a "''funcReceivingValues''" argument, which must be a JS-function or Smalltalk-Block. This function/block is called with the output pin values as arguments. For each pin, one collection containing all values written to the corresponding pin is passed to it as argument (a collection of values is passed, because the pins could be written multiple times by the action).

For example from a Smalltalk coded action, the "<code>Arith [MinMax]</code>" action (which has 2 outputs) can be called with:
self
call:"Arith [ MinMax ]"
with:{ addend1 . addend2 }
into:[:minOutValues :maxOutValues |
"/ ... do something with the min/max values ...
min := minOutValues first.
max := maxOutputValues first.
]
with JavaScript code, the above would be written as:
this.call_with_into("Arith [ MinMax ]",
[ addend1 , addend2 ],
function (minOutValues , maxOutValues) {
// ... do something with the min/max values ...
min = minOutValues.first();
max = maxOutputValues.first();
})
or, using a lambda function, as:
this.call_with_into("Arith [ MinMax ]",
[ addend1 , addend2 ],
(minOutValues , maxOutValues) => {
// ... do something with the min/max values ...
min = minOutValues.first();
max = maxOutputValues.first();
})
In most cases, this callback function would simply store the output values into local variables, as in:
execute
|.. minResult maxResult ..|
...
self
call:'Arith [ MinMax ]' with:#(10 20)
into:[:mins :maxes |
minResult := mins first.
maxResult := maxes first.
].
...
do something with minResult and maxResult
...

Exceptions in the called action can be handled in the calling action:
...
[
result := self call:'Arith [ Quotient ]' with:{ dividend . 0}.
] on:ZeroDivide do:[:ex |
Transcript showCR:'a division by zero occurred'.
].
...

Notice, that a test-fail verdict is reported as TestFail, which is a subclass of Exception,
whereas a test-error verdict is reported as TestError, which is a subclass of Error.
Thus, to handle both failure and error in one handler, you may write:
...
[
result := self call: ...
] on:(Error, Exception) do:[:ex |
Transcript showCR:'either error or fail'.
].
...

or in JS:
...
try {
result = call( ... )
} catch(Error + Exception) {
Transcript.showCR("either error or fail");
}
...

===== Reflection, Information, Queries and Accessing =====

*'''activityCreator''' () The triggering activity (i.e. the caller). Except for special tricks, this is only useful to generate nice print messages (such as "activity foo, called from bar".

*'''activityProcess''' () The thread executing the activity

*'''blockDescription''' () The definition of the activity (i.e. the tree definition item of the action's step)

*'''executor''' () Returns the current executor. See [[#Executor Functions|"Executor Functions"]] below.

*'''inputValueForPin''' (''pin'') The value of a certain pin

*'''inputValueFor''' (''pinName'') The value of a certain pin by name. Reports an error, if there is no such pin, the pin is unconnected or has no value.

*'''inputValueFor_ifAbsent''' (''pinName'', ''ifAbsentValue'') The value of a certain pin by name. Returns "ifAbsentValue" if there is no such pin, the pin is unconnected or has no value.

*'''inventory''' () The inventory of the activity

*'''nameOfStep''' () The name of the corresponding step of the activity

*'''resources''' () All resources which have been acquired for the activity (as specified in the resource-definition of the action). Retrieves a collection of Resource objects, as described below.

*'''resourcesForId''' (''skillId'') Resources which have been acquired for one particular skill-requirement. The argument ''skillId'' corresponds to the name as specified in the first column of the resource definition of the action). Notice, that a collection of Resource objects is returned - even if only one resource has been acquired.

*'''step''' () The corresponding step of the activity

*'''stepLocalStorageAt''' ("<varName>") Retrieves a step's local storage value.

*'''stepLocalStorageAt_put''' ("<varName>", ''value'') Defines a step's local storage value.
:Step local storage can be seen as a kind of static variable, which is only visible inside the code of a single execute function, but with the live time of the step. This means that the value is still present, when the step is executed the next time. However, it will vanish, whenever the diagram which contains the step is edited. Also, its value is not copied, when the step is copied. It is also not made persistent. The value will be reset to nil with every edit operation on the diagram, or via a menu function in the project's "More" menu, or the step's menu.
:Step local storage can be used to count the number of invocations, or to implement static state which is to be preserved between step executions.
:This is an experimental feature, only to be used by advanced users.
 

===== Environment Access =====

Starting at every compound activity, a nested stack of outer environments is present, ending in a top project environment. The following activity methods provide access to some of them. This can be used to automatically setup environment variables from a configuration or when autodetecting a system-under-test's configuration and leaving the values in a defined outer environment. Depending on the intended lifetime of those values, one of the following environments should be chosen as target of such operations:

*'''environment''' () The currently valid environment variables of the compound step which contains this action, or (if none) of the test plan in which this action executes (see "[[#Environment Access|Environment Access]]" below)

*'''environmentAt''' (''anEnvironmentVarName'') The value of an environment variable (in the environment as described above)

*'''environmentAt_put''' (''anEnvironmentVarName'', ''value'') Changing the value of an environment variable (in the environment as describe above)

* '''executorEnvironment''' () an environment which is only present during a single testplan execution

* '''projectEnvironment''' () an environment which is attached to the current test suite (but not persistent when the suite is saved/loaded from an ets file)

* '''browserEnvironment''' () an environment which is attached to the expecco application window; i.e. present while the window is open (i.e. the current session). (it is not made persistent)

* '''systemEnvironment''' () an environment which is present while the expecco application is running (i.e. the current session). (it is not made persistent)

Except for the project environment, none of them are made persistent directly (i.e. the values will not saved with the ".ets"file). However, every test suite, test plan and compound block provides a description of initial values and how to compute them in their environment description, which is edited using the [[ Environment Editor ]] or which can be modified with actions from the reflection library.
Also, such descriptions can be saved and loaded separately from the test suite via the "''Load/Save Parameter Set''" menu functions of the "''File''" menu or via the "--parameters" [[Starting_expecco_via_Command_Line/en#Test_Parameters | command line argument]].

 

===== Event Sending =====
Events can be pushed onto an event queue from either actions found in the standard library or via
API calls to the current activity (also from bridged elementary actions).
The global event handler should be already running (and especially, a handler should be registered) before the first
event is sent. Otherwise, the event might be ignored or an error is raised. A sample suite is found in "demos/d62_Event_Queue_Demos".

* '''pushEvent''' (''eventOrPayloadData'') pushes an event onto the global event handler's event queue. The argument may be either an instance of Event, or the payload (which is packed into an Event instance with type #default). Raises an error, if no global event handler process is running.

* '''pushEventType_data''' (''eventTypeSymbolOrNil'', ''payloadData'') pushes an event of type (or #default) onto the global event handler's event queue. Raises an error, if no global event handler process is running.
 

==== Executor Functions ====

The executor (as returned from the current activity via the "''executor()''" function described above) is responsible
to execute steps in a network and elementary code in a controlled fashion. In addition to sequencing and assigning activities to a particular execution thread, it also cares for the activityLog and error handling.
Usually, you do not need to interact with an executor directly.

*'''executorsWorkingDirectory''' () Temporary working directory. This is removed after the execution (i.e. useful only for very temporary files, which are generated in an action and read in another)

*'''testplan''' () The currently executed testplan (nil if a block test blocks are executed)

*'''project''' () Project (testsuite or library) in which the test is executed
 

==== Resource Functions ====

Resources can be assigned to an action as a "''required resource''", and the execution will be synchronized with the
allocation and reservation of a particular resource as acquired from an inventory.
Once allocated, the resources are available to the action via ''resources()'' or ''resourcesForId()'' functions:

*'''resources''' () retrieves the set of resources allocated for the action. The collection is keyed by the name as given in the "Resources" tab, the associated value is a resource instance providing the concrete values of the resource's skills.

*'''resourceForId''' (idString) retrieves the resource allocated for the idString as given in the "Resources" tab, the returned value is a resource instance providing the concrete values of the resource's skills.

Resource instances respond to the following protocol:

*'''name''' () The name of the resource

*'''skillNamed''' (''nameOrUUID'') Fetch a concrete skill-value of that resource. The argument can be either a skill''s name, or the functional-UUID of the skill element (in the project tree).

*'''skillAttributeNamed''' (''name'') Fetch a concrete skill-attribute-value of the resource
 

==== Test Suite (Project) Functions ====

Every activity, step or action has a reference to its containing project (or library, if imported).
The direct enclosing project/library is returned by the "project()" function, the top level project (i.e. the loaded suite) via the "topProject()" call.
Projects, Test Suites and Libraries are all the same kind of object (i.e. any project can be used as a test suite or imported into another as imported library).

*''aProject''.'''documentation''' () The documentation or nil

*''aProject''.'''functionalId''' () A unique ID which defines this testSuite independent of its name (remains constant after change)

*''aProject''.'''projectsWorkingDirectory''' () Project directory - i.a. all attachments. This directory is created when a project file is loaded and is deleted when expecco is closed. Do not use it for permanently needed files.

*''aProject''.'''modelLanguageStringFor''' (''aString'') translates a string according to the model-language translation table

*''aProject''.'''versionId''' () A unique ID which defines this testSuite in exactly this version. (changed with any edit operation)

*''aProject''.'''elementWithName''' (''aString'') Retrieve an element by name

*''aProject''.'''elementWithId''' (''aUUID'') Retrieve an element by its version id

*''aProject''.'''elementWithFunctionalId''' (''aUUID'') Retrieve an element by its functional id

*''aProject''.'''typeNamed''' (''aTypeName'') Retrieve a datatype. To instantiate a type, write "<code>(self project typeNamed:'Foo') new</code>".
 

==== Testplan Functions ====

*''aTestPlan''.'''documentation''' () The documentation or nil

*''aTestPlan''.'''name''' () The name of the Testplan

*''aTestPlan''.'''tags''' () A collection of tags of the testplan

*''aTestPlan''.'''functionalId''' () A unique ID which defines this testplan independent of its name (remains constant after change)

*''aTestPlan''.'''versionId''' () A unique ID which defines this testplan in exactly this version. (changed with any edit operation)
 

==== Step Functions ====

*''aStep''.'''name''' () The name of the Step

*''aStep''.'''tags''' () A collection of tags of the Step

*''aStep''.'''inputPins'''() A collection with all input pins

*''aStep''.'''inputPinForPinName'''(''inputPinName'') The corresponding input pin. Raises an error, if no such input pin exists.

*''aStep''.'''inputPinForPinName_ifAbsent'''(''inputPinName'', ''ifAbsentValue'') The corresponding input pin. Returns ''ifAbsentValue'', if no such input pin exists.

*''aStep''.'''outputPins'''() A collection with all output pins

*''aStep''.'''outputPinForPinName'''(''outputPinName'') The corresponding output pin. Raises an error, if no such output pin exists.

*''aStep''.'''outputPinForPinName_ifAbsent'''(''outputPinName'', ''ifAbsentValue'') The corresponding output pin. Returns ''ifAbsentValue'', if no such output pin exists.
 

==== Pin Functions ====

The input and output pins can be referenced in elementary code directly by their name.
The name refers to the pin - '''NOT''' the passed value (this allows for the code to check, if a value is present). For indexed pins (i.e. in steps with a variable number of pins), the collection of pins is referred to by the name, and pins are accessed via an index (1..). See more about variable pins in the section below.

===== Common to all Pins: =====
*''pinName''.'''datatype''' () Returns the data type of the pin (Reflection-API)

===== Input Pins: =====

*''pinName''.'''hasValue''' () Returns true if the pin has received a value (useful to determine if there is a value if the trigger condition is "AndConnected" or "Or")

*''pinName''.'''hasEnvironmentFreezeValue''' () Returns true if the pin has a freezeValue from an environment

*''pinName''.'''hasFreezeValue''' () Returns true if the pin has a freezeValue

*''pinName''.'''isConnected''' () Returns true if the pin is connected (but not frozen)

*''pinName''.'''value''' () Returns the value of the pin. This is either the value received via a connection, or a constant freeze value, or an environment variable freeze value. Raises an error if the pin did not receive any value.

*''pinName''.'''valueIfPresent''' () Returns the value of a pin or nil if the pin did not receive any value. Similar to "<code>value()</code>", but avoids the exception.

*''pinName''.'''valueIfAbsent''' (''alternativeValue'') Returns the value of a pin or the alternativeValue, if the pin did not receive any value. Similar to "<code>value()</code>", but avoids the exception.

*''mbxPinName''.'''waitForValue''' () - ''Mailbox pins only'' The pin has to be a mailbox pin. The execution of this action will be suspended until the pin receives a value.

*''mbxPinName''.'''waitForValueWithTimeout''' (''seconds'') - ''Mailbox pins only'' Like above, but the execution will only wait for the specified time limit, given in seconds. The parameter is typically an integer, but can also be a fraction (e.g. 1/3) or a floating-point number (e.g. 0.3).

*''mbxPinName''.'''consumeValue''' () - ''Mailbox pins only'' Consumes the current value which is present at the mailbox input pin. If there is another pending input value, <code>hasValue()</code> will continue to return true, and <code>value()</code> will return the next pending value.

===== Output Pins: =====

*''outPinName''.'''isBuffered''' () True if the pin is buffered (only generates a value if the action completes successful)

*''outPinName''.'''isConnected''' () Returns true if the pin is connected. This can be used to not perform expensive computations in an elementary action, iff no-one is interested in that value.

*''outPinName''.'''value''' (''data'' ) Writes the value. If the output pin is unbuffered and connected to another step's input pin, the other step's action may be triggered (if the other step's trigger condition is fulfilled). If the output pin is buffered, the datum will be passed to the connected input, when the action has finished with success.

===== Variable Input Pins =====

Elementary steps can have a variable number of input pins, if the pin's schema has the "variable pin" attribute set. To change the number of pins of a step in the diagram editor, pull the pin-handle of a placed step, to add or remove pins. In elementary code, the following API call entries (to the variable pin) are provided to deal with this situation:

*''pinName'' now refers to a collection of pins, representing the set of pins actually present at the step. In contrast to regular pins, where pinName refers to a single pin.

*''varPinName''.'''numberOfVariablePins''' () returns the number of actual pins present in the step for the (variable) schema pin named "pinName"

*''varPinName''.'''size''' () same as the above "numberOfVariablePins"

*''varPinName''.'''inputPinAt''' (''idx'') returns the idx'th actual pin of the schema pin named "pinName". Notice this retrieves the pin for reflection queries, NOT the pin value. To get value or query if it has a value, call ''valueAt:''() / ''hasValueAt''(). Pin indexing starts with 1.

*''varPinName''.'''at''' (''idx'') same as inputPinAt(''idx'')

*''varPinName''.'''hasValueAt''' (''idx'') true if the idx'th variable pin is connected and has received a value. Same as <code>hasValue()</code> for variable input pins. Indices start with 1.

*''varPinName''.'''values''' () Retrieves the values passed to the pins as an array. The array contains nil entries for disconnected pins and those without a value

*''varPinName''.'''valuesPresent''' () Retrieves the values as present; skips unconnected pins or those without a value.

*''varPinName''.'''valueAt''' (''idx'') to get the idx'th pin's value; raises an error if no value was given or pin is not connected. Same as <code>value()</code> for variable input pins.

*''varPinName''.'''valueIfPresentAt''' (''idx'') to get the idx'th pin's value, or nil if no value was given or pin is not connected

*''varMbxPinName''.'''waitForValueAt''' (''index'') -''Variable mailbox pins only'' Same as <code>waitForValue()</code> for variable input mailbox pins.

*''varMbxPinName''.'''waitForValueAt_withTimeout''' (''index'', ''seconds'') - ''Variable mailbox pins only'' Same as <code>waitForValue()</code> for variable input mailbox pins.

*''varMbxPinName''.'''consumeValueAt''' (''index'') - ''Variable mailbox pins only'' Same as <code>consumeValue()</code> for variable input mailbox pins.

===== Variable Output Pins =====

Starting with expecco v2.1, steps can also have a variable number of output pins, if the schema has the "variable output pin" attribute set. To change the number of pins, pull the pin-handle of a placed step, to add or remove pins. In elementary code, the following API call entries (to the variable pin) are provided to deal with this situation:

*''varPinName''.'''numberOfVariablePins''' () returns the number of actual pins present in the step for the (variable) schema pin named "pinName".

*''varPinName''.'''outputPinAt_value''' (''idx'', ''value'') write a value to the idx'th output pin. Index starts with 1.

*''varPinName''.'''outputPinAt''' (''idx'') returns the idx'th actual pin of the schema pin named "pinName". Notice that this retrieves the pin; to write an output value to it, call ''value''(v) on the returned pin.

*''varPinName''.'''at''' (''idx'') same as outputPinAt(''idx'')

*''varPinName''.'''outputPins''' () returns a collection of all actual pins present in the step for the (variable) schema pin named "pinName".

 

==== Datatype Functions ====

A datatype can be retrieved by asking a pin for its datatype using the '''datatype''' () function.
This is sometimes useful in elementary code, in order to instantiate a new value (given the pin) or to ask for details of the type.

*''aType''.'''name''' () The name of the Datatype

*''aType''.'''isAnyType''' () true if the datatype is the builtin "Any" type

*''aType''.'''isArrayType''' () true if the datatype is an "Array" type (with any element type)

*''aType''.'''isCompoundType''' () true if the datatype is a compound (structure) type

*''aType''.'''isEnumType''' () true if the datatype is an enumeration type

*''aType''.'''isPrimaryType''' () true if the datatype is any builtin primary type

*''aType''.'''isRangeType''' () true if the datatype is a subrange of another type

*''aType''.'''isTupleType''' () true if the datatype is a tuple type

*''aType''.'''isUnionType''' () true if the datatype is a union type

*''aType''.'''isStringPrimaryType''' () true if the datatype is the builtin "String" primary type

==== Enum Type Functions ====

*''anEnumType''.'''values''' () returns an array of enum-value names (symbolic)

*''anEnumType''.'''integerValueOf''' (''elementName'') returns the associated integer value.

==== Compound Type Functions ====

*''aCompoundType''.'''namedFieldDescriptions''' () returns an array of descriptions of the named fields (if any)

*''aCompoundType''.'''indexedFieldDescriptins''' () returns a description of indexed fields (if any)

Each field description can be asked for the "fieldName()", "fieldType()" and "defaultValue()".

==== Primary Type Functions ====

*''aPrimaryType''.'''typeClass''' () returns the underlying Smalltalk class, of which values are instances of.

==== Range Type Functions ====

*''aRangeType''.'''baseType''' () returns the underlying base type. Typically this will be the Integer primary type.

*''aRangeType''.'''minValue''' () returns the minimum value of the range

*''aRangeType''.'''maxValue''' () returns the maximum value of the range
 

==== Functions for Any Tree- or Diagram Element ====

These include: BlockDescriptions, Types, TestPlans, TestCases, Steps, Connections, Pins, Annotations etc.

*''object''.'''versionId''' A globally unique identifier (GUID or UUID) which is changed with every modification of the item

*''object''.'''functionalId''' A globally unique identifier (GUID or UUID) which is assigned once-and-for-all to the item

*''object''.'''id''' alias for versionId().

*''object''.'''tags''' A collection of tags.

*''object''.'''isAnnotation''' true, if it is an annotation (in a diagram)

*''object''.'''isStep''' true, if it is a step (in a diagram)

*''object''.'''isConnection''' true, if it is a connection (in a diagram)

*''object''.'''isBlockDescription''' true, if it is a block description (in the tree)

*''object''.'''isAttachment''' true, if it is any attachment (in the tree)

*''object''.'''isFileAttachment''' true, if it is a file attachment (in the tree)

*''object''.'''taggedValueAt''' (''aKey'') To retrieve a tagged value. These are usually preserved when objects are transported to/from other systems.

*''object''.'''taggedValueAt_put''' (''aKey'', ''anObject'') to change a tagged value. Only a limited set of datatypes are supported: anObject must be a '''String''' or a '''Number'''.

*''object''.'''propertyAt''' (''aKey'') to retrieve an expecco property. These are expecco-internal properties. These are usually not recognized by other systems.

*''object''.'''propertyAt_put''' (''aKey'', ''anObject'') to set an expecco property. These are usually not recognized by other systems. Only a limited set of datatypes are supported: anObject must be a '''String''' or a '''Number'''.
 

== Groovy Elementary Blocks ==

Groovy is an open source interpreter and compiler for a Java like scripting language which runs on top of the Java Virtual machine. For details, visit [http://groovy-lang.org/ "groovy-lang.org"] and especially the [http://groovy-lang.org/documentation.html Groovy Documentation Portal].

Code written as a Groovy elementary block is not executed directly by expecco. Instead, the code is forwarded to a Groovy shell which runs inside a Java Virtual Machine (JVM). This may be a local JVM, whose sole purpose is to provide additional utility functions or which provides an interface to the actual system under test (SUT), or it may be the JVM which executes the tested application and is running physically on the SUT.

By using Groovy blocks, expecco's basic black-box test functionality is extended to include powerful gray- and white-box tests. You can access the internals of objects inside the SUT, call its functions and even define new classes and functions and call them. Groovy is especially useful, if you have to install callback- or hooks inside the SUT, which interact back to expecco (e.g. to collect SUT-internal events and allow expecco to read those from the SUT). However, you should keep in mind that your tests may become affected by changes in the SUT and needs to be modified if interfaces change (which is a general property of white box tests, not a limitation of expecco).

The machinery to interact with a JVM (and therefore to execute Groovy code blocks) requires the Java Bridge plugin, which is now (rel18.1) part of the basic expecco package. Groovy itself is available for free as a jar class library, which is loaded with or into the target application. The Java Bridge plugin already includes a prepackaged Groovy interpreter which can be loaded transparently into the SUT application whenever a Groovy block is executed. So except for the setting of the JVM path, no further setup or installation is required.

=== Why use Groovy Elementary Blocks? ===
The Java Bridge and especially Groovy code is very useful when testing GUI frameworks, communication protocols or machine control soft- and hardware which is written in Java. Especially, if you have to call functions internal to the SUT in order to trigger actions or if you need to be informed about state changes via listeners or callbacks, Groovy is the perfect tool for the task. Note that calls into the JVM are relatively straight forward, using the method forwarding mechanism, even from Smalltalk code. However, callbacks and listeners, which usually have to be implemented as instances of special derived classes of a an abstract framework class, are hard to realize without Groovy.

Without Groovy, you would have to add such classes to the software inside the SUT - e.g. by adding them to the tested software's jar packages, or by adding extra jar packages. In addition, you'd have to provide a communication mechanism (socket, pipe or file interchange), by which your test action is able to retrieve this information.

=== What is the Difference between a regular (expecco-) JavaScript Block and a Groovy Block? ===

In one sentence: expecco JavaScript actions are executed inside expecco, Groovy actions inside the SUT (System Under Test) or any other external JVM (Java Virtual Machine).

More detailed:

Expecco's JavaScript actions are actually alternative syntactic forms of Smalltalk actions. When executed, they run inside the expecco executable and have access to any class or object inside expecco itself, or those which are passed in via input pins or environment variables.

On the other hand, Groovy actions are "''injected''" (eg. downloaded) into a Java VM and execute in that object space. They cannot directly access expecco classes or objects, but instead can access all public classes and objects within the JVM in which they run, which can be the SUT (System Under Test). By means of proxy objects (which are forwarding operation-calls), expecco can deal with remote objects almost transparently: these can be returned from a Groovy action to expecco, and later be used again as arguments to other Groovy actions; i.e. they can be passed around via output- and input pins, stored in variables and inspected.

=== What is the Difference between a Groovy Block and a Bridged Node Block? ===

Groovy blocks execute inside a JVM (Java Virtual Machine) and can access any Java code (eg. classes inside a java application or inside a dynamically loaded jar-library).

In contrast, Node actions are executed inside a Node (aka "Node.js") interpreter (which is not a JVM).

There are also slight differences in the syntax: Groovy is more Java-like, whereas Node blocks use pure JavaScript.

=== Groovy Compilation Mechanism and Performance Issues ===
When a Groovy action is executed for the very first time, the block's code is transmitted via the bridge to the Groovy shell on the target JVM as a string. There, the code is parsed and an anonymous jar is created, containing Java byte code. Thus, there is some initial overhead involved in both sending the code and more so in compiling the code in the JVM. However, for every followup call, the JVM will directly call the generated code and run at full Java speed (i.e. the execution speed is almost as if native Java code was executed), although there is still some overhead due to the interprocess communication (typically a few milliseconds for every call)

=== Using a Single Local JVM Connection / Executing Groovy Actions on the Local Machine ===
By default, a Groovy action is executed on a JVM which runs on the local machine; i.e. the machine on which expecco itself is running.
With the execution of the very first Groovy action, a JVM is started as defined in the expecco settings dialog, then a bridge connection is established to that JVM, and the Groovy interpreter (called "''GroovyShell''") is loaded and instantiated on the JVM. Then a reference to that GroovyShell object is remembered and used for all followup Groovy actions which are to execute on that local JVM.
This default behavior is convenient if you want to use Java support libraries for reporting, statistics or other computations, or if your SUT is running inside a local JVM, or if you want to call interface functions (protocols) which actually talk to your SUT.

=== Using a Particular JVM Connection / Executing Groovy on a Possibly Remote Machine ===
If you either need to customize the JVM startup and/or your test scenario has to talk to one or multiple remote systems (or multiple java programs within one scenario), you have to setup multiple java connections, and pass the connection to use to your Groovy actions.
This can be done either via an input pin, or via an expecco environment variable.
The algorithm to provide this is as follows:

* if the action has a pin named "<code>groovy</code>", and it is connected, that pin's value is used as GroovyShell handle
* otherwise, if the environment contains a variable named "<code>GROOVY</code>", that variable's value is used
* otherwise, a new GroovyShell is instantiated and used, on the JVM which is given by:
** if the action has a pin named "<code>java</code>", and it is connected, that pin's value is used as Java Bridge handle
** otherwise, if the environment contains a variable named "<code>JAVA</code>", that variable's value is used
** finally, otherwise a local JVM connection is used (a shared singleton connection).

This scheme makes the most common case easy, where only one single local JVM is required,
but still allows the flexibility to handle multiple JVMs and even multiple different GroovyShell instances within each JVM.

To use input pins, you have to create corresponding pins manually, and the pin names MUST be "java" / "groovy".
You cannot use these two reserved names as regular input pin names.

=== Choosing another JVM Version ===
By default, the Groovy interpreter runs in the default Java virtual machine. That is the JWM which would be executed when
entering "<CODE>java</CODE>" on the command line. To verify the version, open a command shell (or cmd.exe window) and enter
java -version

To specify another JVM, go to "''Extras''" → "''Settings''" → "''Plugins''" → "''Java Bridge''",
and enter the path to a JRE (Java Runtime Environment) folder into the "''Java Installation Path''" field.
You can also enter a JDK (Java Development Kit) folder name into that field. See also [[Settings_JavaBridgeSettings]].

=== Additional JAR Class Libraries ===
By default, the Groovy code runs inside a JVM which has its classPath initialized from the preferences.
These class path preferences can be changed in the "''Settings''" → "''Project Management''" → "''Groovy Class Path''" settings dialog.
Additional jars can be added to the common classPath (before a JVM is started) by the "[''Add JAR to Groovy Class Path'']" action,
or dynamically to a concrete already running JVM instance via the "[''Add JAR to JVM'']" action.

Notice that you have to restart existing groovy connections to make such changes effective (via the "''Extras''" → "''Debugging''" → "''Shut Down Bridge Connections''" menu function).

=== Groovy Code Snippets / Examples ===
==== Calling Existing Code in the System Under Test (SUT) via a Groovy Action====

A Groovy block's code looks very similar to a regular JavaScript block's code (with some differences in the Groovy language).
However, it is executed inside a JVM, which may be inside the SUT.
It can therefore instantiate Java objects and call static and member functions inside the target system, if it is programmed in Java.

For example, too call a static function named "''foo''" in a class named "''MyTestClass''", use the following Groovy block:

def execute() {
MyTestClass.foo("hello world");
}

if the class is located in another package (or especially: in one of your own),
use explicit package prefixes:
def execute() {
javax.swing.JFrame frame = new javax.swing.JFrame();
javax.swing.JButton button = new javax.swing.JButton( "Press Me" );

frame.add(button);
frame.setSize(300,100);
frame.setVisible(true);
}
or an import declaration:

import javax.swing.*;

// end of import definitions

def execute() {
JFrame frame = new JFrame();
JButton button = new JButton( "Press Me" );

frame.add(button);
frame.setSize(300,100);
frame.setVisible(true);
}
Notice that you may not remove the comment line starting with "// end of....".
 This separator pattern has been hardcoded into the Groovy machinery to separate any class and import
definitions from the execution method.

==== Defining a New Class in the System Under Test using Groovy ====
[[Bild:Groovy_Defining_Class1.png|thumb|300px|Drag this image into expecco]]
You can define your own classes in a Groovy block:

For demonstration, let's start with a simple running example:
class TestSleep {
static void main(String[] args) {
println 'Step 1'
sleep(1000)
println 'Step 2'
sleep(1000)
println 'Step 3'
}
}

// end of definitions -- do not remove this line unless imports above is empty

def execute() {
TestSleep.main(null);
}

Instances of new classes may be required especially to install listeners and callbacks when testing UI or server applications. A typical scenario is when you want expecco to be informed about mouse or keyboard events (MouseListener).

Usually, instances of such classes are created in one Groovy action,
and passed to expecco via an output pin:

class MyClass extends Object {
Object someState;

def set_someState(Object newValue) {
someState = newValue;
}
def get_someState() {
return someState;
}
def String toString() {
return "a very\nlong\nmultiline\na\nb\nstring\n";
}
}

// end of local definitions

def execute() {
outputPin.value( new MyClass() );
}

Then, additional Groovy actions take that as an input value and call the classes methods:
def execute() {
Object myInst = inputPin.value();

myInst.setSomeState(123);
}

or:
def execute() {
Object myInst = inputPin.value();

output.value( myInst.getSomeState() );
}

==== Defining a Listener Class in the System Under Test using Groovy ====
A common pattern in Java communication frameworks is to define an abstract classes or interfaces which has to be subclassed by users of the framework. This pattern is common for callbacks or event listeners. The programmer has to define a listener class, create an instance of it, and register it towards the communication framework. To interact with such a framework in expecco, you will need a listener class, which responds to callbacks from the framework and either remembers them for later queries from a testcase's activity, or by directly calling back into expecco. The later is much harder to deal with, as those callbacks may come at any time, even when the test has already finished or the test is being debugged (remember that the JVM may run independent from expecco). So synchronization issues may be hard to solve. It is much easier and recommended to implement the first approach: the listener collects incoming events, until expecco is ready to process them.

You will need an elementary Groovy block to instantiate and register the listener towards the framework similar to the conceptual code below:
// a Groovy Elementary Block

import <interface or abstract class from which to inherit>;

class MyListener extends AbstractListener {
ArrayList eventQueue = new ArrayList();
Object eventNotifier = new Object();

/**
 * Called from a framework when an event occurs.
 */
public void onExampleEvent(Object event) {
synchronized (eventQueue) {
eventQueue.add(event);
}
synchronized (eventNotifier) {
eventNotifier.notifyAll();
}
}

/**
 * Called from expecco to fetch next event.
 *
 * Of there is no event in the queue, blocks
 * until an event arrives (by means of #onExampleEvent())
 */
public Object getNextEvent() {
while (true) {
synchronized (eventQueue) {
if (! eventQueue.isEmpty()) {
return eventQueue.remove(0);
}
}
synchronized (eventNotifier) {
try {
eventNotifier.wait();
} catch (InterruptedException ie) {
// Pass, try again
}
}
}
}
}

// end of local definitions

// called from expecco, to instantiate a listener
def execute() {
var theListener = new MyListener();

framework.registerListener ( theListener );
outputPin.value( theListener ); // return it to expecco
}

Make sure that the above elementary code is called from your activity diagram in the initialization/setup phase, and that the returned listener reference is either remembered in an environment variable of your suite, or passed down to the actual test case via input/output pins.

Define an additional elementary block (here in JavaScript, but could also be Smalltalk or Groovy), which takes the listener as input pin and fetches the next event via <code>getNextEvent()</code>:

// a JavaScript Elementary Block

execute() {
var theListener;
var event;

theListener = inPin.value();
event = theListener.getNextEvent();
outpin.value ( event );
}
The above code blocks the test suite until an event arrives. It may be useful to add another method to query the number of received events, or to flush any previously received and already enqueued events.

In your test case, perform any stimulation required to make the framework generate an event, so that the listener's framework entry is called.
Then, invoke the #getNextEvent() action to suspend execution until an incoming event arrives (you will probably set a [[DiagramElements-Pin#Timelimit Input Pin|time limit]] on that step's execution). Once this action finishes, the event is available in expecco as a reference to the real event object (remember: the event object is an object inside the remote Java machine, so what you have in expecco is a handle to that remote object).

All getters, setters and other methods of the event's implementation can be invoked from elementary code (any of the programming languages can do that, due to the message forwarding of the bridge).

For example, assuming that the event provides getEventID() and getMessageString() getters,
which can be called from a Smalltalk action with:
id := theEvent getEventID. msg := theEvent getMessageString.
and from a JavaScript action or from another Groovy action witht:
id = theEvent.getEventID(); msg = theEvent.getMessageString();.

Also, the expecco object inspector has been enhanced to recognize those proxy bridge objects, and presents the internal state, inheritance and class protocol in a multitab fashion. This makes looking into those remote objects almost as comfortable as looking into local ones.

==== Accessing JMX MBeans ====

import java.lang.management.*

// end of definitions

def execute() {
def os = ManagementFactory.operatingSytemMXBean;
def mem = ManagementFactory.memoryMXBean;

Transcript.showCR("OS architecture: " + os.arch.toString() );
Transcript.showCR("MEM heapUsage : " + mem.heapMemoryUsage.toString() );
Transcript.showCR("POOLS:");
ManagementFactory.memoryPoolMXBeans.each { eachPool ->
Transcript.showCR(" pool name : " + eachPool.name.toString() );
Transcript.showCR(" pool peakUsage: " + eachPool.peakUsage.toString() );
}
}
Please refer to the corresponding Java documentation for details.

==== Executing Jython, JRuby or other Script Code inside the JVM ====

[[Datei:bulb.png|16px]] the following example is somewhat outdated due to the new builtin support for jython (in 19.2).

The following example executes Jython (Python) code inside the JVM (please make sure that the jython jar is in your Groovy class path):
import org.python.util.PythonInterpreter;
import org.python.core.*;

// end of definitions -- do not remove this line unless imports above is empty

def main()
throws PyException
{
Properties p = new Properties();
// p.setProperty("sys.path", "/Users/cg/work/exept/bridgeFramework/javaBridge/javaBin/jython2.7.0");

p.setProperty("python.path", "<path to jython2.7.0/Lib>");
p.setProperty("python.home", "<jython2.7.0>");

Object props = System.getProperties();
// String[] args = new String[0];
String[] args = { "" };
PythonInterpreter.initialize(props, p, args);

PythonInterpreter interp =
new PythonInterpreter();

System.out.println("Hello, brave new world");
interp.exec("import sys");
interp.exec("print sys");

interp.set("a", new PyInteger(42));
interp.exec("print a");
interp.exec("x = 2+2");
PyObject x = interp.get("x");

System.out.println("x: "+x);
System.out.println("Goodbye, cruel world");
}

def execute() {
main();
}
Of course, you can also write the "interp" instance to an output pin, and remember it somewhere or pass it to other actions. Then, other actions can directly invoke the "exec(...)" function, without instantiating a new interpreter.

=== Groovy Datatype Limitations ===

==== Integer types ====
As Groovy dynamically compiles to plain Java bytecode and executes on top of a regular JVM, the integer range is limited to 32bit (64bit for "long int" types).
No automatic conversion between small and large integers is performed. If required, you will have to use a BigNum package and/or cast int to long int. There is currently no automatic conversion or transparent support to pass large numbers from expecco to Groovy and vice versa. Integers passed from Java to expecco will be represented as instances of the Integer type there.

==== Limited Object Conversion to/from Groovy ====
Some limited form of object conversion is automatically performed when passing expecco's Smalltalk objects to Groovy, and back when returning values from Groovy. This conversion especially affects values passed to/from pins of a Groovy action.

The following table summarizes the conversion process:
{| Border
! from Smalltalk
! to Java and from Java
! to Smalltalk
!
|-
| String
| String
| String
|-
| Integer (up to 32/64 bit)
| int, long int, boxed Integer
| Integer
|-
| Float, Double
| float, double; boxed or unboxed
| Float (Notice that Smalltalk Floats have double precision)
|-
| Fraction
| float, double; boxed or unboxed (danger alert: precision may be lost)
| Float (Notice that Smalltalk Floats have double precision)
|-
| Boolean
| Boolean
| Boolean
|-
| Array of any above
| ArrayList of any above
| Array of any above
|-
| other Smalltalk Object(!)
| -
| -
|}

(!) does not work, yet: at the time of writing, Smalltalk objects other than the basic types listed above cannot be passed to Java.
However, the reverse direction is possible, and Smalltalk includes a mechanisms to handle (and even inspect) remote Java objects.

==== No Smalltalk Classes, No Smalltalk Objects in Groovy ====
Of course, no Smalltalk class can be used directly in Groovy code.
And Smalltalk objects can only be passed as opaque handles to/from Groovy as described above.
However, all Java classes are at your hands now!
Some limited interaction with expecco and underlying Smalltalk objects is possible via the "<code>eval()</code>" and "<code>perform()</code>" API described below.

However, in general: if more complex objects need to be interchanged, this must be either done by converting them to an array (of objects), possibly an array of arrays, which is passed to a Groovy "interface function" first, which instantiates the required Java object(s). Or, alternatively to some ASCII representation (XML or JSON, for a more lightweight approach) and convert this back and forth.

=== Handling of Java (and Groovy) Objects in expecco/Smalltalk ===

==== Java Object References (Handles) ====

Groovy elementary function can return references to Java objects via output pins. Because the actual object is located inside a JVM (i.e. outside of expecco), these references are treated like opaque handles by the underlying Smalltalk runtime system. However, a mechanism is provided to allow for almost transparent access to the referenced object's private slots, its classes' static slots, its class hierarchy and method information. The object inspector is able to present that information in a convenient way, similar to how Smalltalk objects are presented. Also methods of the Java object can be called and values returned to expecco.

==== Message Forwarding ====

Smalltalk and JavaScript code can send regular messages to Java objects inside a remote JVM. This is possible via the Smalltalk "<code>doesNotUnderstand:</code>" mechanism, which intercepts any call, sends a message to the real object (via the Java Bridge), awaits an answer and returns the result, which is usually a reference to another Java object.

All of this is transparent to the programmer of the elementary code, except for the fact that Java method naming is different from Smalltalk. And of course a performance penalty, due to the interprocess communication, marshalling overhead and dynamic lookup via reflection on the Java side.

==== Method Name Conversions ====

When a message is sent from Smalltalk code to a Java object, a message translation mechanism similar to the Smalltalk <-> JavaScript mechanism is used:
foo -> foo()
foo:arg -> foo(arg)
foo:a1 _:a2 ... _:aN -> foo(a1, a2, ... aN) where the "_" are arbitrary strings.

thus, to call a Java object's "installHandler(arg1, arg2, arg3)" function, you should write in Smalltalk:
javaObject installHandler:arg1 _:arg2 _:arg3
and in JavaScript:
javaObject.installhandler(arg1, arg2, arg3)

It is obvious, that this kind of code is better written in JavaScript, being the same as a native Java call would look like.

==== Conversion of Dynamic Smalltalk Objects to Static Java Types ====

Inside expecco (which is running under a Smalltalk VM), all object references are dynamically typed.
This means, that in Smalltalk, every object holds a reference to its class and in principle, any object can be passed as argument to
a called function.
In contrast, Java requires the type of a function argument to be declared (either as a class or interface),
and the argument type(s) are part of a method's signature.

Therefore, when calling a Java function from Smalltalk, the correct function must be found by reflection at execution time.

For example, if the Java object provides two methods as in:

public void foo(Integer arg) { ... }

public void foo(Float arg) { ... }

and it is called from Smalltalk with:

aJavaObjectHandle foo: 1

then the "Integer"-argument version of foo must be called.

Whereas if called as:

aJavaObjectHandle foo: 1.0

then the "Float"-argument version is to be called.

For this, the Java Bridge side uses reflection to scan the available methods for a best fit,
and transforms the passed Smalltalk argument to the best matching type before calling the actual function.

There are some rare situations, where this automatic lookup fails or finds a wrong method.
For example, if same-named functions exist with
both a "<code>float</code>" (unboxed) and a "<code>Float</code>" (boxed) argument,
and you need to make sure which is called.
In such cases, you can either use a Groovy block as mediator, which calls the desired function with an explicitly casted argument, and call the Groovy block from Smalltalk (or JavaScript) or use an explicit cast operation ("<code>Bridge2::Cast object:o as:typeName</code>").

==== Current IDE Limitations ====

The Smalltalk IDE has currently only limited support to extract and present Java's static type information. Currently, there is no class- and function name completion in the editor, making elementary code development for Java/Groovy less pleasant. Therefore, for complicated setups, it is a good idea to open a specialized Java development environment (e.g. eclipse) in parallel, and test the setup code there before copy-pasting it into a Groovy block.

Eclipse is also useful to find out class- and method names during development.

=== Groovy Code API ===

Groovy code supports a '''subset''' of the above activity functions, which is intended provide an interface similar to the JavaScript and Smalltalk elementary code API. Of course, technically for every API function below, the elementary code executing in the remote Java VM has to make a remote procedure call back to expecco. On the JVM side, this is done very similar to the above described remote message mechanism, when messages are sent from Smalltalk to Java/Groovy. However, due to the static type system, it is not possible to call previously unknown interfaces. Therefore, only a fixed set of API entry points is supported.

==== Attention / Warning (Groovy) ====

Unless explicitly prevented by the "<code>mayStillDoExpeccoCalls()</code>" function ([[#Special_Functions (Groovy) |described below]]),
all called expecco functions listed below will ONLY work as expected WHILE the Groovy action is still ACTIVE (i.e. while inside the Groovy "<code>execute()</code>" function).

The reason is that expecco ensures that handlers, which are responsible for transferring information from the Groovy code back to expecco,
will always be released, when the Groovy step has finished its execution.
This is mostly required to prevent memory leaks in the Java VM, because the observer instance object is registered inside the JVM and would remain there forever, if not unregistered. This observer object is a proxy for Java code, which implements all the functions below and forwards them (via an IPC mechanism) to expecco. One new such object is required for every Groovy action execution and if not released, they sooner or later consume huge amounts of JVM memory. Therefore by default, the observer is released after the Groovy action execution.

In most Groovy blocks this is not a problem, except for those which install callback methods,
AND those callbacks get called AFTER the Groovy block has finished (for example by another Java thread),
AND the callback code calls one of those expecco interface functions. This includes the Transcript output functions, notifications and pin value writers.

Unless the observer is still around, callbacks are ignored and behave like a no-operation, if called after the step has finished.
Of course, writing to a pin from within a callback AFTER the execute() function has finished does not work in any case (with or without a kept observer). The behavior in this case is undefined; currently, it is a no-operation, but it may be changed to raise an error in future versions.

==== The Current Activity (Groovy) ====
The current activity instance is accessed as "''this''" inside the Groovy action code (like in an elementary JavaScript block). For every executed action, a new activity object is instantiated. It is usually alive during the execution only (i.e. it is destroyed and its memory reused automatically, after the block's action has finished).

In Groovy (as in JavaScript or Java), if no receiver is given for a function call, "''this''" is the implicit receiver. Thus the statements "<CODE>this.logInfo("hello")</CODE>" and "<CODE>logInfo("hello")</CODE>" are equivalent.

==== Objects are passed by Reference ====
Except for Strings and Numbers, objects are passed from Groovy to expecco by reference. These references can later be sent back to other Groovy actions transparently. Notice, that these references will keep the Groovy object (which is actually a Java object) alive until the reference object is garbage collected in expecco. Be aware that such references may have a very long life time, if kept in an activity log. Therefore, output pins which receive such references should either be marked as non-logging, or you should set the "''Log Strings of Bridge Objects''" flag in the [[Settings_LoggingSettings/en||"''Settings''" - "''Execution''" - "''Logging''" dialog]].

==== Reporting (Groovy) ====

*'''error''' () Report a defect (in the test). Stops execution.

*'''error''' (''infoString'') Report a defect (in the test). Stops execution. The infoString argument will be shown in the activity log.

*'''fail''' ([''infoString'']) Report a failure (in the SUT) with optional infoString. Stops execution.

*'''inconclusive''' ([''infoString'']) Report an inconclusive test (with optional infoString). Stops execution.

*'''activitySuccess''' ([''infoString'']) Finishes the current activity with success.

*'''pass''' ([''infoString'']) Finishes the current testCase with success. The optional infoString argument will be shown in the activity log.

*'''testPass''' ([''infoString'']) Same as pass(); for compatibility with bridged languages where "pass" is a reserved keyword (i.e. python).
 

==== Logging (Groovy) ====

*'''logError''' (''messageString'') Adds a error message to the activity log.

*'''logError''' (''messageString'', ''detail'') Adds a error message to the activity log.

*'''logWarning''' (''messageString'') Adds a warning to the activity log.

*'''logWarning''' (''messageString'', ''detail'') Adds a warning to the activity log.

*'''logInfo''' (''messageString'') Adds an info message to the activity log.

*'''logInfo''' (''messageString'', detail) Adds an info message to the activity log.

*'''alert''' (''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "[[Settings_LoggingSettings/en|Execution-Log-Settings]]" dialog (by default it is disabled).

*'''warn''' (''messageString'') Same as ''alert()'' (for Smalltalk protocol compatibility).
 

==== Reflection, Information, Queries and Accessing (Groovy) ====

*'''environmentAt''' (''anEnvironmentVarName'') The value of an environment variable

*'''environmentAt_put''' (''anEnvironmentVarName'', ''value'') Changing the value of an environment variable.

*'''nameOfActiveTestPlan''' () The name of the currently executing text plan

*'''nameOfActiveTestPlanItem''' () The name of the currently executing text case

*'''nameOfStep''' () The name of the corresponding step of the activity
 

==== Interaction with Expecco and Debugging (Groovy) ====

*'''eval''' (''smalltalkCodeString'') Evaluate a piece of Smalltalk code inside expecco.

*'''evalJS''' (''javascriptCodeString'') Evaluate a piece of JavaScript code inside expecco.

*'''inspect''' (''javaObject'') Opens the expecco-inspector showing details of the argument object.

*'''halt'''() or '''halt'''(''message'') stops (breakpoint) and opens the expecco-debugger; however, this debugger cannot show the internals of the suspended Groovy code, but will only present the expecco calling chain up to the bridge call.

 

==== Special Functions (Groovy) ====

*'''mayStillDoExpeccoCalls''' (''boolean'') Ensures that the API-functions described here will still be callable (by Java callback functions from other threads) even after the step has finished execution. In other words, it prevents releasing the observer object which is responsible for the transfer of information between the two systems. Be aware that this object remains and will never be released, until the bridge connection is closed. I.e. there is a potential for a memory leak inside the Java VM here.
:Even with mayStillDoExpeccoCalls(true), only functions which are not depending on the step's activity may be called after the activity has finished. This includes event, logging and transcript/stderr functions, but no pin access or verdict reporting functions.
 

==== Pin Functions (Groovy) ====
Currently, Groovy blocks do not support a variable number of input or output pins.

Attention:
 Groovy uses many more reserved keywords for syntax than JavaScript or Smalltalk. These keywords cannot be used as pin names, and you will get a syntax error ("<foo> token not expected") if you try. Be careful to not name your pins as any of: "in", "return", "class", "private", "public", etc. As a proven best practice, add a "Pin" suffix to your pin names (i.e. name it "inPin", instead of "in").

===== Input Pins (Groovy) =====

*'''hasValue''' () Returns true if the pin has received a value

*'''value''' () Returns the value of the pin. Raises an error if the pin did not receive any value.

*'''valueIfAbsent''' (''alternativeValue'') Returns the value of a pin or the alternativeValue if the pin did not receive any value.
 

===== Output Pins (Groovy) =====

*'''isBuffered''' () True if the pin is buffered


*'''value''' (''data'') Writes the value.
 

==== Transcript, Stderr and Stdout (Groovy) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from Groovy code. However, only a limited subset of messages is supported:

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show''' (''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

*'''showCR''' (''arg'') A combination of show(), followed by a linebreak.

*'''writeLine''' (''string'') For compatibility with Java's PrintStream protocol.

*'''print''' (''string'') For compatibility with Java's PrintStream protocol (expecco 2.8).

*'''println''' (''string'') For compatibility with Java's PrintStream protocol (expecco 2.8).

*'''println''' () For compatibility with Java's PrintStream protocol (expecco 2.8).

In addition, stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").
 

== Node.js (Bridged) Elementary Blocks ==

Node.js is an open source interpreter for JavaScript. For details on the language and libraries, visit [https://www.w3schools.com/nodejs "NodeJS Tutorial"] .
 You have to download and install "node" separately - the interpreter is not part of the expecco installation procedure (see [[Installing_additional_Frameworks/en | "Installing additional Frameworks"]]) and [https://nodejs.org/en/download/ https://nodejs.org/en/download] ).

Node.js code execution in expecco is supported via 2 different mechanisms:
* Node.js Bridged Action Blocks - these look at the outside like regular action blocks with typed input and output pins, which are available inside the action's code via "<code>.value()</code>" APIs. The bridge-partner in which the code is to be executed is started once and will remain an active process until terminated. Any state (data) created inside the bridge remains alive while the partner is running and the connection is alive.
* [[ElementaryBlock_Element/en#Node.js-Script_Blocks | Node.js-Script Action Blocks]] - these look like shell-script blocks, in that the standard input and output is used to interact with the script. For every individual script action, the script interpreter is started anew. No state is alive between and across actions (the script-interpreter is terminated after each action)

The following describes the first kind of blocks (bridged). Node.js-Script blocks are described elsewhere, in the [[ElementaryBlock_Element/en#Node.js-Script_Blocks | Node.js-Script Blocks]] chapter.

Code written as a Node.js elementary block is not executed directly by expecco. Instead, the code is forwarded to a node interpreter. This may be a local node process, whose sole purpose is to provide additional utility functions or which provides an interface to the actual system under test (SUT), or it may be on a remote system.

=== NodeJS Datatype Limitations ===
Because expecco objects and Node objects live in different processes,
no direct object access is possible between the two partners.
When objects are passed via an input pin from expecco to Node, or via an output pin from Node to expecco, the object is either converted to JSON on the sender side and reconstructed on the receiver side, or it is passed by reference, in that the sender transmits a "handle" (which is some unique number) to the partner.

Since the class system / object model is different, not all objects are exactly representable on the other side, and some information may be lost. If required, additional information must be explicitly passed (eg. by generating a string representation ''manually'').

==== Limited NodeJS Object Conversion ====
Some limited form of object conversion is automatically performed when passing expecco's Smalltalk objects to NodeJS, and back when returning values from NodeJS. This conversion especially affects values passed to/from pins of a NodeJS action.

The following table summarizes the conversion process:
{| Border
! from Smalltalk
! to NodeJS and from NodeJS
! to Smalltalk
!
|-
| String
| String
| String
|-
| Float (node ONLY supports IEEE double numbers)
| Float
| Float
|-
| Float, Double
| Float
| Float (Smalltalk Floats have double precision)
|-
| Fraction
| Float
| Float (Smalltalk Floats have double precision)
|-
| Boolean
| Boolean
| Boolean
|-
| Array of any above
| Array of any above
| Array of any above
|-
| -
| any
| any NodeJS object as Reference via "<code>makeRef(obj)</code>" fetch in Node via "<code>inpin.refValue()</code>"
|-
| Filename
| String (i.e. pathname)
| String
|-
| arbitrary Smalltalk Object (!)
| Object with slots
| Dictionary with slots
|}

(-) does not work. In general, only objects which can be represented by JSON can be transmitted between expecco and the node action.

==== No Smalltalk Classes, No Smalltalk Objects in NodeJS ====
Of course, no Smalltalk class can be used directly in NodeJS code.
And only a subset of Smalltalk objects (those which can be represented as JSON string) can be passed to/from NodeJS as described above.
However, all node.js code (packages/modules) are at your hands now!

In general: if more complex objects need to be interchanged, this must be either done by converting them to an array (of objects), possibly an array of arrays.
Or, alternatively to some ASCII representation (XML or JSON, for a more lightweight approach) and convert this back and forth.

It is also possible to pass Node-object-references from the Node interpreter to expecco, and pass it back to the Node interpreter later (usually in another action).
This is used to get connection, protocol or device handles from Node, and pass them to other (transmission or control) actions later.

==== Limited Error Reporting ====
Notice, that arithmetic errors are usually not reported by Node.
Dividing by zero or taking the logarithm of a negative number will deliver a Nan ("Not a Number") instead of raising an error. Thus you have to explicitly check the result from such computations in your code (this is different in expecco's builtin JavaScript actions, where an error is reported).

=== Debugging NodeJS Actions ===
Some debugging facilities are provided to support development of Node code.
If your code contains an endless loop, you can interrupt the Node interpreter
(via the "''Interrupt Execution''" button at the top right)
and get a debugger window, showing the call stack and local variables.

However, there are situations, when the Node interpreter gets completely locked up and ceases to react.
In this situation, you will have to shut down the Node interpreter via the "''Plugins''" → "''Bridges''" → "''Node JS''" → "''Close Connections''" menu function.
Of course, this also implies, that any state inside the Node interpreter is lost, and you'll have to rerun your test setup from the start.

===== Debugger Functions =====
Currently, you cannot look "into" objects, and you cannot modify the local variables.
The debugger looks very similar to the Smalltalk/JavaScript debugger
and supports ''continue'', ''line stepping'', ''stepping into called functions'', ''stepping out of called functions'',
''aborting an activity'' and ''terminating'' the whole node-interpreter.

===== Limitations of the Debugger =====
One problem which is encountered with the current node version is that the breakpoint line numbers
are sometimes off-by-one; this means, that the line reported by the node-debugger is wrong and
therefore also shown wrong in the debugger. This is a problem of the particular node version,
and may or may not appear in your concrete installation (i.e. node interpreter version).

Sorry, but we cannot currently provide a workaround for this problem, as we have not yet figured out,
what constellation of source-code/statement/situation leads to this problem.
(this problem was also reported by other node users in the internet forums).

=== NodeJS Code API ===

NodeJS code supports a '''subset''' of the above activity functions, which is intended provide an interface similar to the JavaScript and Smalltalk elementary code API. Of course, technically for every API function below, the code executing in the remote Node interpreter has to make a remote procedure call back to expecco. On the Node side, this is done very similar to the above described remote message mechanism, when messages are sent from expecco to a bridge.
Also notice, that due to the single threaded nature of Node programs, all functions which ask for a value from expecco (eg. "<code>environmentAt</code>") will take a callback argument, which is called when the return value arrives.

Be remonded that the objects described below are proxy objects inside node, which will forward messages back to expecco when functions listed below are called on them. Due to the roundtrip times, these will be relatively slow (in the order of milliseconds).

==== Variables seen by the Executed Node Function ====

The following variables are in the scope of the executed function:

*<code>Transcript</code> supports a few functions to display messages in the expecco Transcript window (see below)
*<code> Stdout </code> supports a few functions to display messages on expecco's stdout stream (see below)
*<code> Stderr </code> supports a few functions to display messages on expecco's stderr stream (see below)
*<code> Logger </code> supports <code>info()/warn()/error()/fatal()</code>; these are forwarded to the Smalltalk Logger object (see Logger)

*<code>__bridge__</code> the bridge object which handles the communication with expecco. The instance slot named "<code>asynchronous</code>" is of special interest if the called function uses asynchronous callbacks (see below)

==== Reporting (NodeJS) ====

*'''error''' (''infoString'',...) Report a defect (in the test). Stops execution. If the infoString argument contains "%i" placeholders ("%1","%2",...), these will be expanded by the remaining arguments. (eg. <code>logFail("foo:%1 bar:%2", 123, 234.0)</code> will generate the failure string "foo:123 bar:234.0").

*'''fail''' (''infoString'',...) Report a failure (in the SUT). Stops execution.

*'''inconclusive''' (''infoString'',...) Report an inconclusive test. Stops execution.

*'''activitySuccess''' (''infoString'',...) Finishes the current activity with success (same as "success()").

*'''success''' (''infoString'',...) Finishes the current activity with success (same as "activitySuccess()"). Please use "activitySuccess" ("success" is not supported in all bridges due to name conflictswith other libraries. For readability, it is better to use the same name in all bridges: "activitySuccess", which is supported on all bridges)

*'''pass''' (''infoString'',...) Finishes the current testCase with success.

*'''testPass''' (''infoString'',...) Same as pass(); for compatibility with bridged languages where "pass" is a reserved keyword (i.e. python).

==== Logging (NodeJS) ====

*'''logFail''' (''messageString''...) Adds a fail message to the activity log. Execution continues, but the test will be marked as failed. If the messageString argument contains "%i" placeholders ("%1","%2",...), these will be expanded by the remaining arguments. (eg. <code>logFail("foo:%1 bar:%2", 123, 234.0)</code> will generate the failure string "foo:123 bar:234.0").

*'''logError''' (''messageString''...) Adds a error message to the activity log. Execution continues, but the test will be marked as erroneous.

*'''logWarning''' (''messageString''...) Adds a warning to the activity log. Execution continues.

*'''logInfo''' (''messageString''...) Adds an info message to the activity log. Execution continues

*'''alert''' (''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in "''Extras''" → "''Settings''" → "''Execution''" → "''Log -Settings''" (by default it is enabled). Notice that the code in the bridge is suspended until the box is confirmed.

*'''warn''' (''messageString''...) Same as ''alert()'' (for Smalltalk protocol compatibility).

==== Reflection, Information, Queries and Accessing (NodeJS) ====

*'''nameOfAction''' () The name of the activity

==== Interaction with Expecco (NodeJS) ====

*'''call'''(<actionName>, <arg1>, <arg2>, ... <argN>, function(rslt...) {...}); Executes any other expecco action (inside expecco - not inside the node interpreter), and finally calls the callBack function, when the action has finished. Notice that this is an asynchronous callback; you should not perform any further actions after the call, but instead continue inside the callback (and signal final completion via "<code>activitySuccess() / error()</code>" call from there). The callback may expect multiple rslt-arguments, to get the output values of more than one pin. However, it is currently not possible to get the values of pins which are written multiple times (i.e. an error will be reported, if that is the case) See example below.

==== Event Sending (NodeJS) ====
* '''pushEvent''' (''payloadData'') pushes an event onto the global event handler's event queue. The payload is packed into an Event object with eventType "#default. Raises an error, if no global event handler process is running.

* '''pushEventType_data''' (''eventTypeSymbolOrNil'', ''payloadData'') pushes an event of type (or #default) onto the global event handler's event queue. Raises an error, if no global event handler process is running.

==== Environment Access (NodeJS) ====

*'''environmentAt'''(''varName'', function(err, rslt) {...}); Fetches a value from the expecco environment which is in scope of the current activity, and finally calls the callBack function, when the value has been retrieved (passing the retrieved value as argument). Notice that this is an asynchronous callback; you should not perform any further actions after the call, but instead continue inside the callback (and signal final completion via "<code>activitySuccess() / error()</code>" call from there). You can only read simple objects (numbers, booleans and strings) from node actions.

*'''environmentAtPut'''(''varName'', ''newValue'', function(err) {...}); Writes a value into the expecco environment which is in scope of the current activity, and finally calls the callBack function, when the value has been stored. Notice that this is an asynchronous callback; you should not perform any further actions after the call, but instead continue inside the callback (and signal final completion via "<code>activitySuccess() / error()</code>" call from there). The ''varName'' argument must be a string and ''newValue'' a simple object (number, boolean or string) from node actions.

==== Special Functions (NodeJS) ====
*'''makeRef''' (<anyNodeObject> [, <optionalName> ]) Generates a reference to a NodeJS object, which can be passed to expecco as an output pin value. Such reference objects can be passed back to NodeJS later and are dereferenced there back to the original object. This is used to pass NodeJS handles (i.e. server/client handles) to expecco and later back to NodeJS. Read below about reference passing vs. value passing. Notice that the nodeObject will be registered (i.e. remembered) inside the node interpreter, in order to be found later, when the reference is passed as input by another node action. When the reference is no longer needed, it should be deregistered by calling the "<code>releaseRef</code> function described below. Also notice, that expecco will do this automatically, when the reference object is finalized. See example below.

*'''releaseRef''' (<nodeObjectReference>) removes the reference from the registery inside the node interpreter. See example below.

*'''wait''' () Tells expecco to wait until one of the "<code>activitySuccess/error/fail/inconclusive</code>" functions is called. Use this if the action's execution is not finished when the execute() function returns, but instead will explicitly notify the finish from within a callback. This is also to be used if a pin value has to be written later by a callback function. See example and description of callbacks/async functions below.
*'''waitForPin''' (''pinName'') Tells expecco to wait until the given output pin receives a value. This is needed for async/await (promise resolved) pin values. See example and description of callbacks/async functions below.


==== Pin Functions (NodeJS) ====

Attention:
 Javascript uses many more reserved keywords for syntax than Smalltalk. These keywords cannot be used as pin names, and you will get a syntax error ("<foo> token not expected") if you try. Be careful to not name your pins as any of: "<code>in</code>", "<code>return</code>", "<code>class</code>", "<code>private</code>", "<code>public</code>", etc. As a proven best practice, add a "''Pin''" suffix to your pin names (i.e. name it "''inPin''", instead of "''in''").

===== Input Pins (NodeJS) =====

Currently, NodeJS blocks do not support a variable number of input or output pins.

*''pinName''.'''hasValue''' () Returns true if the pin has received a value

*''pinName''.'''isConnected''' () Returns true if the pin is connected

*''pinName''.'''value''' () Returns the value at the pin (the datum). Raises an error if the pin did not receive any value.

*''pinName''.'''refValue''' () Returns the object referenced by the value at the pin. The pin must have received a reference. Raises an error if the pin did not receive any value. Use this to pass back the original reference object to expecco. The input pin must have received a reference to a Node object as generated previously by "<code>makeRef</code>". Read below about reference passing vs. value passing.

*''pinName''.'''valueIfPresent''' () Returns the pin's datum if it has one, null otherwise. Similar to "<code>value()</code>", but avoids the exception.
*''pinName''.'''valueIfAbsent''' (''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>value()</code>", but avoids the exception.

===== Output Pins (NodeJS) =====

Currently, NodeJS blocks do not support a variable number of input or output pins.


*''pinName''.'''isConnected'''() Returns true if the pin is connected (this can be used to prevent writing output values and thus speed up the execution, especially if big arrays of data values are generated)

*''pinName''.'''value''' (''data'') Writes the value.

==== Transcript, Stderr and Stdout (NodeJS) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from Node code. However, only a limited subset of messages is supported:

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show''' (''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

*'''show''' (''fmt'', ''arg''...) Like "<code>show()</code>, but "%i" sequences in the format argument are expanded by the corresponding arg strings.

*'''showCR''' (''arg'') A combination of show(), followed by a linebreak.

*'''showCR''' (''fmt', ''arg''...) Like "<code>showCR()</code>, but "%i" sequences in the format argument are expanded by the corresponding arg strings.

In addition, stdout (console.log) and stderr (console.error) are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").
 

=== Reference passing vs. value passing of Node objects to expecco ===

When values are passed via an output pin from Node to expecco, two mechanisms are possible:
* pass by value The object's JSON string is generated and passed to expecco. There, the JSON encoding is decoded and a corresponding expecco object is constructed. Conceptional, the expecco object is a copy of the original object.

* pass by reference The object is remembered inside Node, and a reference is passed to expecco. Whenever this reference object is later sent to Node again (via an input pin), the original Node object is retrieved and passed to the JavaScript code. This mechanism preserves the object's identity on the Node side and must be used for object handles (such as protocol handles).

The default mechanism is "''pass by value''". To pass a reference, use "<code>makeRef(obj)</code>" and pass the generated reference to an output pin.
==== Example (NodeJS) ====
The following code snippet sends an object's reference to an output pin:

function execute() {
 ... generate a handle object ...
outputPin.value( makeRef (someHandle , "aNodeHandle" ) );
}

the returned handle can later be sent via an input pin to another Node action, and used transparently there:

function execute() {
var handle = inputPin.value();
... do something with handle ...
}

occasionally, it is required that a reference which was received via an input pin must later be sent to an output pin again, preserving the original reference. This is to prevent additional memory allocations which would result from calling "<code>makeRef</code>" again (you would get multiple references to the same object).
For this, use "<code>inputPin.refValue()</code>" and send this to an output pin without a "<code>makeRef</code>":

function execute() {
var handle = inputPin.value();

... do something with handle ...
// send the original reference to the output
outputPin.value( inputPin.refValue() );
}

Finally, you want to release the reference inside the node interpreter, to prevent memory leaks.
Usually, this should be called, when a handle becomes invalid (e.g. when a connection handle is closed).

For this, call the "<code>releaseRef</code>" function (on the node side), passing the reference instead of the referenced object.
 For example, a close-connection action block might look like:

function execute() {
var reference = inputPin.refValue();
var referredObject = inputPin.value();

... do something with referredObject ...
closeConnection( referredObject );
// release to prevent memory leaks
releaseRef(referredObject);
}

=== Asynchronous and Callback Functions ===
A common pattern in node is "''continuation passing style''" control flow. That means, that many functions expect a function as callback argument, which is called later whenever the requested operation has finished. This is used especially with I/O and protocol related operations (such as socket connect, http requests, client connect setup etc.).
A similar situation arises with async functions, which somehow get a promise as value, and the promise is resolved via an await.

If your "<code>execute</code>" function calls any of those or is an async function which awaits on a promise, it has to tell expecco that the node-action is effectively still active when the execute function returns and that expecco should wait for an explicit finished-notification. This is done by either calling either "<code>wait()</code>" or "<code>waitForPin()</code>" somewhere within the execute function.

Then expecco will continue to wait for the action to be finished until the node code calls one of the "<code>fail()</code>", "<code>error()</code>", "<code>success()</code>", "<code>pass()</code>", "<code>inconclusive()</code>" functions (listed above) or - in case of a previous <code>waitForPin()</code>, until that pin receives a value.

Example 1: the following code fragment represents a typical callback situation: the "myProtocolConnect()" call gets a callback, which will be called later (asynchronously), when a connection is established. However, "myProtocolConnect()" will return immediately. Without the "wait()" at the end, expecco would assume that the action has finished and would proceed with other actions (possibly without any output being written to the output pin (actually, it would later detect a value being written by an already finished action, and write a warning message to the console and the log).

function execute() {
 ... call a function which does a callback ...
myProtocolConnect( ... , function(err) {
... callback possibly called much later ...
// tell expecco that we're done
if (err) {
error("some error happened: "+err.toString());
} else {
outputPin.value(someConnectionHandle);
success();
}
});
// tell expecco to continue waiting
wait();
}

Notice that callbacks can be either written as functions (with a statement body):
function(err) { statement; ... statement; }
or as a lambda expression, where the body is an expression:
(err) => expression

Example 2: the following code fragment is typical for async/await functions. Similar to the above, but covered by syntactic sugar which makes this less obvious, the execute function will return early, but execute code asynchronously due to the awaited promise:

async function execute() {
let appiumMacDriver = require("appium-mac-driver");

// due to the async operations,
// this execute function will effectively finish when
// the await receives the value,
// and it is written to the pin.
// tell expecco that the function is finished when that pin
// receives a value
waitForPin(sessionOut);

let driver = new appiumMacDriver.MacDriver();
let session = driver.createSession(defaultCaps);
let s = await session;
sessionOut.value(s);
}

Example 3: The following example demonstrates what happens if the "wait()" call is missing. The code below installs a callback which writes to an output pin 1 second AFTER the finished action:

function execute() {
output.value("Value1");
setTimeout(function(err) {
output.value("Value2");
}, 1000);
}

the above code will lead to an error.

The correct version is:

function execute() {
output.value("Value1");
setTimeout(function(err) {
output.value("Value2");
success();
}, 1000);
wait();
}

Up to version 23.2, this situation was not always detected and could have lead to an output value being written to a same-named output pin of a followup action (iff another bridged action was triggered which was of the same type, that second action's output was sometimes written, depending on timing constraints). With version 24.1, this is detected and an error message is sent to the Transcript (it cannot be reported as an error in the activity log, because the first action which is responsible has already finished, whereas the second action (which is innocent) cannot be blamed for that).

=== Calling other Expecco Actions ===
Any expecco action (i.e. elementary or compound) can be called from Node code.
However, as node uses a callback mechanism, the code looks a bit different from other languages, in that an additional callback argument is to be passed. You can pass either the name or the UUID of the activity which is to be called.
Arguments are passed to the called action's input pin (top to bottom).

For now, there is a limitation, in that only a single value (per pin) can be passed to the callback (i.e. you cannot get the values of pins which are written multiple times).
 Example:

function execute() {
 ... call an expecco activity ...
call("myAction", 100, 200 ,
function(result) {
... callback gets the first value from myAction's first output pin ...
success();
});
// not reached
}

Notice, that in order to get a sequence of calls, the code needs nested functions, as in:

function execute() {

call("myAction1", 1000, 2000,
function(rslt1) {
Transcript.showCR("after first call: "+rslt1);
call("myAction2", 10000, 20000,
function(err, rslt2) {
Transcript.showCR("after second call: "+rslt2);
success();
});
// not reached
});
// not reached
}

If the called action has multiple output pins, provide a callback function which expects more than one rslt argument,
as in:
function execute() {

call("actionWithTwoOutputPins", 1000, 2000,
function(valueAtPin1, valueAtPin2) {
Transcript.showCR("received two values: "+valueAtPin1+" and: "+valueAtPin2);
success();
});
// not reached
}

=== Reading expecco Environment Variables ===
Expecco variables can be fetched via the "<code>environmentAt</code>" function. Notice, that this takes a second callback function as argument, which is called when the value is (later) received. The execution of the action proceeds with this continuation, and "<code>environmentAt</code>" does not return.

 For example:
function execute() {
environmentAt("variable1", function(err, varValue) {
Transcript.showCR("the variable value is: "+varValue);
success();
});
// not reached
}

=== Executing Node Actions in Multiple Node Interpreters ===
In order to test the interaction between multiple node programs,
or to generate load for performance tests,
it may be required to start multiple node interpreters,
and run action code in them.

This chapter describes how to start a node interpreter and how to interact with them.

==== Starting another Node Interpreter on the Local Machine ====

Every Node bridge uses the given port for bridge communication plus the next port for debugging.
Every bridge running on the same host must use different ports.
The default bridge uses port 8777 (and 8778 for debugging).
Thus, additional bridges should be given ports incremented in steps of 2,
and useful ports are 8779, 8781, 8783 etc. for additional node bridges.

===== Programmatic Start =====

nodeBridge := Expecco
newNodeJSBridgeConnectionForHost:hostName port:portNr
in:aDirectoryOrNil.

===== Using an Action from the Standard Library =====
use the "''Start new Local Node Bridge''" action from the library.

===== Executing an Action inside another Node Interpreter =====

Either add a "''nodejs''" input pin to the action (passing the other node-bridge's handle) or
set the "<code>NODEJS</code>" environment variable before the action.
An example is found in the "<code>d62_Event_Queue_Demos.ets</code>" suite: 
[[Datei:Event_Queue_Demo.png|600px|]]

=== Node Packages ===

===Example: Installing Additional Node Packages ===
Use the Node package manager "<code>npm</code>" to install packages.
 The "''Extras''" → "''Bridges''" → "''Node Bridge''" menu also contains an entry to install npm packages.
 Find packages in [https://www.npmjs.com https://www.npmjs.com].

For example, assume you need the current city weather in a suite, navigate to "https://www.npmjs.com", search for "weather", find the "<code>city-weather</code>" package and click on it. You will arrive on a page giving installation instructions and sample code at the end.
Scroll down to the example code and keep that page open (we can use the code later).

Open a cmd/shell window and execute on the command line:
npm install city-weather

=== Examples: Using a Node Package in Expecco ===
==== Example1: Access to the City Weather Service ====
For a first test, we will take the original code from the example.
Create a new node action, and enter the code:
var weather = require("city-weather");

function execute() {
weather.getActualTemp('Rome', function(temp){
console.log("Actual temperature: " + temp);
});
}

(you can copy-paste the sample code from the webpage)

Open the expecco console (aka "Transcript" via the "''Extras''" → "''Tools''" → "''Transcript''" menu item) and run the test.
A temperature should be displayed on the Transcript.

Now add an input pin named "''city''", and change the code to:
...
weather.getActualTemp(city.value(), function(temp){
...
and try the code in the "''Test/Demo''" page with a few different cities at the input pin.

Then, add an output pin named "''temperature''", and change the code again to:
var weather = require("city-weather");

function execute() {
weather.getActualTemp(city.value(), function(temp){
console.log("Actual temperature: " + temp);
temperature.value( temp );
});
}

if you now execute this action, you will notice, that the output pin does NOT get the value.
The reason is, that the pin is written by a node-callback function, which is called at a time after the action's "<code>execute</code>" function has already finished.
Thus, we have to tell expecco, that it should wait until the callback is actually called.
For this, you should add a call to the "<code>wait()</code>" function.

This tells expecco, that the execute-function is not complete, and will wait for one of the "<code>success/fail/error</code>" functions to be called.
So we also have to add a call to "<code>success()</code>" inside the callback (otherwise, expecco would wait forever).

Thus, we change the code to:
var weather = require("city-weather");

function execute() {
weather.getActualTemp(city.value(), function(temp){
console.log("Actual temperature: " + temp);
temperature.value( temp );
success();
});
wait();
}

As a final step, you should remove or comment the call to "<code>console.log()</code>" and add some error reporting, in case a city was not found:
var weather = require("city-weather");

function execute() {
weather.getActualTemp(city.value(), function(temp){
// console.log("Actual temperature: " + temp);
if (temp == "City was not found") {
error(temp+": "+city.value());
}
temperature.value( temp );
success();
});
wait();
}

==== Example2: Access OpenStreetMap Services ====
This is described in a [[Node_Examples/en | separate document]].

== Bridged Python Elementary Blocks ==

Code written as a Python elementary block is not executed directly by expecco. Instead, the code is forwarded to a python interpreter. This may be a local python process, whose sole purpose is to provide additional utility functions or which provides an interface to the actual system under test (SUT), or it may be on a remote system.

==== Python Versions ====
Python is available in 2 major dialects (2.x vs. 3.x) and different implementations (cPython, Jython, IronPython):
* use '''jython''', if you have to interface/embed java classes or jars;
* use '''ironPython''', if you have to interface with .NET assemblies;
* use '''python3''' to interface to modern frameworks such as Tesseract (optical character recognition), computer vision, Tensorflow (machine learning) etc.
* use '''python2''' for some older frameworks, which have not yet been ported to the newer python3 (notice, that support for python2 is going to cease soon)

Of course, if you need to interface to a Python module which is specifically written for a version, that specific version is obligatory.

You have to download and install Python, Python3, Jython and/or IronPython separately; these interpreters are not part of the expecco installation procedure.
 See ([[Installing_additional_Frameworks/en | "Installing Additional Frameworks"]]) and download Python from [https://www.python.org/downloads https://www.python.org/downloads],
[https://jython.org/downloads.html http://jython.org/downloads.html] for Jython, and [ https://ironpython.net/download/] for IronPython.

Additional frameworks may be needed as prerequisite (i.e. Java for Jython, Mono for IronPython on non-Windows machines).

==== Bridged vs. Scripted Actions====
Similar to Node, Python code execution is supported via 2 different mechanisms:
* '''Bridged Python''' action blocks - these look at the outside like regular action blocks with typed input and output pins, which are available inside the action's code via "<code>.value()</code>" APIs. Objects can be interchanged between expecco and the python process either by value or by reference. The bridge-partner in which the code is to be executed is started once and will remain an active process until terminated. Any state (data) created inside the bridge remains alive while the partner is running and the connection is alive.
* '''Python-Script''' action blocks - these look like shell-script blocks, in that the standard input and output is used to interact with the script. For every individual script action, the interpreter (i.e. Python) is started anew. No state is alive between and across actions (the python-interpreter is terminated after each action), and no objects can be exchanged (except for very simple objects by means of reading encoded objects via stdin/stdout/stderr).

The following describes the first kind of blocks (bridged). Script blocks are described elsewhere, in the [[ElementaryBlock_Element/en#Python_Script_Blocks | Python-Script Blocks]] chapter.

=== Debugging Bridged Python Actions ===
Debug support for bridged Python actions is still being developed and more features are added with newer versions. However, there are probably better IDEs available and it might be a good idea to develop and debug Python code in your preferred IDE, and only add interface code to already debugged modules as expecco actions (this is certainly a matter of your personal preferences; in the past, interfaces to many modules have been implemented using only expecco's debug facilities).

In order to support debugging of Python actions, you have to install either the "''debugpy''" or the "''ptvsd''" package (*) with:
pip install debugpy
or:
pip3 install debugpy
or:
python3 -m pip install debugpy

*) ptvsd is no longer maintained and has been replaced by the debugpy package. Ptvsd might be obsolete by the time of reading this.

For more information on the ptvsd package, see [https://pypi.org/project/ptvsd https://pypi.org/project/ptvsd] and [https://github.com/Microsoft/ptvsd https://github.com/Microsoft/ptvsd].
 For debugpy, refer to [https://pypi.org/project/debugpy https://pypi.org/project/debugpy].

Notice that the debug features are currently not supported by python2 or jython.

=== Python Datatype Limitations ===

==== Limited Python Object Conversion ====
Some limited form of object conversion is automatically performed when passing expecco objects to Python, and back when returning values from Python. This conversion especially affects values passed to/from pins of a Python action.

The following table summarizes the conversion process:
{| Border
! from Expecco (Smalltalk)
! to Python and from Python
! to Expecco
!
|-
| String
| String
| String
|-
| Float 
| Float
| Float
|-
| Float, Double
| Float
| Float (Smalltalk Floats have double precision)
|-
| Fraction
| Float
| Float (Smalltalk Floats have double precision)
|-
| Boolean
| Boolean
| Boolean
|-
| Array of any above
| Array of any above
| Array of any above
|-
| ByteArray
| Array
| Array
|-
| -
| any
| any Python object as Reference via "<code>makeRef(obj)</code>"
|-
| Python object reference as previously generated by "<code>makeRef(obj)</code>" fetch the reference in Python via "<code>inpin.refValue()</code>" or the value via "<code>inpin.value()</code>"
| fetch the reference in Python via "<code>inpin.refValue()</code>" or the value via "<code>inpin.value()</code>"
| send value or reference with "<code>makeRef(obj)</code>"
|-
| Filename
| String (i.e. pathname)
| String
|-
| arbitrary Smalltalk Object (!)
| Object with slots
| Dictionary with slots
|}

(-) does not work. In general, only objects which can be represented by JSON can be transmitted between expecco and the python action.

==== No Smalltalk Classes, No Smalltalk Objects in Python ====
Of course, no Smalltalk class can be used directly in Python code.
And only a subset of Smalltalk objects (those which can be represented as JSON string) can be passed to/from Python as described above 1).

In general: if more complex objects need to be interchanged, this must be either done by converting them to an array (of objects), an array of arrays or a dictionary.
Or, alternatively to some ASCII representation (XML or JSON, for a more lightweight approach) and convert this back and forth.

It is also possible to pass an object-reference from the Python interpreter to expecco, and pass it back to the Python interpreter later (usually in another action).
This is used to get connection, protocol or device handles from Python, and pass them to other (transmission or control) actions later.

1) However, such objects can still be passed to expecco as an object reference as with:<code>output.value(makeRef(obj))</code>


==== Limited Syntax Highlighting, Code Completion and Limited Debugging Support ====
Currently, all of those are very limited: the syntax highlighter only detects keywords and some constants as such; code completion does not work and debug support is limited.

The bridge is meant to interface to already debugger code, not as a replacement for a full python IDE.
For this, you should start the bridge under your favourite IDE and connect to this already running bridge.

=== Bridged Python Code API ===

WARNING: Bridged Python Elementary Actions are still being developed - their behavior might be subject to changes (aka the protocol will be extended).

Python code may consist of function- and/or class definitions. Among the functions, there should be one named "<CODE>execute()</CODE>"; typically, that is the last defined function, which calls into other python code. If no "execute"-function is defined, expecco tries to call "<code>main()</CODE>" as fallback. This special behavior was added to make it easier to reuse existing script code.

Bridged Python code can use activity functions similar to the above Groovy or Node actions.
The API is intended to provide an interface similar to the JavaScript and Smalltalk elementary code API. Of course, technically for every API function below, the code executing in the remote Python interpreter has to make a remote procedure call back to expecco. On the Python side, this is done very similar to the above described remote message mechanism, when messages are sent from Smalltalk to a bridge.

==== Variables seen by the Executed Python Function ====

The following variables are in the scope of the executed function:

*<code>Transcript</code> supports a few functions to display messages in the expecco Transcript window (see below)
*<code> Stdout </code> supports a few functions to display messages on expecco's stdout stream (see below)
*<code> Stderr </code> supports a few functions to display messages on expecco's stderr stream (see below)
*<code> Logger </code> supports <code>info(), warn(), error() and fatal()</code>; these are forwarded to the Smalltalk Logger object (see below)
*<code> Dialog </code> supports <code>confirm(), warn(), information()</code>; these are forwarded to the Smalltalk Dialog object (see below)


==== Reporting (Python) ====

*'''error''' (''infoString'') Report a defect (in the test). Finishes the current activity with an ''error'' verdict.

*'''fail''' (''infoString'') Report a failure (in the SUT). Finishes the current activity.

*'''inconclusive''' (''infoString'') Report an inconclusive test. Finishes the current activity.

*'''activitySuccess''' (''infoString'') Finishes the current activity with success (same as "success()").

*'''testPass''' (''infoString'') Finishes the current testCase with success. This has the same effect as "pass()" in other actions - its name had to be changed because "pass" is a reserved keyword in Python.

==== Logging (Python) ====

*'''logFail''' (''messageString'') Adds a fail message to the activity log.

*'''logError''' (''messageString'') Adds a error message to the activity log.

*'''logWarning''' (''messageString'') Adds a warning to the activity log.

*'''logInfo''' (''messageString'') Adds an info message to the activity log.

*'''alert''' (''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" - "''Log -Settings''" dialog (by default it is disabled).

*'''warn''' (''messageString'') Same as ''alert()'' (for Smalltalk protocol compatibility).

==== Reflection, Information, Queries and Accessing (Python) ====



==== Interaction with Expecco (Python) ====
*'''call'''(<actionName>, <arg1>, <arg2>, ... <argN>); Executes any other expecco action (inside expecco - not inside the Python interpreter), and returns the generated output pin values as a tuple It is currently not possible to get the values of pins which are written multiple times (i.e. an error will be reported, if that is the case) See example below.

:Errata: 
::The call function only returns the first value of the first pin. 
::See callN below (release >= 26.2)

*'''callN'''(<actionName>, <arg1>, <arg2>, ... <argN>); Same as <code>call</code> above, but returns a tuple (Array) containing the first value of each output pin of the called action.

==== Environment Access (Python) ====
*'''environmentAt'''(<varName>); Fetches and returns a value from the expecco environment which is in scope of the current activity. You can only read simple objects (numbers, booleans and strings) from python actions.

*'''environmentAtPut'''(<varName>, <newValue>); Writes a value into the expecco environment which is in scope of the current activity. You can only write simple objects (numbers, booleans and strings) from python actions.


==== Event Sending (Python) ====
* '''pushEvent''' (''payloadData'') pushes an event onto the global event handler's event queue. The payload is packed into an Event object with eventType "<code>#default</code>. Raises an error, if no global event handler process is running.

* '''pushEventType_data''' (''eventTypeSymbolOrNil'', ''payloadData'') pushes an event of type (or <code>#default</code>) onto the global event handler's event queue. Raises an error, if no global event handler process is running.

==== Special Functions (Python) ====
*'''makeRef''' (<anyPythonObject>) Generates a reference to a Python object, which can be passed to expecco as an output pin value. Such reference objects can be passed back to Python later and are dereferenced there back to the original object. This is used to pass Python handles (i.e. server/client handles) to expecco and later back to Python. Read below about reference passing vs. value passing. Notice that the pythonObject will be registered (i.e. remembered) inside the python interpreter, in order to be found later, when the reference is passed as input by another node action. When the reference is no longer needed, it should be deregistered by calling the "<code>releaseRef</code> function described below. Also notice, that expecco will do this automatically, when the reference object is finalised. See example below.

*'''releaseRef''' (<nodeObjectReference>) removes the reference from the registery inside the Python interpreter. See example below.

*'''wait''' () Tells expecco to wait until one of the <code>success()</code>, <code>error()</code>, <code>fail()</code>, or <code>inconclusive()</code> functions is called. Use this if a pin value has to be written later by a callback function. See explanation of [[#Asynchronous_and_Callback_Functions|async callbacks]] and the example in the NodeJS API description.

*'''bridge_inMainThread''' (task) OS X only: Task must be a lambda expression which is executed by the main thread (as opposed to the bridge connection thread). This is required on eg. OS X to run code which interacts with OS X windowing framework. On non-OSX systems, this executes the task directly (and also in the main thread). Typical use: <code>bridge_inMainThread(lambda: someWindow.show() )</code>

==== Pin Functions (Python) ====
Currently, python blocks do not support a variable number of input or output pins.

Attention:
 Python uses many more reserved keywords for syntax than Smalltalk. These keywords cannot be used as pin names, and you will get a syntax error if you try. Be careful to not name your pins as any of: "<code>import</code>", "<code>return</code>", "<code>def</code>", "<code>if</code>" etc. As a proven best practice, add a "''Pin''" suffix to your pin names (i.e. name it "''inPin''", instead of "''in''").

===== Input Pins (Python) =====

*''pinName''.'''hasValue''' () Returns true if the pin has received a value

*''pinName''.'''isConnected''' () Returns true if the pin is connected

*''pinName''.'''value''' () Returns the value at the pin (the datum). Raises an error if the pin did not receive any value.

*''pinName''.'''refValue''' () Returns the object referenced by the value at the pin. The pin must have received a reference. Raises an error if the pin did not receive any value. Use this to pass back the original reference object to expecco. The input pin must have received a reference to a Python object as generated previously by "<code>makeRef</code>". Read below about reference passing vs. value passing.
*''pinName''.'''valueIfPresent''' () Returns the pin-datum if it has one, None otherwise. Similar to <code>value()</code>, but avoids the exception.
*''pinName''.'''valueIfAbsent''' (''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to <code>value()</code>, but avoids the exception. Use this, if "None" is a possible value at the pin, and the code needs to distinguish between getting a "None" at the pin and not having a value at all at the pin.


===== Output Pins (Python) =====


*''pinName''.'''isConnected'''() (vsn 26.2) Returns true if the pin is connected, false otherwise. This may be used to avoid generating output values to unconnected pins (useful if the value is expensive to compute or leads to a big data transfer).

*''pinName''.'''value''' (''data'') Writes the value.

==== Transcript, Stderr and Stdout (Python) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from Python code. However, only a limited subset of messages is supported:

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show''' (''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

*'''show''' (''fmt'', ''arg''...) Like "<code>show()</code>, but "%i" sequences in the format argument are expanded by the corresponding arg strings.

*'''showCR''' (''arg'') A combination of show(), followed by a linebreak.

*'''showCR''' (''fmt'', ''arg''...) Like "<code>showCR()</code>, but "%i" sequences in the format argument are expanded by the corresponding arg strings.

*Transcript '''clear''' () Clears the contents of the Transcript window (new in 24.2)

*Transcript '''raiseWindow''' () Makes the Transcript window visible (new in 24.2)

In addition, stdout (console.log) and stderr (console.error) are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").
 

==== Dialog (Python) ====
Some of expecco's Dialog messages are forwarded from Python:
*'''information''' (''msg'') (new in 23.2) Opens an information dialog. I.e. "<code>Dialog.information("Hello")</code> will show "Hello" in a popup dialog window.

*'''confirm''' (''msg'') Opens a Yes/No confirmation dialog (and returns True/False)

*'''request''' (''msg'') Opens a dialog asking for a string (and returns the entered string or None on cancel)

*'''requestPassword''' (''msg'') Opens a dialog asking for a password string (and returns the entered string or None on cancel)

*'''requestFilename''' (''msg'') (new in 23.2) Opens a dialog asking for a file name string (and returns the entered file name or None on cancel)

=== Global and Static Variables ===
Python actions are defined within the scope of another function, to prevent accidentically overwriting/redefining any global.
Thus, you have to access globals via "globals().get("name")".

==== Static Variables ====
Starting with v24.1, static variables (which are visible within one activity and which are preserved across calls) can be defined by
prepending the execute function's code with:
# start of static definitions
... any variables which should be static ...
# end of static definitions

Notice that these comment lines must be written exactly as above.
 As an example, the following uses a static variable to increment a counter whenever the action is Ivoked:
# start of static definitions
count=0
# end of static definitions

def execute():
nonlocal count

count = count + 1
print(f"count={count}")

Notice that the above example does not work in pre 24.1 versions.
 Also notice, that the static definitions are re-executed whenever the action code is changed or recompiled (i.e. that the count variable is reset to 0).

==== Global Variables ====

Example of a global variable that can also be used in other modules.

Caution: Please make sure that the name of the global variable is unique in your test suite!

def execute():
global count
try:
count
except NameError:
# Throws a NameError if not yet initialised
count = 0
count = count + 1
print(f"count={count}")

=== Printing Debug Messages in Python ===
Be aware, that the stdout stream is buffered in Python. Thus, debugprints generated by print might not appear immeditely.
 Eg, the following code:
print("start")
time.sleep(10)
print("end")
will show both lines after the sleep.

Use
sys.stdout.flush()
to force messages to be passed immediately to expecco; eg:
print("start")
sys.stdout.flush()
time.sleep(10)
print("end")

=== Python Asynchronous and Callback Functions ===
If output pins are to be written by a callback which is invoked AFTER the python function returned, the expecco activity will already be finished, and the pin will NOT be written.
Instead, a warning is generated in the log.

You MUST tell expecco that the execute function has not yet finished, by calling "wait()" and signal the real activity end in the callback via one of "success()", "error()"or "fail()".

For a detailed description of this mechanism, read the
[[#Asynchronous and Callback Functions|corresponding section]] in the Node API.

=== Reference passing vs. value passing of Python objects to expecco ===

When values are passed via an output pin from Python to expecco, two mechanisms are possible:
* pass by value The object's JSON string is generated and passed to expecco. There, the JSON encoding is decoded and a corresponding expecco object is constructed. Conceptional, the expecco object is a copy of the original object.

* pass by reference The object is remembered inside Python, and a reference is passed to expecco. Whenever this reference object is later sent to Python again (via an input pin), the original Python object is retrieved and passed to the Python code. This mechanism preserves the object's identity on the Python side and must be used for object handles (such as protocol handles).

The default mechanism is "''pass by value''".
 To pass a reference, use "<code>makeRef(obj)</code>" and pass the generated reference to an output pin.

When objects are passed from expecco to python, this is transparent. Python will automatically resolve passed in references. Thus you can send a "pointer" to an object to an output pin via "<code>makeRef(obj)</code>" and pass it to another Python action, where the value will refer to the original object.

==== Example (Python) ====
The following code snippet sends an object's reference to an output pin:

def execute():
 ... generate a handle object ...
outputPin.value( makeRef (someHandle ) )

the returned handle can later be sent via an input pin to another Python action inside the same bridge, and use transparently there:

def execute():
handle = inputPin.value()
... do something with handle ...
}

occasionally, it is required that a reference which was received via an input pin must later be sent to an output pin again, preserving the original reference. This is to prevent additional memory allocations which would result from calling "<code>makeRef</code>" again (you would get multiple references to the same object).
For this, use "<code>inputPin.refValue()</code>" and send this to an output pin without a "<code>makeRef</code>":

def execute():
handle = inputPin.value();

... do something with handle ...
# send the original reference to the output
outputPin.value( inputPin.refValue() )

Finally, you want to release the reference inside the Python interpreter, to prevent memory leaks.
Usually, this should be called, when a handle becomes invalid (e.g. when a connection handle is closed).

For this, call the "<code>releaseRef</code>" function (on the node side), passing the reference instead of the referenced object.
 For example, a close-connection action block might look like:

def execute():
reference = inputPin.refValue()
referredObject = inputPin.value()

... do something with referredObject ...
closeConnection( referredObject )
# release to prevent memory leaks
releaseRef(referredObject)



=== Calling other Expecco Actions (Python) ===
Not yet implemented

Any expecco action (i.e. elementary or compound) can be called from Python code.
You can pass either the name or the UUID of the activity which is to be called.
Arguments are passed to the called action's input pin (top to bottom).

For now, there is a limitation, in that only a single value (per pin) can be returned (i.e. you cannot get the values of pins which are written multiple times).
 Example:

def execute():
 ... call an expecco activity ...
result = call("myAction", 100, 200)

=== Python2 vs. Python3 ===
Although python2 is going to be obsoleted soon, there are still many packages and frameworks around, which require that version.

If all of your actions use the same python version, specify it in the "Python" field of the interpreter settings dialog.
Otherwise, change individual action's python version via the "Language" comboList, above the code editor (change to "BridgedPython2" or "BridgedPython3" to make it explicit).

Paths to the explicit versions and to the unspecific version are all defined in the pathon settings.

=== Reading expecco Environment Variables (Python) ===
Expecco variables can be fetched via the "<code>environmentAt</code>" function.
 For example:
def execute():
varValue = environmentAt("variable1")
...

=== Python Packages ===
You should install python packages using "pip" or "pip3", depending on the python version, for which a package is to be installed.
For more information, please consult the [http://pip.pypa.io pip documentation].

On Windows, "pipwin" seems to perform best, if additional C/C++ libraries need to be installed or compiled (eg. "pipwin install pyaudio").

When installing, make sure that the packages are installed in the correct target directory, as per Python environment; i.e. if you have multiple versions of the interpreter or virtual environments, make sure that the Python as started by expecco (and defined in the settings) uses and sees the correct module path.

===Installing Additional Python Packages ===
Use the Python package installer "<code>pip</code>" (or "<code>pip3</code>") to install packages.
The "''Plugins''" → "''Bridges''" → "''Python Bridge''" menu also contains an entry to install pip packages.
If you use virtual environments, make sure that your packages are installed in the correct location.

Find packages in [https://pypi.org/ https://pypi.org/] or [https://docs.python.org/3/py-modindex.html https://docs.python.org/3/py-modindex.html].



=== Accessing Assemblies in IronPython ===
Because IronPython executes inside a CLR environment, it has access to any assembly (written in any language).
For this, IronPython provides a special language extension, which is described in detail in [[https://ironpython.net/documentation/dotnet/dotnet.html the IronPython documentation]].

Example:
*** to be added **

=== Example 1: Using the "overpy" Python Package (open street map access) in Expecco ===
In this example, we will access the OpenStreetMap API to fetch information about a particular street
("Straße der Nationen") in a given city ("Chemnitz").

The example was taken from [https://pypi.org/project/overpy https://pypi.org/project/overpy] which is documented in [https://python-overpy.readthedocs.io/en/latest/index.html https://python-overpy.readthedocs.io/en/latest/index.html]. It requires python3 (you will get a UnicodeEncodeError if you try it in python2).

First, install the package with:
pip3 install overpy

For a first test, we will take the original code from the example.
Create a new Python action, and enter the code:
import overpy

api = overpy.Overpass()

def execute():
# fetch all ways and nodes
result = api.query("""
way(50.746,7.154, 50.748,7.157) ["highway"];
(._;>;);
out body;
""")

for way in result.ways:
print("Name:%s" % way.tags.get("name", "n/a"))
print(" Highway:%s" % way.tags.get("highway", "n/a"))
print(" Nodes:")
for node in way.nodes:
print(" Lat:%f, Lon:%f" % (node.lat, node.lon))

(you can copy-paste the sample code from the webpage)

Open the expecco console (aka "Transcript" via the "''Extras''" → "''Tools''" → "''Transcript''" menu item) and run the test.
A list of street nodes should be displayed on the Transcript.
 Of course, the above can be changed to send the latitude and longitude values to output pins for further processing in your test suite.

=== Example 2: Accessing other Python Packages or Individual Script Files ===
The following works in 19.2 and later. 
In the following example, functions contained in a regular Python script file are called.
We assume, that the file is named "MyLib.py", and located in some directory ''DIR'':
 
DIR/MyLib.py:
def fun1(a,b):
return a+b;

def fun2(a,b):
return a-b;

We also assume, that you have created a new python action block, containing the code:

import MyLib

def execute():
Transcript.showCR("fun1:" + str(MyLib.fun1(10,20))
+ " fun2:" + str(MyLib.fun2(10,20)))

If you execute this action, you will probably get a "Module Not Found" error from python,
(unless DIR is already in your PYTHONPATH environment variable).

To fix the problem, open the "''Extras''" → "''Settings''" → "''External Script Interpreters''" → "''Python''" dialog,
and add DIR to the "Module Path" value. Notice that on Unix/Linux, you have to separate directories with colons ":", whereas under Windows, you'll have to separate them with semicolons ";".

You will have to shut down the already running Python interpreter and restart it, for the new PYTHONPATH setting to become valid. For this, use the "''Plugins''" → "''Bridges''" → "''Python Bridge''" → "''Shutdown Interpreters''" menu item (or shut down all external interpreters via the "''Extras''" → "''Debug''" menu).

=== Example 3: Accessing Python Script Files in Attachments ===
The following works in 19.2 and later. 
You can add Python script files (i.e. like the "MyLib.py" file in the above example) as attachment to to the suite. For this you have to add "$(Attachments)" to the Python module path setting in "''Extras''" → "''Settings''" → "''External Script Interpreters''" → "''Python''", and import it in the Python code as in the previous example.

=== Example 4: Using the Python Appium Bindings ===
In the following, we'll use a Python Appium interface for automation of a mobile application
(in this case, not using the mobile plugin, and not using the GUI Browser).
This may be a useful scenario, if you already have python test actions, which you want to integrate into
expecco.

First install the required python package(s) via the command line or via expecco's "''Plugin''" → "''Bridges''" → "''Python''" menu:
pip3 install Appium-Python-Client
or:
python -m pip install Appium-Python-Client
then make a dummy BridgePython block to check if the package is found:
import appium

def execute():
Transcript.showCR ("Hello world; Appium was found");
Now take either existing code, or copy-paste samples from the [https://pypi.org/project/Appium-Python-Client Appium-Python-Client website]; here is a typical code fragment (of course, you have to adjust the values as required). Obviously, it is also a good idea to add input pins to the python action, so the capabilities and connection parameters can be passed as arguments.
from appium import webdriver

desired_caps = dict(
platformName='Android',
platformVersion='10',
automationName='uiautomator2',
deviceName='Android Emulator',
)

def execute():
driver = webdriver.Remote('http://localhost:4723/wd/hub', desired_caps)
el = driver.find_element_by_accessibility_id('item')
el.click()

=== Example 5: Interfacing to Tensorflow ===

* Create a bridged Python action containing the following code:
import numpy as np
import tensorflow as tf
import tensorflow_hub as hub
import tensorflow_datasets as tfds

def execute():
print("Version: ", tf.__version__)
print("Eager mode: ", tf.executing_eagerly())
print("Hub Version: ", hub.__version__)
print("GPU is", "available" if tf.config.experimental.list_physical_devices("GPU") else "NOT AVAILABLE")

* run it
* if you get a "module not found" error message, either click on the link (named "here"), embedded in the error message, or alternatively select the "''Plugins''" → "''Bridges''" → "''Python''" → "''Install pip Package''" menu item. Of course, you can also install packaged from the command line in a shell/cmd window.
* install missing packages (care for the correct virtual environment if you use them)
* repeat running it, until you get an output on the Transcript (or stderr) similar to:
1: Version: 2.4.1
1: Eager mode: True
1: Hub Version: 0.11.0
1: GPU is NOT AVAILABLE

* You may have to shutdown the bridge after installation of new packages (although it usually works without, unless existing and already loaded packages are upgraded during the installation).

=== Example 6: Interfacing to the "astropy" Package ===
The "astropy" package contains a number of very useful functions for astronomy applications. Among others, you'll find time functions, geo-location mapping, physical constants, image processing and much more inside. (see https://docs.astropy.org/en/stable/index.html)

===== Installation =====

First install the required python package(s) via the command line or via expecco's "''Plugin''" → "''Bridges''" → "''Python''" menu:
pip3 install numpy
pip3 install astropy (astropy-Python-Client)
or:
python -m pip install numpy
python -m pip install astropy (astropy-Python-Client)

===== Smoke Test if Package is Installed =====

then make a dummy BridgePython block to check if the package is found:
import astropy

def execute():
Transcript.showCR ("Hello world; astropy was found");

Notice: because bumpy and astropy are relatively big packages, the first initial execution may take a few seconds because the Python interpreter has to load these packages (but this only happens when the very first Python action is executed).

===== Interface to an astropy Function =====

The following example demonstrates how to call functions within astropy;
this will convert an expecco timestamp (a DateTime object) to a julianDate (as Float).
(Hint: JulianDates are commonly used in Astronomy and Space Sciences).

Please read https://docs.astropy.org/en/stable/time/index.html for details on time functions.

The code includes a few debug prints (to the Transcript). In a production suite, these should probably be commented (or replaced by calls to a logger, which can be switched on/off dynamically).

[[Datei:AstroPyExample1.png|500px]]

The action can then be used in a diagram as:

[[Datei:AstroPyExample2.png|500px]]

After a run, we get the Julian date as a float:

[[Datei:AstroPyExample3.png|500px]]

Be aware that expecco requires objects to be JSON serializable to be passed from/to the Python interpreter. Sadly, this is not true for all atrophy objects. If required either pass objects by reference or encode/decode them as strings (or extract subfields into an array and pass the array or pass subfields via individual input/output pins).

It may also be possible to define additional JSON encoders/decoders for individual types.

=== Example 7: Background Thread Inside Python ===

It may be useful to execute python code in a Python background thread;
for example to poll for data or to check for external equipment status
in a loop.

===== Extra Process with a Secondary Python Bridge =====

In many cases, you can start a secondary Python bridge and execute actions
in it via an expecco background action.
 For this:
* start a new Python bridge (using the "[Python] Start bridge" action from the standard library) in the background action
* add a python bridge input pin to actions which are to be executed there and pass that bridge reference to the background action's python step inputs.
:As an alternative, define an environment variable named "PYTHON" in the background action and set its value to the second bridge instance. Then all python actions inside and under the bg-action will be executed there.
Notice that no object references can be exchanged between the two bridges;
you are limited to data types which are JSON representable.

===== Thread inside the Same Python Bridge =====
If the above is not feasable (for example because the background actions needs access to values or handles of the other actions), you can start a thread inside the same bridge.

However, a number of have to be considered:
* ensure that the extra thread can be terminated eventually. Because Python does not provide a kill-thread mechanism, the thread must check for a stop variable, and terminate itself.
* the stop variable should not be a Python global, to avoid name conflicts if more than one background thread is started (or another imported library uses a similar mechanism)
* communication with the background thread must be performed via event queues, because it cannot write to any output pin.

Here is an example which follows the above scheme:
====== Background Thread Starter ======
[[Datei:Python_background_action_schema.png|mini]]
A Python action which gets a bridge and additional parameters as input. Here, a deltaTime, which defines the poll-loop cycle and a token which is passed with the checkStatus to the event queue.

The action defines 3 functions, the threaded function itself, for which a new thread is started by "execute", and a thread-stop function (which simply sets the "running" variable to False.

A reference to the stop-function is sent to the output pin.

import sys
import time
import threading

running = True

def thread_function(dt, tok):
nonlocal running

ExpeccoLogger.info("Thread %s: starting", tok)
while running:
time.sleep(dt)
if running:
checkOutcome = True # perform check...
pushEventType_data("bg-check", (tok,checkOutcome))
ExpeccoLogger.info("Thread %s: finishing", tok)

def stopThread():
nonlocal running
ExpeccoLogger.info("stopThread")
running = False

def execute():
ExpeccoLogger.info ("start")
x = threading.Thread(target=thread_function,
args=(waitTime.value(), token.value(),))
x.start()
stopper = stopThread
stopThreadOut.value(makeRef(stopThread))
ExpeccoLogger.info ("end")

====== Thread Stopper ======
[[Datei:Call_Python_Function.png|mini]]
the stop-function provided by the thread-starter can later be called to clear the "running" flag. An action to call it would look like:

import threading

def execute():
f = func.value()
f()

====== EventQueue Setup ======
The background thread will write to an event queue, with its events marked as 'bg-check'. Thus, we must define a handler for those events.
In expecco, a handler can be either an action block, or a Smalltalk block or a JavaScript function.
 This example uses a Smalltalk block which send a message to the Transcript:
[[Datei:Python_BG-Thread-Setup.png]]
When executed, the Transcript shows:
[info]: start {SimpleBridge >> event_LOGGER: [78]}
[info]: Thread action1: starting {SimpleBridge >> event_LOGGER: [78]}
[info]: end {SimpleBridge >> event_LOGGER: [78]}
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:49.907)
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:50.909)
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:51.914)
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:52.919)
Event(type=bg-check data=#(action1 true) ts=2024-04-29 16:11:53.937)
[info]: stopThread {SimpleBridge >> event_LOGGER: [78]}
[info]: Thread action1: finishing {SimpleBridge >> event_LOGGER: [78]}

=== Example 8: Interfacing to a .NET Assembly via IronPython ===

IronPython is a python interpreter running within the .NET CLR framework. The ability of IronPython to import .NET assemblies, makes it easy to also interface those to expecco.

Please refer to the IronPython documentation on how to import .NET assemblies.

 --- example to be added ---

== Bridged C Elementary Blocks ==

The following works in 19.2 and above. 
You have to make sure that a C-compiler toolchain is available and can be called directly or indirectly (see [[Installing_additional_Frameworks/en | "Installing additional Frameworks"]]).

Bridged C-code is highly dependent on the C-compiler toolchain of the target machine and may require preparations for machine dependencies with #ifdefs (word length, OS-APIs etc.). It is typically used by experts and for special situations, when simpler alternatives are not available.

Bridged C-code can be used to implement time critical functions or to interface to C/C++ libraries, when the simple DLL-call interface is too complicated to use (for example, if complicated data structures have to be exchanged, if C-callbacks are needed, or if C++ interfaces are to be implemented).

In addition, bridged C-Code actions run in a separate process, isolated from expecco. Thus expecco is not affected by errors in the C-code and cannot be disturbed (eg. by invalid memory references), which is not guaranteed for DLL called functions (which are executed within the expecco process). On the downside, there is some overhead involved in calling a bridged action, since input/output parameters and the call itself are transmitted via an interprocess communication mechanism (i.e. socket/network message). Thus the call roundtrip times are in the millisecond range, as opposed to microseconds for DLL calls.

Other applications are high-speed data acquisition and protocol implementations, in which a C-part is responsible for the time critical task, and expecco can query/control that task remotely (i.e. fetch captured data or state information).

=== The C Bridge ===
Be reminded that bridged C-Code actions are executed inside a separate OS-process, which runs the C-bridge code.
Whenever a bridged C-action is to be executed, the pin-data is transferred via an interprocess communication mechanism (IPC), and the action's code is executed inside the bridge process. Pin data and event requests are transmitted back to expecco via the same IPC mechanism.

The C-bridge itself is available as executable or as shared or linkable library in two configurations, with or without the dynamic C code injection facility.

Setups without code injection are useful to augment (statically compiled) embedded systems with a debug interface, through which expecco can later access specific (and explicitly published) interfaces. In such a setup, no dynamic C-code can be injected into the running application. Instead, the set of callable interfaces must be declared and implemented in advance (in the embedded system).

The following chapter describes the dynamic C-code injection facility as seen by elementary activity code in expecco. For static embedded systems, please refer to the [[Embedded Systems C Bridge API | "Embedded Systems C Bridge API"]].

=== Bridged C Code API ===

Note: This is a preliminary API documentation. Bridged C elementary actions are still being developed and the API may be extended or improved in the future (However, it is very very likely to be backward compatible).

The API is intended to look similar to the other languages' elementary code API.
However, due to the nature and syntax of the C-language, certain differences are apparent. 
The biggest differences are due to C being a statically typed language: the simple "<code>pin.value()</code>" interface for pins (as used in other languages) cannot be offered here; instead, a datatype-specific API is provided in C.

==== Variables Seen by the Executed C Function ====

The following variables are in the scope of the executed function:

*<code>Transcript</code> supports a few functions to display messages in the expecco Transcript window (used as argument; see below)
*<code> Stdout </code> supports a few functions to display messages on expecco's stdout stream (used as argument; see below). This is NOT the same as the stdout FILE*.
*<code> Stderr </code> supports a few functions to display messages on expecco's stderr stream (used as argument; see below). This is NOT the same as the stderr FILE*.


==== Reporting (C) ====

*void '''error''' (char* ''fmt'' , ...) Report a defect (in the test). Stops execution. The arguments are printf-style.

*void '''fail''' (char* ''fmt'', ...) Report a failure (in the SUT). Stops execution. The arguments are printf-style.

*void '''inconclusive''' (char* ''fmt'' , ...) Report an inconclusive test. Stops execution. The arguments are printf-style.

*void '''activitySuccess''' (char* ''fmt'' , ...) Finishes the current activity with success (same as "success()"). The arguments are printf-style.

==== Logging (C) ====

*void '''logFail''' (char* ''fmt'' , ...) Adds a fail message to the activity log, but continues execution. The arguments are printf-style. Notice: although the action continues to be executed, it will be marked as failed at the end.

*void '''logError''' (char* ''fmt'' , ...) Adds a error message to the activity log, but continues execution. The arguments are printf-style. Notice: although the action continues to be executed, it will be marked as erronous at the end.

*void '''logWarning''' (char* ''fmt'' , ...) Adds a warning to the activity log, but continues execution. The arguments are printf-style.

*void '''logInfo''' (char* ''fmt'' , ...) Adds an info message to the activity log, and continues execution. The arguments are printf-style.

*void '''alert''' (char* ''fmt'' , ...) Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" → "''Log -Settings''" dialog (by default it is disabled).

*void '''warn''' (char* ''fmt'' , ...) Same as alert(). (For Smalltalk protocol compatibility)

==== Event Sending (C) ====
*void '''pushEventType_data'''(char* ''event'', char* ''dataOrNULL'') adds an event to expecco's event queue. The payload in ''dataOrNULL'' must be a 0-terminated string.

*void '''pushEventType_dataBytes'''(char* ''event'', unsigned char* ''dataOrNULL'', int ''numBytes'') adds an event to expecco's event queue. The payload in ''dataOrNULL'' points to a byte-buffer of given length.

*void '''pushEventType_dataJSON'''(char* ''event'', jsonObject ''dataOrNULL'') adds an event to expecco's event queue. The payload in ''dataOrNULL'' is a [[Embedded_Systems_C_Bridge_API#JSON_Library|json object]].


==== Pin Functions (C) ====
Currently, C blocks do not support a variable number of input or output pins.

Attention:
 C uses many more reserved keywords for syntax than Smalltalk. These keywords cannot be used as pin names, and you will get a syntax error if you try. Be careful to not name your pins as any of: "<code>return</code>", "<code>char</code>", "<code>int</code>", etc.

As a proven best practice, add a "''Pin''" suffix to your pin names (e.g. name it "''inPin''", instead of "''in''").

===== Input Pins (C) =====

====== Queries ======
*bool_t '''hasValue''' (''inPin'') Returns true if the pin has received a value, where ''true'' is represented as 1, false as 0.

*bool_t '''isConnected''' (''inPin'') Returns true if the pin is connected. This is useful for output pins to avoid computing or sending back values which are not used by expecco.

====== Pin Value ======
'''Scalar Values''' 
*char* '''stringValue''' (''inPin'') Returns the string value at the pin as a c-char*. Raises an error if the pin did not receive a value, or if the value was not a string. [[bild:bulb.png|20px]]Attention: The returned pointer becomes invalid after the action's execution; it should therefore be strcpy'd if it is needed later (i.e. do not keep a reference to it). See keepRef() below to get a pointer which is NOT freed.

*long '''longValue''' (''inPin'') Returns the integer value at the pin as a c-long. Raises an error if the pin did not receive a value, or if the value was not an integer.

*longlong '''longLongValue''' (''inPin'') (vsn24.1, 64bit) Returns the integer value at the pin as a c-longLong. Raises an error if the pin did not receive a value, or if the value was not an integer. This API is only avalable in 64bit versions of the C-bridge (i.e. not in the cBridge32.exe for Windows) and only with expecco vsn 24.1 and later.

*double '''doubleValue''' (''inPin'') Returns the double value at the pin as a c-double Raises an error if the pin did not receive a value, or if the value was not a number.

*bool_t '''booleanValue''' (''inPin'') Returns the boolean value at the pin as a c-int. Raises an error if the pin did not receive a value, or if the value was not a boolean.

'''Vectors''' (aka Arrays / bulk data) 
*uchar* '''bytesValue''' (''inPin'') Returns the byteArray value at the pin as a c-unsigned char*. Raises an error if the pin did not receive a value, or if the value was not a byteArray or C-struct. This can also be used to receive other bulk data, such as an int32 or float array. For example, by converting a collection of numbers first to a byteArray, and then casting the bytesValue to another pointer type in the bridge code. Use <code>arraySize(''inPin'')</code> or <code>bytesLength(''inPin'')</code> to get the number of bytes in the byte[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request. If you need to keep it (for whatever reason), it must be copied to a static or another malloc'd memory area or fetched with keepRef() which is described below.

*ushort* '''shortsValue''' (''inPin'') Returns the shortArray value at the pin as a c-unsigned short*. Raises an error if the pin did not receive a value, or if the value was not an array. Use <code>arraySize(''inPin'')</code> or <code>shortsLength(''inPin'')</code> to get the number of shorts in the short[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request See also keepRef() below.

*uint* '''intsValue''' (''inPin'') Returns the intArray value at the pin as a c-unsigned int*. Raises an error if the pin did not receive a value, or if the value was not an array. Use <code>arraySize(''inPin'')</code> or <code>intsLength(''inPin'')</code> to get the number of ints in the int[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request (see keepRef() below).

*long* '''longsValue''' (''inPin'') Returns the intArray value at the pin as a c-unsigned long*. Raises an error if the pin did not receive a value, or if the value was not an array. Use <code>arraySize(''inPin'')</code> or <code>longsLength(''inPin'')</code> to get the number of longss in the long[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request (see keepRef() below).

*float* '''floatsValue''' (''inPin'') Returns the floatArray value at the pin as a c-float*. Raises an error if the pin did not receive a value, or if the value was not an array. Use <code>arraySize(''inPin'')</code> or <code>floatsLength(''inPin'')</code> to get the number of floats in the float[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request (see keepRef() below).

*double* '''doublesValue''' (''inPin'') Returns the doubleArray value at the pin as a c-double*. Raises an error if the pin did not receive a value, or if the value was not an array. Use <code>arraySize(''inPin'')</code> or <code>doublesLength(''inPin'')</code> to get the number of doubles in the double[]. [[bild:bulb.png|20px]]Attention: the returned array has been allocated with malloc() on the heap, and will be freed after the request (see keepRef() below).

'''Other''' 
*void* '''pointerValue''' (''inPin'') Returns the pointer value at the pin as a <code>void*</code>. This must be a pointer which has been previously sent to expecco via putPointer(). Raises an error if the pin did not receive a value, or if the value was not a pointer. This means, that it must be a pointer as previously sent to expecco with putPointer. Please read the description of "<code>putPointer()</code>" below.

*jsonObject '''jsonValue''' (''inPin'') Returns the value at the pin as a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]]. Raises an error if the pin did not receive a value. [[bild:bulb.png|20px]]The returned pointer becomes invalid after the action's execution; field values should therefore be extracted and copied if needed later (i.e. do not keep a reference to it or its components).

'''Queries''' 
*int '''arraySize''' (''inPin'') Returns the number of array elements, if there is a byte-, short-, int-, float- or double-Array at the pin. Notice that the number of elements is returned, NOT the number of bytes. Raises an error if the pin did not receive a value, or if the value was not an array or C-struct.

'''Values with Default'''
*char* '''stringValueIfAbsent''' (''inPin'', char* ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>stringValue()</code>", but avoids the exception. The returned pointer becomes invalid after the action's execution.

*long '''longValueIfAbsent''' (''inPin'', long ''repl'') (vsn24.1, 64bit) Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>longValue()</code>", but avoids the exception.

*longlong '''longLongValueIfAbsent''' (''inPin'', longlong ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>longLongValue()</code>", but avoids the exception. This API is only avalable in 64bit versions of the C-bridge (i.e. not in the cBridge32.exe for Windows) and only with expecco vsn 24.1 and later.

*double '''doubleValueIfAbsent''' (''inPin'', double ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>doubleValue()</code>", but avoids the exception.

*bool_t '''booleanValueIfAbsent''' (''inPin'', bool_t ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>booleanValue()</code>", but avoids the exception.

*uchar* '''bytesValueIfAbsent''' (''inPin'', uchar* ''repl'') Returns the pin's datum if it has one, ''repl'' otherwise. Similar to "<code>bytesValue()</code>", but avoids the exception. Be aware of automatic freeing unless the pointer is fetched with keepRef().

*jsonObject '''jsonValueIfAbsent''' (''inPin'', jsonObject ''repl'') Returns the pin-datum as a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]] if it has one, ''repl'' otherwise. Similar to "<code>jsonValue()</code>", but avoids the exception. The returned pointer becomes invalid after the action's execution.

*char* '''stringValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, an empty string otherwise. Similar to "<code>stringValue()</code>", but avoids the exception. The returned pointer becomes invalid after the action's execution unless fetched with keepRef().

*long '''longValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, 0 (zero) otherwise. Similar to "<code>longValue()</code>", but avoids the exception.

*longlong '''longLongValueIfPresent''' (''inPin'') (vsn24.1, 64bit) Returns the pin's datum if it has one, 0 (zero) otherwise. Similar to "<code>longLongValue()</code>", but avoids the exception. This API is only avalable in 64bit versions of the C-bridge (i.e. not in the cBridge32.exe for Windows) and only with expecco vsn 24.1 and later.

*double '''doubleValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, 0.0 (zero) otherwise. Similar to "<code>doubleValue()</code>", but avoids the exception.

*bool_t '''booleanValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, 0 (false) otherwise. Similar to "<code>booleanValue()</code>", but avoids the exception.

*uchar* '''bytesValueIfPresent''' (''inPin'') Returns the pin's datum if it has one, NULL otherwise. Similar to "<code>bytesValue()</code>", but avoids the exception.

*jsonObject '''jsonValueIfPresent''' (''inPin'') Returns the pin-datum as a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]] if it has one, NULL otherwise. Similar to "<code>jsonValue()</code>", but avoids the exception. The returned pointer becomes invalid after the action's execution.

*void* '''keepRef''' (''inPin'') (rel. 26.1) Returns a pointer to the malloc's bulk data and tells the bridge that the underlying memory shall NOT be freed when execute() returns. This avoids the need to memcpy big data blocks from the incoming memory buffer; however it is now in your responsibility to free that memory eventually. This is only to be used for strings, bytearrays and other bulk vectors.

Variable number of input/output pins are not supported. You should pass an array or structure if required.

===== Output Pins (C) =====

*bool_t '''isConnected''' (''outPin'') (rel. 26.2) Returns true (1) if the pin is connected, false (0) otherwise. This may be used to avoid generating output values to unconnected pins (useful if the value is expensive to compute or leads to a big data transfer).

* void '''putString''' (''outPin'', char* ''data'') Writes a string to the output pin. The string must be zero-terminated.

* void '''putStringN''' (''outPin'', char* ''data'', int ''len'') Writes len bytes of a string to the output pin.

* void '''putLong''' (''outPin'', long ''data'') Writes a long to the output pin. Be aware that the size of a long depends on the cbridge host's CPU architecture, the OS and the C-compiler: on Unix machines, it is typically an int64, whereas on Windows it is usually an int32.

* void '''putULong''' (''outPin'', unsigned long ''data'') Writes an unsigned long to the output pin. Be aware that the size of an unsigned long depends on the cbridge host's CPU architecture, the OS and the C-compiler: on Unix machines, it is typically an uint64, whereas on Windows it is usually an uint32.

* void '''putLongLong''' (''outPin'', long long ''data'') Writes a long long to the output pin. Typically, a long long is an int64 on all architectures.

* void '''putULongLong''' (''outPin'', unsigned long long ''data'') Writes an unsigned long long to the output pin. Typically, an unsigned long long is an uint64 on all architectures (depends on cbridge host's CPU, OS and compiler). This API is not available in the 32 bit cBridge version.

* void '''putDouble''' (''outPin'', double ''data'') Writes a double (float64) to the output pin.

* void '''putBoolean''' (''outPin'', bool_t ''data'') Writes a boolean to the output pin. Anything but 0 (zero) is interpreted as true.

* void '''putJsonObject''' (''outPin'', jsonObject ''data'') Writes a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]] to the output pin. Refer to [[Embedded_Systems_C_Bridge_API#JSON_Library | the JSON library documentation]] on how to create a [[Embedded_Systems_C_Bridge_API#JSON_Library|jsonObject]].

* void '''putBytesN''' (''outPin'', unsigned char* ''bytes'', int ''nBytes'') Writes nBytes from a byte array to the output pin.

* void '''putPointer''' (''outPin'', void* ''dataPtr'') Writes a reference for dataPtr to the output pin. This value can be passed to another cBridge action (executed on the same bridge), where it can be read from the input with <code>pointerValue()</code> (this is similar to the makeRef mechanism of other bridged languages).

The following API is available since the 21.2 release:

* void '''putDoublesN''' (''outPin'', double* ''doubles'', int ''count'') Writes count double values as a vector to the output pin. expecco will receive these values as a collection of double precision floating point values.

* void '''putFloatsN''' (''outPin'', float* ''floats'', int ''count'') Writes count float values as a vector to the output pin. expecco will receive these values as a collection of single precision floating point values.

* void '''putIntsN''' (''outPin'', int* ''ints'', int ''count'') Writes count int values as a vector to the output pin. expecco will receive these values as a collection of integer values.

* void '''putLongsN''' (''outPin'', long* ''longs'', int ''count'') Writes count long values as a vector to the output pin. expecco will receive these values as a collection of integer values. Be reminded that the sizeof longs may be different between Windows and non-Windows machines.

These vectors will appear at the output pin as a collection; the type of collection is given by the pin's datatype. For most space efficient representation, we recommend the use of the bulk data types (FloatArray, DoubleArray, etc.)

The following API is available since the 21.2.1 update release:

* void '''putShortsN''' (''outPin'', short* ''longs'', int ''count'') Writes count (signed) short values as a vector to the output pin. expecco will receive these values as a collection of integer values.

* void '''putUIntsN''' (''outPin'', unsigned int* ''ints'', int ''count'') Writes count unsigned int values as a vector to the output pin. expecco will receive these values as a collection of integer values.

* void '''putULongsN''' (''outPin'', unsigned long* ''longs'', int ''count'') Writes count unsigned long values as a vector to the output pin. expecco will receive these values as a collection of integer values. Be reminded that the sizeof longs may be different between Windows and non-Windows machines.

* void '''putUShortsN''' (''outPin'', unsigned short* ''longs'', int ''count'') Writes count unsigned short values as a vector to the output pin. expecco will receive these values as a collection of integer values.

==== Transcript, Stderr and Stdout (C) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from C code (as pseudo variables).
However, only a very limited subset of operations is supported (in the following, ''stream'' stands for one of the above wellknown expecco streams and is given as argument to the function):

*void '''cr''' (''stream'') Adds a linebreak (i.e. followup text will be shown on the next line)

*void '''show''' (''stream'', char* ''fmt'', ...) Adds a textual representation of the argument. The argument is printf-style.

*void '''showCR''' (''stream'', char* ''fmt'', ...) A combination of show(), followed by a linebreak.

If the bridge was started by expecco (as opposed to being executed on a remote host), stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").

Thus, you can use "<code>fprintf(stdout, ...)</code>" or "<code>fprintf(stderr, ...)</code>" or "<code>showCR(Transcript, ...)</code>".
 

==== Additional Utility Functions (C) ====

*char* '''getTmpDirectory''' () Returns a pointer to the pathname of the temp directory.

*char* '''getenv''' (char* ''varName'') Returns a pointer to the shell variable's value.

*int '''setenv''' (char* ''varName'', char* ''value'') Set the shell variable's value.

=== Referring to Functions in Shared Libraries ===

If the cBridge code refers to any functions which are located in additional shared libraries (DLLs), the bridge needs to know where to find those.

The location of any shared library must be specified in the C-bridge settings dialog, unless the library is found in the CBridge executable's folder or at a standard place (eg. "/usr/lib", "/usr/local/lib", etc. on Unix and "C:\Windows" and others on Windows).
The details depend on the OperatingSystem; Windows searches along the PATH setting, linux along LD_LIBRARY_PATH. If in doubt, consult your OS documentation.

Navigate to "''Extras''" → "''Settings''" → "''Execution''" → "''External Script Interpreters''" → "''CBridge''" and add the path to the "DLL Path" field.

As an alternative, edit the CC-Script and add appropriate command line arguments to the linker command near the end (it is recommended to keep the original, and make an edited copy).

You'll also have to edit the script, if additional compiler or linkage arguments are required, or if you have to determine the location of additional frameworks dynamically.

=== Referring to Types Defined in expecco ===

User defined struct, union and enum "CType (C-Defined)" dataypes (which are declared in expecco and present in the suite's element tree) are visible inside the activity code, and can be included as:
#include "expecco/Types/XXX.h"
where "XXX" is the name of the expecco type (in the tree).
If the type declares an unnamed struct, the type will be known as a typedef in the C-code.
==== Typedef Name vs. struct/union Name ====
If the type is named "myStruct" and defined as:
struct {
...
}
it should be referred to in the C-code as:
myStruct s, *sP;
In this case, the name of the typedef is the name of the type.

In contrast, if it was defined as:
struct foo {
...
}
you can also write:
struct foo s;
struct foo *sP;
In other words, there will be a typedef for "myStruct" (the name of the type) and a struct by the name as in the type's definition.

Notice, that these files do actually not exist; instead, the activity's C-code is scanned and dynamically expanded to include those definitions. See example below.
You should shutdown any already running bridge, when a type is changed, to enforce a recompilation of the C code.

=== Including Attachments as Header Files ===

Attached files can be included as:
#include "expecco/Attachments/XXX.h"
where "XXX.h" is the name of the expecco attachment file.
 Be reminded that the name of the attachment itself (the tree-item name) is not required to be the same as the name of the file, although usually, they are.

=== C++ Interfaces ===
C++ functions should be called indirectly via a C function wrapper (i.e. <code>extern "C"</code>).
 Object references can be passed from the bridge to expecco and back via the "<code>putPointer</code>" and "<code>pointerValue</code>" functions.

=== Running Bridged C-Code on a Remote Computer ===

The remote computer must have the cBridge executable running.
The executable is found in the "<code>packages/bridgeFramework/cBridge/cLibrary</code>" folder under your expecco installation folder and should be copied to the remote machine. Windows users will find both a 64bit version ("cBridge.exe") and a 32bit one ("cBrige32.exe"). If your C-code needs or refers to any existing dll, make sure that the correct bridge is configured in the settings (a 32bit bridge will not be able to load a 64bit dll and vice versa).

On the expecco side, you have two options:
# specify that the bridge is already running in the settings; then all cBridge actions which have not been explicitly given a bridge to execute in will be executed there
# explicitly connect to a running bridge via the "''Connect to Running Bridge''" action block, and passing the resulting bridge handle to the C-action.
The handle can be passed either explicitly via the step's cBridge input pin, or implicitly by declaring a variable named "<code>CBRIDGE</code>" and storing the handle there. The cBridge input pin is generated via the step's ''Special Pins'' menu.
 If the CBRIDGE variable is declared in a compound action, it will be valid by all actions executed from that and below that action. This makes it possible to run actions on multiple bridges without explicitly passing the bridge handles around via input pins.

Bridges can be started either by one of the bridge start actions in the standard library or by a batch-, shell- or powershell script. Type "<code>cBridge --help</code>" for command line options.

You can have multiple bridges running, even in heterogenous networks (i.e. call for a remote C-action on a Windows machine, while running expecco on a Linux machine).
We provide bridge executables for additional architectures (eg. Raspberry-PI) upon request and for a small additional fee.

=== Running Multiple Bridges in Parallel ===

You can start multiple bridges via the "[Start new local CBridge]" action from the standard library and remember the bridge connection handles in variables. 
[[Datei:Setup.png|300px]] Make sure, that the bridges are using different ports.

In addition, add a bridge input pin to the action(s) which you want to execute on one of those bridges (via the "Special Pins" popup menu in the action's schema). [[Datei:ShowTempDir.png|300px]] 
For example, the following simply sends a message to the standard error:
static void
execute() {
char buffer[128];

snprintf(buffer, sizeof(buffer), "%s", getTmpDirectory());
putString(output, buffer);
}
and finally, here is an example which executes this action in parallel on
4 bridges: [[Datei:FourActions.png|300px]].

=== Bulk Data ===

If a huge number of data elements (known as "''Bulk Data''") are to be transferred, transmission times may get much longer than the actual execution time of the action (keep in mind that the communication times take most of the time if the executed computation is simple).

If the cBridge runs on the same machine as expecco, shared memory will be used to exchange bulk data. This may reduce the transmission times drastically, depending on the amount of data (there are still other messages exchanged via the socket communication).

===== Data from C to Expecco =====
* Passing a Pointer to expecco
:if you can leave the data inside the bridge (eg. as malloc'd data vector), '''and''' expecco does not need to access the elements of the vector, you can leave the data inside the cBridge and only pass a handle to expecco. This handle may later be sent to another C-action (on the same bridge) to process the data at non-critical times (eg. at the end of the test).
:This mechanism is the fastest because only a small handle (typically 32/64 bits) has to be transmitted to expecco. However, it degrades to become very very slow if you access individual elements of the vector from expecco, as this will result in one IPC roundtrip per accessed element.
* Passing Bulk Data as a Vector
:If each vector element is sent individually to an output pin (eg. in a loop with <code>putFloat</code> or <code>putDouble</code>), one IPC roundtrip will be performed per element.
:It is much faster to send the whole vector data sent as one array via putDoublesN(), putFloatsN() or putIntsN(). This still does introduce some additional cost due to JSON-encoding (on the cBridge side) and JSON-decoding on the expecco side, but the effective transmission time is dramatically reduced.
* Passing Bulk Data as a ByteArray
:Further speedup is possible by not sending the data as a number vector, but instead as a byte vector, actually sending the raw ended bytes from the bridge to expecco. For this, use a putBytesN() call and case your bulk data to a "char *" 1).
:However (big warning): expecco will receive a byte-vector and you will have to add code to extract the relevant elements from this. If the cBridge CPU and the expecco-CPU use a different byte order or a different floating-point-number representations, you will have to deal with that in that extraction code. Be aware, that it may even depend on the compiler: Microsoft VisualC compilers for x86_64 interpret "long" as a 32bit integer, whereas most other compilers/systems treat them as 64bit integers. 
:This is probably the fastest method to transmit bytes, but comes with those possible pitfalls. We therefore recommend to try the "Bulk Data as Vector" method first. In most situations that is either within the acceptable timing constraints, or too far off, such that the ByteArray transmission will also not be fast enough, and you should use the pointer passing method anyway.

===== Passing Data from Expecco to C =====
Be aware that the bulk data pointer you receive at an input pin has been allocated
in malloc'd memory which is freed when the execute() function returns. If the data is to be retained inside the C bridge (or passed to a function which keeps a reference), you have two choices:
* memcpy the data into an internal buffer
* tell the caller that the buld data should not be freed on return from execute
The second variant is available with expecco 26.1, and preferred. In either case, it is in your responsibility to free the memory when no longer needed.

1)Starting with expecco 26.1, this is no longer required - there are now additional fast bulk transfer entries named: <code>putFloatsN</code>, <code>putDoublesN</code> etc.

=== Example1: Writing and Calling C Code in Expecco ===

In this example, numbers and a string will be passed to a C action block. The action has been defined with 3 input pins:
* <code>in1</code> (type Float)
* <code>in2</code> (type Integer)
* <code>in3</code> (type String)
and the single output "<code>out1</code>", with type String.

The code will generate a string by concatenating the printf strings of its arguments at the output
and also print a number of messages via different output channels.

Create a new bridged C action, 
[[Datei:CBridge Demo Action1.png]]
 and enter the code:

static void
execute() {
double dVal = '''doubleValue'''(in1); // fetch input pin's double value
long lVal = '''longValue'''(in2); // fetch input pin's integer value
char* sVal = '''stringValue'''(in3); // fetch input pin's string value
char buffer[512];

snprintf(buffer, sizeof(buffer), "%s / %ld / %g", sVal, lVal, dVal);

// write to output pin
'''putString'''(out1, buffer);

// a regular print
// (will be shown inside expecco's Transcript, if io-trace is enabled)
fprintf(stderr, "hello on stderr from C-Code!\n");

// another regular print
// (will be shown inside expecco's Transcript, if io-trace is enabled)
fprintf(stdout, "hello on stdout from C-Code!\n");
// explicit output to expecco's Transcript

// explicit output to expecco's stdout
'''show'''(Stdout, "hello on expecco's stdout from C-Code!\n");

// explicit output to expecco's stderr
'''show'''(Stderr, "hello on expecco's stderr from C-Code!\n");

// explicit output to expecco's Transcript
'''show'''(Transcript, "another hello from C-Code!\n");

// possibly report failure to expecco
if (strlen(sVal) < 20) {
'''fail'''("short string \"%s\" (length=%d)", sVal, strlen(sVal))
}
}

=== Example2: Passing Complex Objects to and from C-Code (by value) ===

Complex struct objects can be passed by value to the C-code by defining a CStruct type
i.e. create a new type named eg. "myStruct" in the tree, define it as C-Type and enter a definition similar to:

/* C: */
struct {
int i1;
float f1;
double d1;
char c[20];
}

then, add an input pin with that datatype to the C-action,
and add the following line to the action's C-code, to include the type's definition:

#include "expecco/Types/myStruct.h"

(the name of the include must match the type's typename in the tree)

From within your C-code, access the fields with:

struct myStruct* p;

p = (struct myStruct*)'''bytesValue'''(inPin);

fprintf(stderr, "got i1:%d\n", p->i1);
fprintf(stderr, "got f1:%f\n", p->f1);
fprintf(stderr, "got d1:%F\n", p->d1);
fprintf(stderr, "got c:%s\n", p->c);

and write such a struct to an output pin with:

'''putBytesN'''(outPin, p, sizeof(struct myStruct));

To create such a struct argument, use an instance creation action block (and possibly additional field setter actions).
Those can be automatically generated by selecting the type in the tree,
and invoking the popup menu function "''Refactoring''" → "''Generate''" → "''Creators and Accessors''".

=== Example3: Passing Handles/Pointers to expecco and Back to Another C Action ===

A common situation is when two C actions are given, where one generates a handle (i.e. pointer),
which must be passed to the other action (in the same bridge).
 For example, the first may be a "<code>createConnection()</code>" function,
and the second needs that connection handle as argument (that would typically be a kind of "<code>send()</code>", "<code>receive()</code>" or "<code>close()</code>" function, and the handle something like a FILE pointer or Windows handle).

For this scenario, the cBridge provides a mechanism similar to the "<code>makeRef</code>" facility of other bridges.
The first action function will send the handle to an output pin via "<code>putPointer()</code>";
the pin's datatype should be "<code>Any</code>", "<code>Handle</code>" or a struct type as described above:

void execute() {
...
'''putPointer'''( outPin, (void*) handle );
}

and the other action functions can get this handle from an input pin:

void execute() {
handle = '''pointerValue'''( inPin );
...

=== Example4: Passing Bulk Data to expecco and to another C Action ===

In this example, one generates some data (eg. a vector of float values),
and passes this to another C action (possibly in another bridge).
 For example, the first may be a measurement value collector,
and the second computes some statistical analysis.
Be aware, that this example was created for demnstration; in practice, you would probably pass a pointer within the same bridge. But the example is also useful if one of those actions is a non-C action, for example a Python numpy action.

The first action function generates some data and sends them to an output pin.
The pin's datatype should be "<code>float*</code>" or "<code>FloatArray</code>":

#define NUM_FLOATS 1024 // or whatever
void execute() {
float data[NUM_FLOATS];
...
// compute or generate the data
for (i=0; i<NUM_FLOATS; i++) {
data[i] = ...
}
...
// send it to the output pin
'''putFloatsN'''( outPin, data, NUM_FLOATS );
}

the receiving action can get this data from an input pin (also with type "<code>float*</code>" or "<code>FloatArray</code>"):

void execute() {
float* data;
int numElements;

// receive from an input pin
// always verify the size!
// The data could have been created by any action with any size!
data = '''floatsValue'''( inPin );
numElements = '''arraySize'''( inPin );
...
// processing
for (i=0; i<numElements; i++) {
... do something with data[i] ....
}
...
}

== Bridged Smalltalk Elementary Blocks ==

The following works in 20.1 and above. 
Similar to the above described bridged Node and bridged Python actions, these actions are coded in the Smalltalk language and executed by a separate Smalltalk engine (separate process). Both local and remote execution are possible.

By the time of writing, bridged Smalltalk actions can be executed in an ST/X Smalltalk engine, support for VA-Smalltalk and VW-Smalltalk is being developed and will be available in one of the next expecco releases.

=== Bridged Smalltalk Code API ===

Note: This is a preliminary API documentation.
Bridged Smalltalk elementary actions are still being developed and the API may change slightly until officially released.

Bridged Smalltalk actions will execute in another Smalltalk system; by the time of writing, this may be another Smalltalk/X or a VisualWorks Smalltalk system. With enough customer interest, other dialects (VisualAge and Squeak) may be supported in the future.

The API looks similar to the API of regular Smalltalk actions, which execute inside expecco itself.
However, for some objects, only a subset of the protocol is available.

==== Variables (Bridged Smalltalk) ====

The following variables are in the scope of the executed code:

*<code>Transcript</code> a proxy which supports a few functions to display messages in the expecco Transcript window (see below)
*<code> Stdout </code> a proxy supports a few functions to display messages on expecco's stdout stream (see below)
*<code> Stderr </code> a proxy supports a few functions to display messages on expecco's stderr stream (see below)

 

==== Reporting (Bridged Smalltalk) ====

*'''error''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Report a defect (in the test). Up to 4 optional with:-args are sliced into the string, if it contains "%i" placeholders. Stops execution.

*'''fail''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Report a failure (in the SUT). Stops execution.

*'''inconclusive''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Report an inconclusive test. Stops execution.

*'''activitySuccess''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Finishes the current activity with success (same as "success()").

*'''pass''':''infoString'' [ '''with''':''arg1'' ... '''with''':''arg4'' ] Finishes the current testCase with success.
 

==== Logging (Bridged Smalltalk) ====

*'''logFail''':''messageString'' Adds a fail message to the activity log.

*'''logError''':''messageString'' Adds a error message to the activity log.

*'''logWarning''':''messageString'' Adds a warning to the activity log.

*'''logInfo''':''messageString'' Adds an info message to the activity log.

*'''alert''':''messageString'' Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" → "''Log Settings''" dialog (by default it is disabled).

*'''warn''':''messageString'' Same as ''alert:'' (for JavaScript compatibility).
 

==== Environment Access (Bridged Smalltalk) ====
*'''environmentAt'''(<varName>); Fetches and returns a value from the expecco environment which is in scope of the current activity. You can only read simple objects (numbers, booleans and strings) from remote smalltalk actions.

*'''environmentAtPut'''(<varName>, <newValue>); Writes a value into the expecco environment which is in scope of the current activity. The variable must be writable. You can only write simple objects (numbers, booleans and strings) from remote smalltalk actions.

 

==== Input Pins (Bridged Smalltalk) ====

*''pin'' '''hasValue''' Returns true if the pin has received a value

*''pin'' '''value''' Returns the value of the pin. Raises an error if the pin did not receive any value.

*''pin'' '''valueIfAbsent''':''alternativeValue'' Returns the value of a pin or the value from alternativeValue if the pin did not receive any value.

*''pin'' '''valueIfPresent''' Returns the value of a pin or nil if the pin did not receive any value.

*''pin'' '''isConnected''' Returns true if the pin has a connection
 

==== Output Pins (Bridged Smalltalk) ====

*''pin'' '''value''':''someValue'' Writes the value to the pin. Only simple object can be transferred by value (nil, booleans, integers, floats, strings). Anything else should be passed by reference (see makeRef below).
 

==== Transcript, Stderr and Stdout (Bridged Smalltalk) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from remote Smalltalk images.
However, only a limited subset of messages is supported:

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show''':''arg'' Adds a textual representation of the argument, which can be a string, number or any other object.

*'''showCR''':''arg'' A combination of show(), followed by a linebreak.

*'''nextPutAll''':''string'' String writing

*'''nextPutLine''':''string'' String printing with cr

In addition, stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").
 

==== Passing Objects by Reference (Bridged Smalltalk) ====
By default, objects written to output pins via "'''value:'''" will be marshalled to JSON, transferred to expecco and decoded there.
Effectively, a copy of the object is created, which looses its identity when sent back later to the remote smalltalk in another action.
This would make it impossible to get handles from a remote action, which is to be sent to another action on the same remote machine.
The "makeRef" method solves this.

*''self'' '''makeRef''':''object'' creates a reference object, which can be written to a pin.

*''self'' '''makeRef''':''object'' '''name''':''aString'' ditto, but gives it a user friendly name (eg. for the expecco log)

I.e. to write a reference to a pin, use:
''somePin'' '''value''':(self '''makeRef''':''someObject'')

=== Additional Information on Bridged VisualWorks Smalltalk Actions ===

Inside bridged VisualWorks actions, the above described "Transcript" refers to the expecco Transcript; not the VisualWorks Transcript (the remote code is compiled inside an environment, where the Transcript variable has been redefined).

To send output to the VisualWorks Transcript, use "Smalltalk.Core.Transcript", as in:
...
Smalltalk.Core.Transcript show:'Hello on VW Transcript'; cr
...
Transcript show:'Hello on expecco Transcript'; cr
...
Be aware, that the VW Transcript does not understand the "showCR:" message; you need "show:" followed by "cr".

== Bridged Ruby Elementary Blocks ==

Note: This is a preliminary API documentation.
Bridged Ruby elementary actions are still being developed and the API may change slightly until officially released.

Bridged Ruby actions will execute in a Ruby interpreter.

The API looks similar to the API of regular actions, which execute inside expecco itself or another language interpreter.
However, due to Ruby language specifics, some differences are noticable.

==== Variables (Bridged Ruby) ====

The following variables are in the scope of the executed code (notice the "$" prefix; Ruby requires global variables to be prefixed by a "$" character):

*<code>$Transcript</code> a proxy which supports a few functions to display messages in the expecco Transcript window (see below)
*<code> $Stdout </code> a proxy which supports a few functions to display messages on expecco's stdout stream (see below)
*<code> $Stderr </code> a proxy which supports a few functions to display messages on expecco's stderr stream (see below)

*<code> $Dialog</code> a proxy which supports a few functions to display confirmation dialogs (see below)
 

==== Reporting (Bridged Ruby) ====

*'''error'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Report a defect (in the test). Up to 4 optional args are sliced into the string, if it contains "%i" placeholders. Stops execution.

*'''fail'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Report a failure (in the SUT). Stops execution.

*'''inconclusive'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Report an inconclusive test. Stops execution.

*'''activitySuccess'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Finishes the current activity with success (same as "success()").

*'''pass'''(''infoString'' [ ,''arg1'' ... ,''arg4'' ]) Finishes the current testCase with success.
 

==== $Transcript, $Stderr and $Stdout (Bridged Ruby) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are also accessible from Ruby actions (with a $-prefix).
Notice, that $Stderr refers to expecco's stderr and $Stdout refers to expecco's stdout. Both may be (and usually are) different from the Ruby interpreter's STDERR/STDOUT.

*'''cr''' () Adds a linebreak (i.e. followup text will be shown on the next line)

*'''show'''(''arg'') Adds a textual representation of the argument, which can be a string, number or any other object.

*'''showCR'''(''arg'') A combination of show(), followed by a linebreak.

*'''nextPutAll'''(''string'') String writing

*'''nextPutLine'''(''string'') String printing with cr

*'''puts'''(''string'') String printing with cr

In addition, stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").

 

==== $Dialog (Bridged Ruby) ====

*'''confirm'''(''msg'') Opens a simple yes/no dialog; returns a boolean.

*'''request'''(''msg'') Opens a simple string-input dialog; returns a string or nil if cancel was pressed.

*'''requestPassword'''(''msg'') same, but the entered string is not shown on the screen

*'''requestFilename'''(''msg'') asks for a filename
 

==== Logging (Bridged Ruby) ====

*'''logFail'''(''messageString'') Adds a fail message to the activity log.

*'''logError'''(''messageString'') Adds a error message to the activity log.

*'''logWarning'''(''messageString'') Adds a warning to the activity log.

*'''logInfo'''(''messageString'') Adds an info message to the activity log.

*'''alert'''(''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" → "''Log Settings''" dialog (by default it is disabled).

*'''warn'''(''messageString'') Same as ''alert:'' (for JavaScript compatibility).
 
==== Environment Access (Bridged Ruby) ====
*'''environmentAt'''(<varName>); Fetches and returns a value from the expecco environment which is in scope of the current activity. You can only read simple objects (numbers, booleans and strings) from ruby actions.

*'''environmentAtPut'''(<varName>, <newValue>); Writes a value into the expecco environment which is in scope of the current activity. The variable must be writable. You can only write simple objects (numbers, booleans and strings) from ruby actions.

 

==== Input Pins (Bridged Ruby) ====

*''pin''.'''hasValue'''() Returns true if the pin has received a value

*''pin''.'''value'''() Returns the value of the pin. Raises an error if the pin did not receive any value.

*''pin''.'''valueIfAbsent'''(''alternativeValue'') Returns the value of a pin or the value from alternativeValue if the pin did not receive any value.

*''pin''.'''valueIfPresent'''() Returns the value of a pin or nil if the pin did not receive any value.

*''pin''.'''isConnected'''() Returns true if the pin has a connection
 

==== Output Pins (Bridged Ruby) ====

*''pin''.'''value'''(''someValue'') Writes the value to the pin. Only simple object can be transferred by value (nil, booleans, integers, floats, strings). Anything else should be passed by reference (see <code>makeRef</code> below).
 

==== Passing Objects by Reference (Bridged Ruby) ====
By default, objects written to output pins via "'''value:'''" will be marshalled to JSON, transferred to expecco and decoded there.
Effectively, a copy of the object is created, which looses its identity when sent back later to the remote ruby in another action.
This would make it impossible to get a handle from a remote action, which is to be sent to another action on the same remote machine.
The "<code>makeRef</code>" method solves this, by creating a "pointer" or "handle" to the object inside the remote machine.

*'''makeRef'''(''object'') creates a reference object, which can be written to a pin.

*'''makeRef'''(''object'', '''name''') ditto, but gives it a user friendly name (eg. for the expecco log)
:I.e. to write a reference to a pin, use:
::: ''somePin''.'''value'''('''makeRef'''(''someObject''))

== Bridged Dart Elementary Blocks ==
planned for one of the next expecco versions

== Bridged Scheme Elementary Blocks ==

Note: As of rel26.1, this is a preliminary API documentation.

 Bridged Scheme elementary actions are still being developed and the API may change slightly until officially released.

Bridged Scheme actions will execute in a Scheme interpreter (currently only Racket, but other dialects will follow).

The API looks similar to the API of regular actions, which execute inside expecco or another language interpreter.
However, due to Scheme being a functional language, and we do not want to depend on any object model (which we may have to port), the API is written to run on a bare scheme.

==== Variables (Bridged Scheme) ====

The following variables are in the lexical scope of the executed code:

*<code>Transcript</code> a proxy object by which the stream functions can send messages to the expecco Transcript (see below)
*<code> Stdout </code> same for the standard output (see below)
*<code> Stderr </code> same for the standard error (see below)


==== Reporting (Bridged Scheme) ====

*('''error''' ''infoString'' [ ''arg1'' ... ]) Report a defect (in the test). Optional args are sliced into the string, if it contains "%i" placeholders. Stops execution.

*('''fail''' ''infoString'' [ ''arg1'' ... ]) Report a failure (in the SUT). Stops execution.

*('''inconclusive''' ''infoString'' [ ''arg1'' ... ]) Report an inconclusive test. Stops execution.

*('''activitySuccess''' ''infoString'' [ ''arg1'' ... ]) Finishes the current activity with success (same as "success()").

*('''pass''' ''infoString'' [ ''arg1'' ... ]) Finishes the current testCase with success.
 

==== Transcript, Stderr and Stdout (Bridged Scheme) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are accessible from Scheme actions.
Notice, that Stderr refers to expecco's stderr and Stdout refers to expecco's stdout. Both may be (and usually are) different from the Scheme interpreter's STDERR/STDOUT.

*('''cr''' ''stream'') Adds a linebreak (i.e. followup text will be shown on the next line; eg. <code>(cr Transcript)</code>)

*('''show''' ''stream'' ''arg'' ...) Adds a textual representation of the arguments, to the stream. Eg. <code>(show Stderr "the result is" 123 "\n")</code>.

*('''showCR''' ''stream'' ''arg'' ...) A combination of (show ...), followed by a (cr).

*('''nextPutAll''' ''string'') String writing

*('''nextPutLine''' ''string'') String printing with cr

In addition, stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").

 

==== Dialog (Bridged Scheme) ====

--- unfinished --
*('''confirm''' ''msg'') Opens a simple yes/no dialog; returns a boolean.

*('''request''' ''msg'') Opens a simple string-input dialog; returns a string or nil if cancel was pressed.

*('''requestPassword''' ''msg'') same, but the entered string is not shown on the screen

*('''requestFilename''' ''msg'') asks for a filename
 

==== Logging (Bridged Scheme) ====

*('''logFail''' ''messageString'') Adds a fail message to the activity log.

*('''logError''' ''messageString'') Adds a error message to the activity log.

*('''logWarning''' ''messageString'') Adds a warning to the activity log.

*('''logInfo''' ''messageString'') Adds an info message to the activity log.

*('''alert''' ''messageString'') Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" → "''Log Settings''" dialog (by default it is disabled).

*('''warn''' ''messageString'') Same as ''alert:'' (for JavaScript compatibility).
 

==== Environment Access (Bridged Scheme) ====
*('''environmentAt''' <varName>) Fetches and returns a value from the expecco environment which is in scope of the current activity. You can only read simple objects (numbers, booleans and strings) from scheme actions.

*('''environmentAtPut!''' <varName> <newValue>) Writes a value into the expecco environment which is in scope of the current activity. The variable must be writable. You can only write simple objects (numbers, booleans and strings) from scheme actions.

 

==== Input Pins (Bridged Scheme) ====

*('''pin-hasValue?''' ''pin'') Returns #tif the pin has received a value

*('''pin-value''' ''pin'') Returns the value of the pin. Raises an error if the pin did not receive any value.

*('''pin-valueIfAbsent''' ''pin'' ''alternativeValue'') Returns the value of a pin or the value from alternativeValue if the pin did not receive any value.

*('''pin-valueIfPresent''' ''pin'') Returns the value of a pin or nil if the pin did not receive any value.

*('''pin-isConnected?''' ''pin'') Returns true if the pin has a connection
 

==== Output Pins (Bridged Scheme) ====

*('''pin-value!''' ''pin'' ''someValue'') Writes the value to the pin. Only simple object can be transferred by value (nil, booleans, integers, floats, strings). Anything else should be passed by reference (see <code>makeRef</code> below).
 

==== Passing Objects by Reference (Bridged Scheme) ====
By default, objects written to output pins via "('''pin-value!''' ...)" will be marshalled to JSON, transferred to expecco and decoded there.
Effectively, a copy of the object is created, which looses its identity when sent back later to the remote ruby in another action.
This would make it impossible to get a handle from a remote action, which is to be sent to another action on the same remote machine.
The "<code>makeRef</code>" method solves this, by creating a "pointer" or "handle" to the object inside the remote machine.

*('''makeRef''' ''object'') creates a reference object, which can be written to a pin.

*('''makeRef''' ''object'' ''name'') ditto, but gives it a user friendly name (eg. for the expecco log)
:I.e. to write a reference to a pin, use:
::: ('''pin-value!''' ''somePin'' ('''makeRef''' ''someObject''))

== Bridged Octave Elementary Blocks ==

Note: As of rel26.1, this is a preliminary API documentation.

 Bridged Octave/Matlab elementary actions are still being developed and the API may change slightly until officially released.

Bridged Octave actions will execute in a GNU Octave interpreter.

The API looks similar to the API of regular actions, which execute inside expecco or another language interpreter.

==== Variables (Bridged Octave) ====

The following variables are in the lexical scope of the executed code:

*<code>Transcript</code> a proxy object by which the stream functions can send messages to the expecco Transcript (see below)
*<code> Stdout </code> same for the standard output (see below)
*<code> Stderr </code> same for the standard error (see below)


==== Reporting (Bridged Octave) ====

Notice these have been named with an "ex_" prefix to avoid name conflicts with the existing builtin error function and the others for name consistency.

*'''ex_error'''(''infoString'', [''arg1'', ... ]) Report a defect (in the test). Optional args are sliced into the string, if it contains "%i" placeholders. Stops execution.

*'''ex_fail'''(''infoString'', [''arg1'', ... ]) Report a failure (in the SUT). Stops execution.

*'''ex_inconclusive'''(''infoString'', [ ''arg1'', ... ]) Report an inconclusive test. Stops execution.

*'''ex_activitySuccess'''(''infoString'', [ ''arg1'', ... ]) Finishes the current activity with success (same as "success()").

*'''ex_pass'''(''infoString'', [ ''arg1'', ... ]) Finishes the current testCase with success.
 

==== Transcript, Stderr and Stdout (Bridged Octave) ====

The expecco "<code>Transcript</code>", "<code>Stderr</code>" and "<code>Stdout</code>" are accessible from Scheme actions.
Notice, that Stderr refers to expecco's stderr and Stdout refers to expecco's stdout. Both may be (and usually are) different from the Scheme interpreter's STDERR/STDOUT.

*'''show'''(''stream'', ''arg'', ...) Adds a textual representation of the arguments, to the stream. Eg. <code>show(Stderr, "the result is", 123, "\n")</code> sends it to expecco's stderr.

*'''showCR'''(''stream'', ''arg'', ...) A combination of (show ...), followed by a (cr).

*'''nextPutAll'''(''string'', ...) String writing

*'''nextPutLine'''(''string'', ...) String printing with cr

*'''cr'''(''stream'') Adds a linebreak (i.e. followup text will be shown on the next line; eg. <code>(cr Transcript)</code>)

In addition, stdout and stderr are also forwarded to the expecco Transcript window, depending on the settings in expecco ("''Extras''" → "''Settings''" → "''Execution''" → "''Tracing''" → "''Show Stdout and Stderr on Transcript''").

 

==== Dialog (Bridged Octave) ====

*'''confirm'''(''msg'', ...) Opens a simple yes/no dialog; returns a boolean.

*'''request'''(''msg'', ...) Opens a simple string-input dialog; returns a string or nil if cancel was pressed.

*'''requestPassword'''(''msg'', ...) same, but the entered string is not shown on the screen

*'''requestFilename'''(''msg'', ...) asks for a filename
 

==== Logging (Bridged Octave) ====

*'''logFail'''(''messageString'', ...) Adds a fail message to the activity log. Multiple args are concatenated.

*'''logError'''(''messageString'', ...) Adds a error message to the activity log.

*'''logWarning'''(''messageString'', ...) Adds a warning to the activity log.

*'''logInfo'''(''messageString'', ...) Adds an info message to the activity log.

*'''alert'''(''messageString'', ...) Adds a warning message to the activity log, and also shows a DialogBox, which has to be confirmed by the operator. The dialog box and confirmation can be disabled by a settings flag in the "''Execution''" → "''Log Settings''" dialog (by default it is disabled).

*'''warn'''(''messageString'', ...) Same as ''alert:'' (for compatibility with other languages).
 

==== Environment Access (Bridged Octave) ====
*'''environment_get'''(<varName>) Fetches and returns a value from the expecco environment which is in scope of the current activity. You can only read simple objects (numbers, booleans and strings) from octave actions.

*'''environment_set'''(<varName> <newValue>) Writes a value into the expecco environment which is in scope of the current activity. The variable must be writable. You can only write simple objects (numbers, booleans and strings) from octave actions.

 

==== Input Pins (Bridged Octave) ====

*'''pin_value'''(''pin'') Returns the value of the pin. Raises an error if the pin did not receive any value.

*'''pin_valueIfAbsent'''(''pin'', ''alternativeValue'') Returns the value of a pin or the value from alternativeValue if the pin did not receive any value.

*'''pin_valueIfPresent'''(''pin'') Returns the value of a pin or nil if the pin did not receive any value.

*'''pin_hasValue'''(''pin'') Returns true if the pin has received a value

*'''pin_isConnected'''(''pin'') Returns true if the pin has a connection
 

==== Output Pins (Bridged Octave) ====

*'''pin_send_value'''(''pin'', ''someValue'') Writes the value to the pin. Only simple object can be transferred by value (nil, booleans, integers, floats, strings). Anything else should be passed by reference (see <code>makeRef</code> below).
 

==== Passing Objects by Reference (Bridged Octave) ====
By default, objects written to output pins via "'''pin_send_value'''(...)" will be marshalled to JSON, transferred to expecco and decoded there.
Effectively, a copy of the object is created, which looses its identity when sent back later to the remote ruby in another action.
This would make it impossible to get a handle from a remote action, which is to be sent to another action on the same remote machine.
The "<code>makeRef</code>" method solves this, by creating a "pointer" or "handle" to the object inside the remote machine.

*'''makeRef'''(''object'') creates a reference object, which can be written to a pin.

*'''makeRef'''(''object'', '''name''') ditto, but gives it a user friendly name (eg. for the expecco log)
:I.e. to write a reference to a pin, use:
::: '''pin_send_value'''(''somePin'', '''makeRef'''(''someObject''))

== DotNET Elementary Blocks ==

Editing support for C# is provided with vsn 26.2. However, .NET objects can also be instantiated and methods be called via the transparent message forwarning mechanism provided by Smalltalk. This means, that you use Smalltalk code to send (Smalltalk-) messages to proxy objects, which forward the call information to the corresponding bridge object.

You can also use bridged IronPython actions and refer to the assembly or objects from there.

=== C# Actions ===
The API available follows the other bridged action APIs:
==== Input Pin Functions (bridged C#) ====
* object = inPin.value()
* objectOrNull = inPin.valueIfPresent()
* object = inPin.valueIfAbsent(''default'')
* bool = inPin.hasValue()
* bool = inPin.isConnected()
==== Output Pin Functions (bridged C#) ====
* outPin.value(''value'')
==== Variables (bridged C#) ====
* string = environmentAt(''varName'')
* environmentAtPut(''varName'', ''stringValue'')

==== Logging (bridged C#) ====
* logInfo(''message'')
* logWarning(''message'')
* logError(''message'')
* logFail(''message'')
==== Dialogs (bridged C#) ====
* bool = Dialog.confirm(''message'')
* string = Dialog.request(''message'')
* string = Dialog.requestPassword(''message'')
* string = Dialog.requestFilename(''message'')

== VisualBasic Elementary Blocks ==

Support for VisualBasic Script elementary block execution is provided as an extension plugin, and requires a separate plugin license.
It is only available for expecco running on the MS Windows operating system.

Code written as a VisualBasic elementary block is not executed directly by expecco. Instead, the code is forwarded to a VisualBasic scripting host which runs as another process either on the local or on a remote host. The scripting host must be a Microsoft Windows host (but expecco itself may run on any type of operating system). By using VisualBasic blocks, expecco's basic black box test functionality can be easily extended by many powerful gray- and white-box tests. Many libraries for device and equipment control, COM/DCOM and other technologies and UI interaction are possible with the VisualBasic plugin.

Please consult the separate [[VBScript/en | VisualBasic plugin documentation]] for more detail.

== Shell, Batch and other Script Elementary Blocks ==
There is no special API for those, except for pin-value expansion and stdin/stdout/stderr handling.
All of this is described in the [[ElementaryBlock_Element/en#Script_Action_Blocks | "Script Action Blocks" documentation]]

== Remote expecco Elementary Blocks ==

These run on a remote expecco system, and can be used to generate load (stress) or perform additional measurements.
Remote expecco actions will be available in or after the 24.2 expecco version.

--- to be documented ---

== Tutorial: Common Tasks ==

This chapter gives code fragments and examples for common tasks.

The underlying Smalltalk class library contains (among others) very powerful and robust collection, stream and number representation systems, of which many functions are useful for elementary block developers. The set of usable functions is much larger than for example in Java or C standard libraries. Thus for a newcomer to Smalltalk, it is highly recommended and fruitful to read the introduction texts and/or use the class browser for a deeper understanding. You can benefit from existing code and save a lot of development time in knowing a little about your class libraries.

Also, it is a good idea to try the sample code in a "workspace" window or within the code editor,
by selecting the piece of code to be tried, and performing the "''printIt''" menu function.
Thus you can quickly test&try code fragments without a need for an elementary block and its setup.

Or use the [[How_to_Program/en#MethodFinder:_Find_Functions_by_Example|MethodFinder]] tool to find operations.

=== String Handling ===

Notice, that in Smalltalk all collection indices are 1-based. I.e. the index of the first element is 1, and the last index is the collection's size. This is the same in Mathematica, but different in C, JavaScript, Java and others.
Thus Smalltalk loops over collection elements should run from 1 to the collection's size, not from zero to the size minus 1. You will get an index exception, if you try.

Also notice, that index-based enumerations (i.e. loops from 1 to the size) are actually seldom needed, due to the powerful "<code>do:</code>", "<code>collect:</code>", "<code>select:</code>" etc. family of enumeration methods.
These do all the index computations for you, and are often heavily tuned for better performance.

Also notice, that in Smalltalk, String is a subclass of Collection, and most of the functions described below are actually not implemented in the String class, but inherited from a superclass. Take this into consideration, when searching for String utility functions in the class browser (i.e. look there first or click on the "''See Inherited Methods''" button in the class browser [[Datei:SeeInheritedInBrowser.png]] ).
On the other hand, the fact that most of those functions are implemented in the Collection superclass also means, that they work on many other collections (Arrays, ByteArray, OrderedCollection, Set, Dictionary etc.).

If you are in doubt, open a [[Tools_Notepad/en|Workspace]] window, enter a piece of code and evaluate it (using the "''printIt''" menu function).
Or open the [[How_to_Program/en#Find_Functions_by_Example|Method Finder]] to find an operation given the desired outcome.

==== Copying Parts of a String ====

To extract a substring, and the index and/or count is known, use one of:

''aString'' copyFrom: ''startIndex'' to: ''stopIndex''

''aString'' copyFrom: ''startIndex''

''aString'' copyTo: ''stopIndex''

''aString'' copyFrom: ''startIndex'' count: ''n''

''aString'' copyFirst: ''count'' "/ same as copyTo:

''aString'' copyLast: ''count'' "/ gives the last count characters

''aString'' copyFrom: ''startIndex'' butLast: ''count'' "/ copy except the last count characters

All of the above will copy including the character at the start- and stop index.
I.e.
'hello world' copyFrom:2 to:5
will return 'ello'.
 [[Datei:point_right.png|20px]]This is different from some C/Java functions, which usually expect the stopIndex to be one-after the last copied element.
===== Search & Copy =====
to search for a character and copy up to that character's position, use:
''aString'' copyUpTo: ''characterToSearch''

''aString'' copyFrom:''startIndex'' upTo: ''characterToSearch''

You can also search backward from the end (i.e. the last occurrence of a character):
''aString'' copyUpToLast: ''characterToSearch''

==== Finding Elements and Substrings ====

To search for elements of a string (which are characters), use:

''aString'' indexOf: ''aCharacter''
''aString'' indexOf: ''aCharacter'' startingAt: ''startIndex''

and:

''aString'' lastIndexOf: ''aCharacter''
''aString'' lastIndexOf: ''aCharacter'' startingAt: ''startIndex''

to search backward from the end.

 [[Datei:point_right.png|20px]]The Smalltalk methods return a 1-based index, and 0 (zero) if not found.

[[Datei:point_right.png|20px]]Notice that a character constant is written in Smalltalk as <code>$<x></code>, where <x> is a printable character or a space. Non-printable characters must be specified by their name ("<code>Character return</code>", "<code>Character lf</code>", "<code>Character tab</code>") or their Unicode-point (decimal: "<code>Character value: 127</code>" or hex: "<code>Character value: 16r1F00</code>").

If there are multiple characters to be searched for, pass a collection of searched characters to one of:

''aString'' indexOfAny: ''aBunchOfCharacters''
''aString'' indexOfAny: ''aBunchOfCharacters'' startingAt: ''startIndex''

for example,

'hello world' indexOfAny: 'eiou' startingAt:3

looks for the next vocal at or after position 3.

Both receiver and argument may actually be any kind of Collection;
thus:
''aString'' indexOfAny: #( $a $A $e $E )

works the same.

Finally, there is a very generic search function, where you can pass a test-procedure as argument:

''aString'' findFirst:[:ch | ...a boolean test on ''ch'' ...]

will return the index of the next character for which your boolean check computes a true value.
For example, to search for the next digit, use:
''aString'' findFirst:[:ch | ch isDigit]

to search for a digit OR period OR dollar character, you can use one of:

''aString'' findFirst:[:ch | ch isDigit or:[ ch == $. or:[ ch == $$]]]
''aString'' indexOfAny:'0123456789$.'

use whichever you find more readable.
(there is also a "<code>findFirst:startingAt:</code>", and corresponding "<code>findLast:</code>" and "<code>findLast:startingAt:</code>" for backward searches)

Because it is a common task to search for separators and other non-printable characters,
special methods exist for those:

''aString'' indexOfSeparatorStartingAt: ''startIndex''
''aString'' indexOfNonSeparatorStartingAt: ''startIndex''
''aString'' indexOfControlCharacterStartingAt: ''startIndex''

where separators are the whitespace characters (space, tab, vt, cr and lf),
and control characters are all characters below ASCII 32.

All of the index-search methods return a 0 (zero) if the character is not found.

Substrings can be searched with:

''aString'' indexOfString: ''anotherString''
''aString'' indexOfString: ''anotherString'' startingAt: ''startIndex''
''aString'' indexOfString: ''anotherString'' caseSensitive: false
''aString'' indexOfString: ''anotherString'' startingAt: ''startIndex'' caseSensitive: false

''aString'' indexOfString: anotherString startingAt: startIndex

''aString'' indexOfSubCollection: ''anotherString''
''aString'' indexOfSubCollection: ''anotherString'' startingAt: ''startIndex''

There are also corresponding backward search variants "<code>lastIndexOfSubCollection:</code>".

Notice the somewhat generic names "<code>indexOfSubCollection:</code>" instead of a more intuitive "<code>indexOfString:</code>".
The reason is that these methods are inherited from collection, which does not care if the elements are
characters or other objects (<code>indexOfString:</code> is an alias for <code>indexOfSubCollection:</code>).

This means, that you can use the same method to search for a slice in an array:

#(1 2 3 4 5 6 7 8 9 8 7 6 5 1 2 3 2 1) indexOfSubCollection:#(9 8 7)

using the same code.

To find all such methods in the class browser, search for implementors of "<code>*indexOf*</code>", and look at the matches in <code>Collection</code>, <code>SequenceableCollection</code>, <code>CharacterArray</code> and <code>String</code>.

==== If you don't need the Index ====

If you only need to check if a character or substring is present, but not its position,
you can use "<code>includes:</code>", "<code>includesString:</code>", "<code>includesString:caseSensitive:</code>", "<code>includesSubCollection:</code>", "<code>includesAny:</code>" or "<code>includesAll:</code>" in a similar spirit.
These may be slightly faster and make the code more readable. They return a boolean.

==== Caseless Searches ====

For strings, special substring searches are available, which ignore case (upper/lower) differences:

''aString'' includesString: ''anotherString'' caseSensitive: false
''aString'' indexOfString: ''anotherString'' caseSensitive: false

==== Prefix and Suffix Checks ====

''aString'' startsWith: ''anotherString''
''aString'' endsWith: ''anotherString''

are obvious.
The powerful:

''aString'' startsWithAnyOf: ''aCollectionOfStrings''

searches for multiple string prefixes. For example,

'hello' startsWithAnyOf: #( 'ab' 'ce' 'de' )

would look for all of them and return false in this concrete example.
Of course, there is a corresponding "<code>endsWithAnyOf:</code>".

==== Splitting Parts of a String (or Collection) ====

The simplest are:

''aString'' asCollectionOfWords

''aString'' asCollectionOfLines

which split at separators and line-ends respectively and return a collection as they say in their name.

More generic is:

''aString'' js_split: charOrString

which returns a collection of substrings split at "''charOrString''" elements. as the name suggests, you can pass either a single character or a substring as argument.
Thus:

'hello world isn't this nice' js_split:(Character space)

will give you the strings <code>('hello' 'world' 'isnt' 'this' 'nice')</code>.
Whereas:
'some : string : separated : by : space : colon space' js_split:' : '
will return a collection containing: <code>('some' 'string' 'separated' 'by' 'space' 'colon' 'space')</code>.

Notice, that we used "<code>js_split:</code>" in the above examples, which is the method used by JavaScript's "<code>split()</code>" function. This is because in Smalltalk, the "<code>split:</code>" method has a different semantics: the receiver is a "''splitter''", and the argument is splitted by it.
 In Smalltalk, the splitter can be both a simple string or a [[Regex Pattern Info| regular expression]]. For example:

'[a-z]*' asRegex split:'123abc456def789'

will generate the collection: <code>#('123' '456' '789')</code>.

To split into same-sized pieces, use:

''aString'' splitForSize: ''charCount''

this may be less of interest for strings, but is handy to split fixed records of binary data (remember: these functions are implemented in a superclass of <code>String</code>, from which <code>ByteArray</code> also inherits).

==== Joining and Concatenating Strings ====

The simplest of them is the "," (comma) operator. This takes two collections (and as such also Strings) and creates a new collection containing the concatenation of them.
Thus:

'hello' , 'world'

will create a new string containing 'helloworld',
and:
'hello' , ' ' , 'world'

will give you 'hello world',
 and:
#(1 2 3) , #(4 5 6)
will generate a 6-element array containing the elements 1 to 6.

Notice that concatenation may become somewhat inefficient, if many strings are concatenated,
because many temporary string objects are created. Its time complexity is O(n2), where n is the number of strings concatenated.

If you have to construct a string from many substrings, either use one of the join functions below with O(n) complexity,
or a writeStream with O(n log n) complexity (eg. the <code>streamContents:</code> message).
Both handle the reallocations much more efficiently (actually: avoiding most of them).

To join a set of strings, use:

''asCollectionOfStrings'' asStringWith: ''separator''

where separator may be a character, a separator string or nil.
For example:
#( 'a' 'b' 'c') asStringWith:nil
gives 'abc',
and:
#( 'a' 'b' 'c') asStringWith:' : '
returns: 'a : b : c'

Using a writeStream, write:

|w result|

w := WriteStream on:(String new:10).
w nextPutAll: 'a'.
w nextPutAll: 'b'.
...
result := w contents

or, using a convenient utility method (which does exactly the same):

result := String streamContents:[:s |
s nextPutAll: 'hello'.
s nextPutAll: 'world'.
...
s nextPutAll: 'Nice world'
].

but please read more on streams in the stream chapter below.

==== Formatting Strings (Method A) ====

For text messages, you may want to construct a pretty user readable string which contains printed representations of other objects.
For this, use:
''formatString'' bindWith: ''argument''

''formatString'' bindWith: ''argument1'' with: ''argument2''

''formatString'' bindWith: ''argument1'' with: ... with: ''argumentN'' (up to 5 arguments)

''formatString'' bindWithArguments: ''argumentCollection'' (any number of arguments)

using the "<code>{ .. }</code>" array constructor (notice the periods as expression separators), this is usually written as:

''formatString'' bindWithArguments: { ''argument1'' . ''argument2'' . ... . ''argumentN'' }

The formatString itself may contain "%X" placeholders, which are replaced by corresponding
printed representations of the argumentX. The arguments will be converted to strings if they are not, thus arbitrary objects can be given as argument (although, in practice, these are usually numbers).

If many arguments are to be passed in,
the placeholder names X may consist of a single digit (1-9) only for the first 9 arguments.
For other arguments, you must write "%(X)". I.e. '%(10)' to get the tenth argument sliced at that position (1).

The last of the above methods is a powerful tool, in that it does not only handle argumentCollections indexed by numbers (i.e. Array of arguments), but also Dictionaries, which are indexed by name.

For example, if you have a Dictionary collection of a person record (in expecco: a compound datatype instance), with element keys "firstName", "lastName" and "city",
you can generate a nice printed string with:

|record|

record := Dictionary new. "/ example using a dictionary
record at:'firstName' put: 'Fritz'.
record at:'lastName' put: 'Müller'.
record at:'city' put: 'Stuttgart'.

'%(lastName), %(firstName) lives in %(city)' bindWithArguments: record.

gives you the string: 'Müller, Fritz lives in Stuttgart'.
 In combination with a expecco compound datatype instance, this would be:

|person|

person := myType new.
person firstName:'Fritz'.
person lastName:'Müller'.
person city:'Stuttgart'.

'%(lastName), %(firstName) lives in %(city)' bindWithArguments: person.

1) Note: this has been relaxed in 19.2, where %10 is allowed. However, all digits up to the first non-digit character will make up the index. If you need a sliced in value followed by a digit, you'd still have to use %(x).

==== Formatting Strings with Printf (Method B) ====
There is also a formatting method similar to "<code>printf</code>". It takes a format string and a number of arguments and constructs a string representation.
As Smalltalk does not support variable numbers of arguments, these must be passed with different keyword messages:

''formatString'' printfWith:''arg''

''formatString'' printfWith:''arg1'' with:''arg2''

''formatString'' printfWith:''arg1'' with:''arg2'' with:''arg3''
... up to 5 arguments

''formatString'' printf:''argVector''

For the argVector, use the "{" .. "}" construct.

For example,

'%05d 0x%-7x %f' printf:{ 123 . 517 . 1.234 }
generates the string:
'00123 0x205 1.234'

The above provides the functionality of C's "sprintf" - i.e. it generates a string as result. However, streams also understand printf-messages, so you can also print directly to a stream:

Transcript printf:'%05x\n' with:12345
or:
Transcript printf:'%05x %d %f %o\n' withAll:{ 123. 234*5. 1.234. 254 }

Notice, that printf translates the standard C-character escapes "\n", ”\t" etc.

==== Formatting Strings with Embedded Expressions (Method C) ====
A string constant prefixed with "e" is a so called expression-string. This may contain Smalltalk expressions enclosed in "<code>{..}</code>", which are sliced into the string (actually, the expression's printString is sliced in). In addition, C-style escape sequences like "\n" are recognized in e-strings.
 Example:

Transcript show: e'today is {Date today} and the time is {Time now}\nAnd the dayName is {Date today dayName}'.

==== Regex and Glob Matching ====

Both match a string against a match pattern, but the syntax and functionality is different.
* Glob is much easier to use but less powerful. Glob is the match algorithm used in the Unix and MS-DOS filesystem (e.g. when saying "<code>ls *.foo</code>" or "<code>dir *.foo</code>" on the command line).
* [[Regex Pattern Info| Regex]] is the algorithm used in tools like "grep" and many text processing systems and languages.

Notice that regex patterns are different and not just a superset of glob patterns. Especially the meanings of "*" and "." are different.
 
Please consult Wikipedia for more information on Regex [https://en.wikipedia.org/wiki/Regular_expression] and GLOB [https://en.wikipedia.org/wiki/Glob_%28programming%29].
A chapter on regex is also found in this [[Regex Pattern Info| wiki]].

For a Glob match, use:

''aGlobPattern'' match:''aString''

''aGlobPattern'' match:''aString'' caseSensitive:false

or, reversed argument order, if you prefer:
''aString'' matches:''aGlobPattern''

''aString'' matches:''aGlobPattern'' caseSensitive:false

For a regex match, use:

''aString'' matchesRegex:''aRegexPattern''

''aString'' matchesRegex:''aRegexPattern'' caseSensitive:false

''aString'' matchesRegex:''aRegexPattern'' ignoringCase:true "/ an alias to the above

Sorry for the inconsistent method naming which is due to the fact that the regex matcher originated in a public domain package, which was developed independently from the original ST/X system. In order to remain compatible with other Smalltalk dialects, the names were kept.

The CharacterArray class provides a whole bunch of useful match methods (eg. to extract multiple occurrences of a pattern, to do prefix matches and to extract sub patterns from a complex match pattern). Please use the class browser (from the "''Extras''" → "''Tools''" menu) to find them.

==== Code Converting ====

There are code converters for various character encodings in and below the CharacterEncoder class.
Most of them are obsolete or seldom used these days, as now most systems support Unicode (which was not the case, the ST/X was written 30 years ago and switched to Unicode in the 90's!).

In general, you can get an instance of an encoder via a convenient CharacterEncoder interface:

CharacterEncoder encoderFor:<encoding>

or:

CharacterEncoder encoderToEncodeFrom:<encoding1> to:<encoding2>

where encoding is a name, such as 'iso8859-1', 'unicode', 'utf8', 'utf16', 'ascii', 'jis7' etc.

Thus, to encode a string from Unicode (which is the internal encoding anyway) to Japanese JIS0201, use:

(CharacterEncoder encoderFor:#'jis0201') encode:'hello'

or to encode from Microsoft cp1253 to koi8-r, use:

(CharacterEncoder encoderToEncodeFrom:#'cp1253' to:#'koi8-r') encode:<''someStringInCP1253''>

You will probably not need that general interface, but use UTF-8 these days.
For those, the String class provides easier to use interface:

''aString'' utf8Encoded

''aString'' utf8Decoded

==== Collection Slices ====

A slice is a reference to a subcollection, which looks and behaves like any other collection, but shares the underlying data with the original collection. Thus modifications in either the original or slice are visible in the other and vice versa.

To get a slice, use one of the "<code>from:</code>", "<code>from:to:</code>", "<code>to:</code>" and "<code>from:count:</code>" methods (the names are similar to the above mentioned "copy*" methods).

For example:

data := ... some big ByteArray read from a file ...

record1 := data from:1 to:recordSize.
record2 := data from:(recordSize+1) to:recordSize*2.
etc.

gives you the records from the big collection as individual objects. If any modification is made to any of the slices, that modification is actually made in the underlying data collection (i.e. C-Programmers may think of this as a "''pointer into the data object''").

Slices are especially useful with bulk data processing, to avoid the creation of individual record copies.

However, they are a bit dangerous, as the programmer has to be always aware of possible side effects. If you are uncertain, do not pass a slice to another (unknown) function; instead use the corresponding copy methods.

=== Stream Handling ===

Streams can be both internal streams (streaming out-of or into a collection) or external streams.
External streams are always byte- or character-oriented and operate on files, sockets, pipes or i/o devices.
An internal stream's element type depends on the underlying collection, but String-streams are most common.

The following presents only a very small excerpt of the full stream protocol.
Please refer to the online documentation of the Smalltalk/X stream classes.

==== Creating (Internal Streams) ====

streams for reading:
rs := ReadStream on:''aCollection''.

rs := ''aCollection'' readStream

streams for writing:
ws := WriteStream on:(String new:''initialSize'')

ws := '' writeStream

ws := WriteStream on:(Array new)

notice that the underlying collection is reallocated when more elements are added due to nextPut: operations.
The reallocations are done by doubling the size, resulting in O(n log n) complexity. If you have a rough idea on the final size, preallocating with an initialSize avoids or reduces the number of reallocations.

==== Checking ====

''s'' atEnd
returns true iff the read stream "s" is positioned at the end.
''s'' size
returns the size of the read stream's buffer, or the number of elements written into a write stream.

==== Positioning ====

''s'' position

returns the stream's current read position, starting at 0 when at the beginning.
I.e. position represents the number of elements which have already been read or written.

''s'' position:''pos''

set the position.

''s'' rewind

reset the position to the beginning

''s'' setToEnd

set the position to the end (normally only useful for appending write streams)

''s'' backStep

position one element backwards

''s'' skip:n

skip n elements when reading

==== Reading ====

''rs'' next

retrieve the next element from the stream. Nil if there are no more elements.

''rs'' next:''count''

retrieve the next "n" elements from the stream.

''rs'' nextAvailable:''count''

retrieve the next "n" elements or whatever number of elements are available.

''rs'' upTo:''element''

retrieve elements up to an element which is equal to "element"

''rs'' skipTo:''element''

skip over elements up to an element which is equal to "element"

''rs'' through:''element''

retrieve elements up-to and including an element which is equal to "element"

''rs'' peek

retrieve the next element from the stream but does not advance the read pointer. Nil if there are no more elements. The next call to any of the above will see this character (again).

==== Writing ====

''ws'' nextPut:''element''

append element to the stream.

''ws'' next:''count'' put:''element''

append element multiple times to the stream.

''ws'' nextPutAll:''aCollectionOfElements''

append all elements from the given collection to the stream.

''ws'' println

append a newline character.

''ws'' cr

also

''ws'' nextPutLine:''aCollectionOfElements''

append all elements from the given collection followed by a newline to the stream.

''ws'' print:''anObject''

append a printed representation of anObject (for humans) to the stream.

''ws'' store:''anObject''

append the printed representation of anObject (for the system) to the stream.
Unless the object has recursive references, a copy of the element can be reconstructed with <code>Object readFrom:</code>''aReadStream''

''ws'' println:''anObject''

append a printed representation of anObject (for humans) to the stream, followed by a newline.

''ws'' printCR:''anObject''

the same

''ws'' contents

retrieve the stream's contents (typically, the characters buffered so far)

==== File Streams ====

''aString'' asFilename readStream

''aString'' asFilename writeStream

See more below in the chapter on [[#File_Operations |file operations]].

=== Numbers ===

==== Reading Numbers from a String ====

To read a number from a string, use the "readFrom:" method provided by the number classes,
where the argument is either a string, or a headstream.
A readstream is obtained with either "<code>(ReadStream on:''aString'')</code>" or the more convenient "<code>(''aString'' readStream)</code>".

Thus, in general, code to read a number looks like:
<class> '''readFrom:''' ''aString''
or:
<class> '''readFrom:''' (ReadStream on:''aString'')
or:
<class> '''readFrom:''' (''aString'' readStream)

where "<class>" is one of "<code>Integer</code>", "<code>Float</code>", "<code>FixedPoint</code>" or "<code>Number</code>".
If "<class>" is "<code>Number</code>", any type of number will be read and returned. Otherwise, only that type of number will be accepted (i.e. "<code>Integer readFrom:''String''</code>", will report an error if there is a decimal point in the string.

If the string contains nothing but the number string, the above two code expressions behave the same.
However, there is an often overlooked difference in case of extra characters after the number:

* the string-reader expects that the given string contains a representation of a corresponding number object, and NO extra characters before or after it. It will report an error otherwise.

* in contrast, the stream reader will first skip any spaces, then read as many characters as required from the stream, return the number and leave the stream positioned after the number. It will report an error if no number can be read. More values can be read from the stream if required.

Thus both:
Integer '''readFrom:''' '1234'
and:
Integer '''readFrom:''' (ReadStream on:'1234').

return the Integer object 1234.

Whereas:
Integer '''readFrom:''' '1234bla'
will raise an error, but:
myStream := ReadStream '''on:''' '1234bla'.
Integer '''readFrom:''' myStream.

returns the integer 1234 and leave the stream positioned on the 'bla'. Thus further elements can be read from the stream later.

Notice that "<code>Integer readFrom:</code>" will read an integer, but not a float.
Thus:
Integer '''readFrom:''' '1234.5'
will raise an error, but:
Integer '''readFrom:''' (ReadStream on:'1234.5').

will return the Integer object 1234 and leave the stream positioned on the decimal point character.

When expecting an arbitrary number (e.g. with or without decimal point),
use:
Number '''readFrom:''' ''aStringOrStream''
which will return either an integer object or a float object depending on what it gets.

If you want to enforce getting a float, use
Float '''readFrom:''' ''aStringOrStream''
which returns the float "1234.0", even when given the string "1234".

The above assumes that a period is the decimalpoint character; use:
Number '''readFrom:''' ''aStringOrStream'' '''decimalPointCharacter:''' ''decimalPointCharacter''
if another character is expected (eg. $, for a German number),
or use:
Number '''readFrom:''' ''aStringOrStream'' '''decimalPointCharacters:''' ''decimalPointCharacters''
to allow for a number of characters (given as Array of characters or as String).
Thus:
Number readFrom:myString decimalPointCharacters:',.'
will accept either English or German numbers.

===== Error handling =====

By default, the readers raise an exception, if any conversion error occurs.
This can be caught in an error handler as described elsewhere (hint: catch the error with "<code>on:do:</code>").

However, the conversion routines can also be given a correction function as argument,
which is invoked in case of an error, and which provides a replacement value. This is easier and shorter to write then an exception handler.

For this, all of the methods described are also present in a variant with an extra "<code>onError:</code>" argument, which provides that replacement.

For example:

Integer '''readFrom:''' ''aString'' '''onError:''' [ 0 ]

will return the number as usual if OK, but zero if not.
 Of course, arbitrary code can be provided inside this handler - especially it may show an error dialog and ask the user for a replacement, or return from the executed elementary block:

val := Integer
'''readFrom:'''aString
'''onError:'''[
|ersatz|
ersatz := Dialog '''request:''''Please enter a correct number'.
Integer '''readFrom:'''ersatz
]

===== Reading with a Different Decimal Point Character =====

If the number was originally for a european, it may contain a decimal point different from "." -
for example, in Germany you may encouter a monetary amount as "1245,99".

For this, use:

Float '''readFrom:''' ''aStringOrStream'' '''decimalPointCharacters:''' ','

or (better):

FixedPoint '''readFrom:''' ''aStringOrStream'' '''decimalPointCharacters:''' ','

If your code has to deal with both US and German numbers, provide all possible decimal points in the string, as in:

FixedPoint '''readFrom:''' ''aStringOrStream'' '''decimalPointCharacters:''' ',.'

===== Reading Multiple Numbers from a Stream =====

A common task is to read multiple numbers from a single long string.
Of course, you could first split the string into pieces and use the above "readFrom:" on each.

This may also be a quick&dirty solution, if the individual number strings are contained in fixed-length fields and there are no separators in between the fields (but read below for a better way to do this).
Take a look at the string handling examples on how to split strings.

To read multiple numbers, the best solution is to first create a read stream on the string, then read the individual numbers:

myString := '1234 456.7 0.5 2345.3456 3234234234234234234234234234234234234'.
myStream := myString '''readStream'''.

n1 := Number '''readFrom:''' myStream. "/ gives the integer 1234 in n1
n2 := Number '''readFrom:''' myStream. "/ gives the float 456.7 in n2
n3 := Number '''readFrom:''' myStream. "/ gives the float 0.5 in n3
n4 := FixedPoint '''readFrom:''' myStream. "/ gives the fixedPoint 2345.3456 in n4
n5 := Number '''readFrom:''' myStream. "/ gives the large integer 3234...34 in n5

Notice that "<code>readFrom:</code>" first skips any separators (spaces) - therefore no extra code is needed to deal with those.

If extra stuff needs to be skipped, use any of the existing stream functions (<code>skipFor:</code>/<code>skipUntil:</code> etc.). If none does the job, you can look at individual characters and skip until a match is found.
For example, to read 3 numbers from the following string '123 bla 456.8|0.5',
you could use:

s := '123 bla 456.8|0.5' readStream.
n1 := Integer '''readFrom:'''s.
s '''skipSeparators'''.
s '''nextAlphanumericWord'''. "/ skips over the 'bla'
n2 := Number '''readFrom:'''s.
s next. "/ skips over one character
n3 := Number '''readFrom:'''s.

of course, the above code would not handle strings like '123 bla bla 456.8|0.5' or '123 bla 456.8 |0.5'.
 Using "peek", which looks at the next character in the stream without consuming it,
we could to change the code to:

n1 := Integer '''readFrom:'''s.
[ s '''peek''' '''isDigit''' ] '''whileFalse:'''[ s '''next''' ]. "/ skips over the 'bla bla'
n2 := Number '''readFrom:'''s.
s '''next'''. "/ skips over one character
n3 := Number '''readFrom:'''s.

Notice that "<code>peek</code>" returns nil, if the end of the stream is reached. And that "<code>nil isDigit</code>" will report an error (because only characters can be asked for being a digit).
Thus, the code like the above is not prepared to read a variable number of numbers.

===== Reading with Scanf =====

There is also a C-like scanf utility, which can read numbers, strings, characters in various formats.

myString := '1234 456.7 0.5 2345.3456 3234234234234234234234234234234234234'.
values := '%d %f %f %f %d' '''scanf:''' myString.

generates a collection of numbers in "values":
OrderedCollection(1234 456.7 0.5 2345.3456 3234234234234234234234234234234234234)

The details and format characters are described in the PrintfScanf utility class, here is a short summary:

Conversions (upper case same as lower case):
* 'b' binary (base 2)
* 'c' character or (first char of string)
* 'd' decimal
* 'e' float
* 'f' float
* 'g' float
* 'i' integer (alias for 'd')
* 'o' base-8 octal
* 's' string
* 'u' integer
* 'x' base-16 hex

Length prefix:

* 'h' with float formats: reads as ShortFloat
* 'L' with float formats: reads as LongFloat

Examples:
* '%d %x' '''scanf:''''1234 ff00' -> OrderedCollection(1234 65280)
* '%d %s' '''scanf:''''1234 ff00' -> OrderedCollection(1234 'ff00')
* '%d %x %b' '''scanf:''''1234 ff00 1001' -> OrderedCollection(1234 65280 9)

==== Reading a Particular Number of Numbers from a Stream ====

Assume that you are given a number which defines how many numbers to extract from a given string.

Of course, you can use a "<code>start to: stop do:[:idx |...</code>" loop,
but experienced Smalltalk programmers make use of the collection protocol,
as in:
(1 to: count) collect:[:idx | Number readFrom:aStream ]

Such a construct is needed e.g. when you have to parse a string, where the first entry defines how many numbers follow:

coll := (1 to: (Integer readFrom:myString)) collect:[:idx | Number readFrom:aStream ].

which would parse the string "5 1.0 3.0 2.0 -1.0 .05" into a 5-element collection containing the converted numbers.

==== Reading a Variable Number of Numbers from a Stream ====

To do so, we should collect numbers as being read from the stream in a collection:

collectedNumbers := OrderedCollection new.

[ aStream atEnd ] whileFalse:[
collectedNumbers add: ( Number readFrom:aStream ).
]

or, if any non-digits and non-spaces between numbers should be skipped,
use:

collectedNumbers := OrderedCollection new.

[ aStream atEnd ] whileFalse:[
aStream skipUntil:[:char | char isDigit].
collectedNumbers add:( Number readFrom:aStream ).
]

==== Using the Pattern Matcher to Extract Parts ====

In rare situations, complex patterns need to be matched and numeric values
retrieved from the matched parts. For this, use a regex pattern matcher to first extract parts from the string, and then convert the substrings.
For example, to fetch numbers after certain keywords in a string, you could use:

"/ assuming that the string is of the form:
"/ <..arbitrary-text...>key1<number1><...arbitrary text...>key2<number><...arbitrary text...>
"/ where arbitrary text may even contain key1 and key2, but not followed by a number,
"/ we first use a regex to match, then convert the matched regex parts:

myString := 'bla bla key1 bla key11234more bla key2 bla key29876bla bla'.

parts := myString allRegexMatches:'((key[12]))([0-9]+)'.
"/ now, parts contains #( 'key11234' 'key29876'
numbers := parts collect:[:eachPart | Number readFrom: (eachPart copyFrom:5) ].
"/ now, numbers contains #( 1234 9876 )

notice that ''parts'' delivers the matched strings i.e. the collection ('key11234' 'key29876'),
so that we have to skip over the 'keyX' prefix before extracting the numbers.

=== File Operations ===

Expecco (i.e. Smalltalk) represents file names as instances of a specialized class called "<code>Filename</code>". These look similar to strings, but provide an abstraction over details of the underlying file- and operating system.

This makes it possible to write portable code which runs on Windows, Linux and even VMS, even though these systems use very different filename separators and volume naming schemes.

Thus, we recommend to use filename operations instead of string concatenation, e.g. to construct pathnames.
In Smalltalk, the abstract class "<code>Filename</code>" is subclassed by concrete classes named "<code>PCFilename</code>" or "<code>UnixFilename</code>".
You should not access those concrete classes explicitly by name!
Instead, always refer to "<code>Filename</code>" and let Smalltalk decide, which concrete class to use.
(unless you know that you are dealing with a unix-style filename, independent of your operating system, which is e.g. the case if you deal with CVS names or you get file-URLS as strings).

for now, a short summary:

''aString'' asFilename - to get a Filename-instance for a given String instance

''aFilename'' readStream - to get a readStream on the contents of a file

''aFilename'' writeStream - to get a writeStream writing to a file

''aFilename'' appendingWriteStream - to get a writeStream appending to the end of a file

==== Checking ====

''aFilename'' exists "/ true if the file exists

''aFilename'' isReadable "/ true if it is readable

''aFilename'' isWritable

''aFilename'' isExecutable "/ for folders, this means: "can be changed into"

''aFilename'' isExecutableProgram

''aFilename'' fileSize

''aFilename'' isDirectory

''aFilename'' isNonEmptyDirectory

''aFilename'' isRegularFile

''aFilename'' isSymbolicLink

''aFilename'' info "/ gets all info; follows any symbolic link. Includes ownerID, groupID, access and modification times etc.

''aFilename'' linkInfo "/ gets all info of a symbolic link itself. Includes ownerID, groupID, access and modification times etc.

''aFilename'' accessTime

''aFilename'' modificationTime

''aFilename'' creationTime "/ (same as modificationTime on Unix systems)

''aFilename'' fileType

''aFilename'' mimeType

==== File names ====

''aFilename'' pathName

''aFilename'' directory "/ the containing directory, as a Filename instance

''aFilename'' directoryName "/ ditto, as string

''aFilename'' baseName

''aFilename'' suffix

''aFilename'' hasSuffix:''aString''

''aFilename'' isAbsolute

''aFilename'' isRelative

''aFilename'' / ''subPath'' "/ yes, "/" is an operator to construct the name of a file inside a folder

''aFilename'' construct:''subPath'' "/ alternative to "/"

==== Operations ====

''aFilename'' makeDirectory

''aFilename'' recursiveMakeDirectory "/ ensures that all folders along the path are also created.

''aFilename'' removeDirectory "/ raises an error, if the folder is not empty

''aFilename'' recursiveRemoveDirectory "/ removes everything below also

''aFilename'' moveTo:''newName''

''aFilename'' copyTo:''newName''

''aFilename'' recursiveCopyTo:''destinationName''

==== Directory Contents ====

''aFilename'' directoryContents

''aFilename'' directoryContentsDo:[:eachFile | ...]

''aFilename'' filesMatching:aGLOBPatternString

==== File Contents ====

''aFilename'' contents
retrieves the contents as a collection of line strings.
Be careful - this should not be used for huge files.

''aFilename'' contentsAsString
retrieves the contents as one (possibly big) string.
Be careful - this should not be used for huge files.

''aFilename'' binaryContentsOfEntireFile
retrieves the contents as one (possibly big) byte array.
Be careful - this should not be used for huge files.

''aFilename'' readingLinesDo:[:eachLineString | ... ]
better use this for large files. Ensures that the file is closed.

''aFilename'' readingFileDo:[:stream | ... ]
or that to read inside the code block. Ensures that the file is closed.

=== Shared Data and Synchronization ===

A number of mechanisms for synchronisation and mutual access to shared data structures are available: <code>Semaphore</code>, <code>RecursionLock</code>, <code>Monitor</code>, <code>SharedQueue</code>, <code>SharedCollection</code> and the <code>synchronized:</code> method, which is understood by every object.
For details, please refer to the Smalltalk/X Online Documentation.

== Examples ==

The following code examples contain versions for Smalltalk, JavaScript, Groovy and Node.js.
Notice that Groovy and Node.js actions are invoked via a remote procedure call ([[Glossary#RPC|RPC]]) mechanism, which means that they are much slower due to the communication, encoding, decoding and general round trip delays. Therefore, Groovy and Node.js blocks (bridged actions in general) should only be used to access data inside the system under test or to call functions which are not available in the base system (such as additional protocols or hardware access, for which only a JAR or node- or python package is available). Or, functions for which the call overhead is small compared to the runtime (i.e. for heavy computing tasks, it may very well make sense).

Thus, most of the examples below are for demonstration purposes, not for real world scenarios (i.e. it will certainly slow down your test runs, if you do math via Groovy or even Node.js, as shown below).

Also bear in mind, that the underlying numeric representations are less flexible and more error-prone if you do math outside Smalltalk:
in Groovy, because there will be no signalling of overflow/underflow situations. Especially with integer arithmetic, which may be outside the 32bit/64bit range. Also, Java has no exact fraction representations, which means that you may loose precision in floating point operations.

Things are even worse in Node.js, which represents all numbers as double precision floats, giving roughly 53 bits of precision. Thus, in Node.js the two integers 12345678901234567890 and 12345678901234567891 will be reported as being equal! (this may change in a future Node version, though).

[[Datei:point_right.png|20px]] Do NOT use Groovy or Node.js for numeric computations, if large integer values are involved (or use a Bignum package).

=== Reading/Writing Pin Values ===

Assuming that the block has two input pins, named "<code>in1</code>" and "<code>in2</code>" and two output pins, named "<code>out1</code>" and "<code>out2</code>",
all of String type,
the following blocks write concatenated strings to both outputs:

===== JavaScript =====
(runs inside expecco when executed)
execute() {
out1.value( in1.value() + in2.value() );
out2.value( in2.value() + in1.value() );
}

===== Smalltalk =====
(runs inside expecco when executed)
execute
out1 value:(in1 value , in2 value).
out2 value:(in2 value , in1 value).

===== Groovy =====
(runs inside the JVM, which may be the system under test or another machine running Java)
def execute() {
out1.value( in1.value() + in2.value() );
out2.value( in2.value() + in1.value() );
}

===== Node =====
(runs inside a node VM, which may be the system under test or another machine running "node")
function execute() {
out1.value( in1.value() + in2.value() );
out2.value( in2.value() + in1.value() );
}

===== Python =====
(runs inside a Python interpreter, which may be the system under test or another machine running "python")
def execute():
out1.value( in1.value() + in2.value() )
out2.value( in2.value() + in1.value() )

===== C =====
static void execute() {
char* s1 = stringValue(in1);
char* s2 = stringValue(in2);
char buffer[512];

snprintf(buffer, sizeof(buffer), "%s%s", s1, s2);
putString(out1, buffer);

snprintf(buffer, sizeof(buffer), "%s%s", s2, s1);
putString(out1, buffer);
}

Note: be aware, that due to the Remote Procedure Call ([[Glossary#RPC|RPC]]), the calling overhead of bridged actions is in the order of milliseconds,
whereas actions executed inside expecco (Smalltalk and JavaScript) are executed typically within a few hundred nanoseconds.

Thus, bridged actions are typically used to invoke longer running, complex operations or to trigger services, which run autonomous, or to talk to interfaces/devices. They are normally not be used for trivial operations like string manipulation or arithmetic.

=== Reading/Writing Environment Variables ===

Assuming that a String-typed environment variable named "''IncDec''" and an Integer-typed variable named "''Counter''" exist in the project's environment, and are writable,
the following blocks read and write to either variable:

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
if ( environmentAt("IncDec") == "inc" ) {
environmentAt_put("Counter", environmentAt("Counter") + 1);
} else {
environmentAt_put("Counter", environmentAt("Counter") - 1);
}
}

===== Smalltalk =====
(runs inside expecco, when executed)
execute
(self environmentAt:'IncDec') = 'inc' ifTrue:[
self environmentAt:'Counter' put:(self environmentAt:'Counter')+1.
] ifFalse:[
self environmentAt:'Counter' put:(self environmentAt:'Counter')-1.
]

===== Groovy =====
(runs inside the JVM, which may be the system under test or another machine running Java).
Notice that the environment-access from inside Groovy involves even more overhead, as those require another RPC call from Groovy back to expecco. When executed, the code below will make 4 full remote-procedure call roundtrips (1 for the call and return value, one for "environmentAt(IncDec)", one for "environmentAt(Counter)" and a fourth one for "environmentAt_put()").

def execute() {
if ( environmentAt("IncDec") == "inc" ) {
environmentAt_put("Counter", environmentAt("Counter") + 1);
} else {
environmentAt_put("Counter", environmentAt("Counter") - 1);
}
}

=== Sending Messages to the Transcript ===
The <code>Transcript</code> refers to the expecco console, if it has been opened (via the "''Extras''" → "''Tools''" menu). If it is not open, "Trnscript" will refer to the standard error stream (Stderr).
In place of "Transcript", the following examples also work for "Stdout" and "Stderr".

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
Transcript.showCR("---------------------");
for (var y=1; y<=10; y++) {
for (var x=1; x<=10; x++) {
Transcript.show( x * y );
Transcript.show( " " );
}
Transcript.cr();
}
}

===== Smalltalk =====
(runs inside expecco, when executed)
execute
Transcript showCR:'---------------------'.
1 to:10 do:[:y |
1 to:10 do:[:x |
Transcript show:(x * y); show:' '.
].
Transcript cr.
].

===== Groovy =====

A few of the common messages and objects for logging and printing are also made available to Groovy code. Of course, a hidden inter-process mechanism is used, which forwards those calls back to expecco (remember: the Groovy code runs inside the system under test). The <code>Transcript</code> object seen by Groovy code is such a proxy object which implements a subset of the Smalltalk Transcript object but passes the argument strings via IPC back to expecco.
So although the code looks similar to the above, the internal implementation (and timing) is completely different, because these calls are implemented as RPC calls from Groovy back to expecco.

(runs inside JavaVM when executed)
def execute() {
Transcript.showCR("---------------------");
for (int y=1; y<=10; y++) {
for (int x=1; x<=10; x++) {
Transcript.show( x * y );
Transcript.show( " " );
}
Transcript.cr();
}
}
For compatibility with existing Java/Groovy code, the functions <code>print()</code> and <code>println()</code> can also be used
(in addition to the above used <code>show()</code>, <code>showCR()</code> and <code>cr()</code> functions)

===== Node =====

A subset of the logging and printing functions are available to Node code. Of course, a hidden inter-process mechanism is used, which forwards those calls back to expecco (remember: the code runs inside the system under test). The <code>Transcript</code> object seen by Node code is such a proxy object which implements a subset of the Smalltalk Transcript object, but passes the argument strings via IPC back to expecco.

So although the code looks similar to the above, the internal implementation (and timing) is completely different, because these calls are implemented as RPC calls from Node back to expecco.

(runs inside Node when executed)
function execute() {
Transcript.showCR("---------------------");
Transcript.show( "hello " );
Transcript.show( "world" );
Transcript.cr();
Transcript.show( "A message with embedded args: %1 and %2\n", "foo", 123);
}
For compatibility with existing Node programs, you can also use "<code>console.log()</code>"
and "<code>console.error()</code>".

=== Square Root Block ===

A function, which computes the square root of its input value, could be implemented like that:
(the names of the pins are: ''in'' and ''out'', their data type is ''Number):

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
var inValue;

inValue = in.value; // Reading input pin value
out.value( inValue.sqrt() ); // Writing to output pin
}
alternative:
execute() {
var inValue;

inValue = in.value; // Reading input pin value
out.value( Math.sqrt(inValue) ); // Writing to output pin
}

===== Smalltalk =====
(runs inside expecco, when executed)
execute
|inValue|

inValue := in value. "/ Reading input pin value
out value: inValue sqrt. "/ Writing to output pin

===== Groovy=====
(runs inside a JVM/the SUT, when executed). As mentioned above, this kind of operation should definitely be executed in Smalltalk/JavaScript inside expecco, and not in the system under test, due to the [[Glossary|RPC]] overheads.
def execute {
Object inValue;

inValue = inPin.value(); // Reading input pin value
outPin.value(Math.sqrt(inValue)); // Writing to output pin
}
(Notice: "in" is a reserved keyword in Groovy and cannot be used as pin name)

===== Node=====
(runs inside Node, when executed).
function execute {
outPin.value(Math.sqrt(inPin.value()));
}
(Notice: "in" is a reserved keyword in Node and cannot be used as pin name)

=== Random-Fail Block ===

A block, which randomly fails (to demonstrate exception handling), could be implemented like:

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
var dice;

dice = Random.nextIntegerBetween_and_(1,6);
if (dice <= 2) {
fail();
}
}

===== Smalltalk =====
(runs inside expecco, when executed)
execute
|dice|

dice := Random nextIntegerBetween:1 and:6.
(dice <= 2) ifTrue:[
self fail.
].

===== Groovy =====
(runs inside a JVM/the SUT, when executed)
execute() {
Random rand = new Random();
int dice = rand.nextInt(5)+1;

if (dice <= 2) {
fail();
}
}

=== Calling other Actions ===

Script code can call other action blocks via the "<code>call</code>" method/function.
Notice, that the call is "''by name''" or "''by ID''", and the called function is specified by a string argument.
The following examples assume that action blocks named "''Action_A''" and "''Action_B''" are present, and that "Action_B" expects two numeric arguments and returns a value through its single output pin.

===== JavaScript =====
(runs inside expecco, when executed)
execute() {
var result;

call("Action_A");
result = call("Action_B", 123.0, 9999);
Transcript.showCR("got result: %1", result);
}
</PRE></CODE>

===== Smalltalk =====
(runs inside expecco, when executed)
execute
|result|

self call:'Action_A'.
result := self call:'Action_B' _:123.0 _:9999).
Transcript showCR:('got result: %1' bindWith:result).

===== Groovy =====
runs inside a JVM/the SUT, when executed, but the called actions are expecco actions;
i.e. the call performs a remote-procedure-call back to expecco, to execute the called action, and continue in the JVM's action when finished.
execute() {
var result;

call("Action_A");
result = call("Action_B", 123.0, 9999);
Transcript.showCR("got result: %1", result);
}

===== Node =====
runs inside the node interpreter, when executed.
The call performs a remote-procedure-call back to expecco, to execute the called action, and continue in the node action when finished.

Notice, that due to the single threaded callback oriented nature of node,
the value from the called function is passed back via a callback function,
not as return value. This is required because the "call" is actually performing
a remote procedure call into expecco (i.e. interprocess communication).
It is also currently not possible to call another node action from a node action (neither directly, nor indirectly).

function execute() {
var result;

Transcript.showCR("calling from Node...");
call("Action_A", function(err, result) {
call("Action_B", 100, 200, function(err, result) {
Transcript.showCR("got value: %1", result);
success();
});
});
}

=== Using the Smalltalk/X Class Library (Smalltalk and JavaScript Blocks Only) ===

Please note, that besides these direct interfaces with the expecco system described here, you can also use the whole class library of the runtime system. Please check the corresponding [http://live.exept.de/doc/online/english/programming/TOP.html Smalltalk/X Documentation] as well as the [http://live.exept.de/ClassDoc Documentation of the Class APIs].

expecco includes a fully featured class browser, to explore the underlying system's code.

You will see the source code, if you have checked the "''Install Source Code''" checkbox during the installation procedure (if you did not, redo the installation, and only check this box). You can also access the source code via the public eXept CVS repository.

The class browser is opened via the main-menu's "''Extras''" → "''Tools''" → "''Class Browser''" item. It is documented in full detail in the [http://live.exept.de/doc/online/english/programming/TOP.html Smalltalk/X Documentation].

Here are a few more examples, using that class library:

=== Bulk-Data Reading from a File ===

The following code reads a measurement data block of 100000 floating point values from file. The file was created beforehand by a recorder device, which was triggered by a dll-callout.
For the demonstration, the code below does not read its values from input pins. In a real world application, the size of the file and its fileName would probably be passed in via input pins, of course.

===== JavaScript =====
execute() {
var N; // should be read from an input-pin
var fileName; // should be read from an input-pin
var dataArray;
var fileStream;

N = 100000;
fileName = 'dataFile.dat';
fileStream = fileName.asFilename().readStream();
dataArray = Array.new(N);
for (i=1; i<=N; i++) {
dataArray[i] = fileStream.nextIEEESingle();
}
out.value(dataArray);
}

===== Smalltalk =====
execute
|N fileName dataArray fileStream|

N := 100000.
fileName := 'dataFile.dat'.
fileStream := fileName asFilename readStream.
dataArray := (1 to:N) collect:[:i | fileStream nextIEEESingle].
out value:dataArray.
an alternative is:
...
dataArray := N timesCollect:[:i | fileStream nextIEEESingle].
...

=== Opening/Using Smalltalk/X Applications, Dialogs and Components ===

Any existing Smalltalk/X utility (both the one's which are provided with the base system, and even those coming from additional loaded Smalltalk code) can be called and used. For example, the following uses the builtin file dialog to ask for a directory.

===== JavaScript =====
execute() {
var answer;

answer = Dialog.requestDirectory("Please select an output folder:");
if ( answer.notEmptyOrNil() ) {
out.value( answer );
}
}

===== Smalltalk =====
execute
|answer|

answer := Dialog requestDirectory: 'Please select an output folder:'.
answer notEmptyOrNil ifTrue:[
out value: answer
]

Take a look at the "Dialog" class (using "''Extras''" - "''Tools''" - "''Class Browser''"),
where you'll find many common standard dialogs, for confirmations, simple questions, file dialogs etc.

=== Loading Additional Smalltalk/X Code ===

You can even create whole library or application packages, compile it as separate package, and load it dynamically to be used from within an elementary block. Assuming that a package named "myPackage.dll" (or "myPackage.so" under Unix/Linux) containing an application class named "MyApplication" has been created and is located in the expecco bin folder, the code can be loaded and executed with:

===== Smalltalk =====
execute
|answer|

Smalltalk loadPackage:'myPackage'. "/ checks if already loaded, to only load the first time called
MyApplication open.

To create your own applications or addons, download the free [http://www.smalltalk-x.de Smalltalk/X development IDE ] for development and package building.

== Expecco and Smalltalk API Stability ==

The Smalltalk/X class library has been around for more than 30 years now,
and of course grew over time.
We have always tried hard to keep the API backward compatible, in not removing existing methods, even when new methods appeared, which provided a similar or superset functionality.

Thus, code written 30 years ago can still depend on the interface and it is still working unchanged.

We will continue to keep this backward compatibility in the future,
to avoid breaking customer code, whenever possible (there were very few exceptions in the past, where obvious bugs had to be fixed, and customer code already depended on the wrong behavior).

That said, we must emphasize on that being only true for the ST/X class libraries themselves, and any officially published expecco APIs from this document.

If you use internal expecco functionality (which you may find when browsing in the class browser),
we cannot guarantee backward compatibility in future versions.
If you feel a need for using such an interface, please consult/inform eXept to either get help on a cleaner solution, and/or inform us that the API is used and to get your used interface be marked as "stable EXPECCO_API".

== Appendix ==

=== Smalltalk Language Syntax (BNF) ===

See also: [http://rosettacode.org/wiki/Category:Smalltalk Smalltalk Short Description (in rosettacode wiki)], [http://live.exept.de/doc/online/english/getstart/tut_2.html Smalltalk Basics]

;; Notice: an elementary Smalltalk action's "execute" method is a unary method (no argument).
;; there can be only one single such method in an elementary action (private functions should be defined as Smalltalk blocks)
;;
;; This is standard Smalltalk language, with Smalltalk/X language extensions
;;
method ::= selectorSpec body

selectorSpec> ::= unarySelectorSpec
| binarySelectorSpec
| keywordSelectorSpec

unarySelectorSpec ::= symbol

binarySelectorSpec ::= binopSymbol identifier

keywordSelectorSpec ::= ( keywordSymbol identifier )+

body ::= [ "|" localVarList "|" ] [statements]

localVarList ::= ( identifier )+

statements ::= statement
| statement "."
| statement "." statements

statement ::= expression
| returnStatement

returnStatement ::= "^" expression

expression ::= identifier ":=" expression
| keywordExpression

keywordExpression ::= binaryExpression
| binaryExpression ( keywordSymbolPart binaryExpression )+

binaryExpression ::= unaryExpression
| unaryExpression ( binopSymbol unaryExpression )+

unaryExpression ::= primary
| primary ( unarySymbol )+

primary ::= identifier
| literalConstant
| expandedStringExpression
| braceArray
| "(" expression ")"
| block
| "self"
| "super"

identifier ::= ( "_" | "a"-"z" | "A"-"Z") ( "_" | "a"-"z" | "A"-"Z" | "0"-"9" )*

literalConstant ::= integerConstant
| radixIntegerConstant
| floatConstant
| arrayConstant
| byteArrayConstant
| stringConstant
| characterConstant
| "true"
| "false"
| "nil"

integerConstant ::= ( "0"-"9" )+

radixIntegerConstant ::= base "r" baseDigits+

base ::= integerConstant (valid are: 2-31)

baseDigits := "0"-"9" | "A"-"Z" | "a"-"z" (valid are "0".."0"+base-1 and "a".."a"+base-10-1 and "A".."A"+base-10-1)

floatConstant ::= [ "-" ] [ digits+ ] "." [ digits+ ] [ ("e" | "E" | "d" | "D") [ "-"] digits+ ]

arrayConstant ::= "#(" literalConstant* ")"

byteArrayConstant ::= "#[" integerConstant(0..255)* "]"

stringConstant ::= ' characters... '
| cString

characterConstant ::= "$" character

block ::= "[" [ blockArgList ] body "]”

blockArgList ::= (identifier":" )*

comment ::= " " " any-character* " " " | eolComment

unarySymbol ::= identifier

binopSymbol ::= ( "+" | "-" | "*" | "/" | "\" | "," | "@" | "%" | "&" | "=" | "<" | ">" | "~" )+

keywordSymbolPart ::= identifier":"

keywordSymbol ::= keywordSymbolPart+

symbolConstant ::= "#"unarySymbol
| "#"binarySymbol
| "#"keywordSymbol
| "#'"any-character*"'"

==== Smalltalk/X Language Extensions (BNF) ====

Smalltalk/X provides a few very useful syntax extensions w.r.t. standard Ansi Smalltalk:

eolComment ::= " "/ " any-character-up-to-end-of-line

tokenComment ::= " "<<"TOKEN
...
any number of lines not beginning with TOKEN
(where TOKEN is any valid identifier string)
...
TOKEN

braceArray ::= "{" [ expression | expression ( "." expression )+ ] "}" (an array with computed elements)

literalObject ::= "#{" ( fieldName: constant )+ "}" (a constant object with getters for fields)

immediateObject ::= "{" ( fieldName: expression )+ "}" (an immediate object with getters and setters)

cString ::= c'string with C-escapes'

eString ::= e'string with C-escapes and {embedded expressions}'

iString ::= i'string with C-escapes and {embedded expressions} which is also internationalized'

typedArrayLiteral ::= #u8(...) "/ unsigned byte array constant
| #s8(...) "/ signed byte array constant
| #u16(...) "/ unsigned int16 array constant
| #s16(...) "/ signed int16 array constant
| #u32(...) "/ unsigned int32 array constant
| #s32(...) "/ signed int32 array constant
| #u64(...) "/ unsigned int64 array constant
| #s64(...) "/ signed int64 array constant
| #f32(...) "/ single precision IEEE float array constant
| #f64(...) "/ double precision IEEE float array constant

cStyleInt ::= 0xXXX
| 0oOOO
| 0bBBB

indexedAccess ::= array-expr "[" index-expr "]"
| array-expr "[" index1-expr "][" index2-expr "]"

indexedStore ::= array-expr "[" index-expr "]" := <expr>
| array-expr "[" index1-expr "][" index2-expr "]" := <expr>

=== JavaScript Language Syntax (BNF) ===

-- incomplete w.r.t. expression syntax -- to be added

;; Notice: an elementary JavaScript action's "execute" function
;; must be a unary function (no argument).
;; 
;; However, it is possible to define additional (private) helper functions.
;; These will only be visible within that single elementary action's code.
;; 
;; Also notice the syntax extensions for character constants and the "return from" statement.
;; 
method ::= functionSpec functionBody

functionSpec ::= ["async"] "function" identifier "(" [argList] ")"

functionBody ::= "{" (statement)+ "}"

statement ::= varDeclaration
| ifStatement
| whileStatement
| doStatement
| forStatement
| tryCatchStatement
| switchStatement
| returnStatement
| "{" (statement)+ "}"
| expression

varDeclaration ::= "var" identifier ( "," identifier)* ";"

ifStatement ::= "if" "(" expression ")" statement
[ "else" statement ]

whileStatement ::= "while" "(" expression ")" statement

doStatement ::= "do" statement "while" "(" expression ")" ";"

forStatement ::= "for" "(" [expression] ";" [expression] ";" [expression] ")" statement

tryCatchStatement ::= "try" statement (catchClause | finallyClause | catchFinallyClause)

catchClause ::= "catch" "(" identifier [identifier] ")" statement

finallyClause ::= "finally" statement

catchFinallyClause ::= catchClause finallyClause

switchStatement ::= "switch" "(" expression ")" "{" ("case constantExpression ":" statement)+ [ "default:" statement+ "}"

returnStatement ::= "return" expression [ "from" identifier ]

expression ::= term ( ("+" | "-") term)*
| "await" expression

term ::= factor ( ("*" | "/" | "%" ) factor)*

factor ::= powExpr ( "**" powExpr)*

powExpr ::= "typeof" "(" expression ")"
| "!" factor
| "-" factor
| "++" factor
| "--" factor
| primary "--"
| primary "++"

primary ::= identifier
| literalConstant
| arrayExpression
| "(" expression ")"
| block
| "this"
| "super"
| "new" classIdentifier [ "(" constant ")" ]
| functionDefinition
| lambdaFunction

functionDefinition ::= "function" [functionName] "(" [argList] ")" functionBody

lambdaFunction ::= "(" [argList] ")" "=>" functionBody
| arg "=>" functionBody
| "(" [argList] ")" "=>" expression
| arg "=>" expression

identifier ::= ( "_" | "a"-"z" | "A"-"Z") ( "_" | "a"-"z" | "A"-"Z" | "0"-"9" )*

literalConstant ::= integerConstant
| radixIntegerConstant
| floatConstant
| arrayConstant
| byteArrayConstant
| stringConstant
| characterConstant
| "true"
| "false"
| "null"

integerConstant ::= ( "0"-"9" )+

radixIntegerConstant ::= hexIntegerConstant | octalIntegerConstant | binaryIntegerConstant

hexIntegerConstant ::= "0x"hexDigit+

hexDigit := "0"-"9" | "A"-"F" | "a"-"f"

octalIntegerConstant ::= "0"octalDigit+

octalDigit := "0"-"7"

binaryIntegerConstant ::= "0b"binaryDigit+

binaryDigit := "0" | "1"

floatConstant ::= [ "-" ] [ digits+ ] "." [ digits+ ] [ ("e" | "E" | "d" | "D") [ "-"] digits+ ]

arrayConstant ::= "[" [literalConstant ("," literalConstant)*] "]"

arrayExpression ::= "[" [expression ("," expression)*] "]"

stringConstant ::= apos character* apos
| quote character* quote

characterConstant ::= "$" character

apos ::= "'"' (single quote)

quote ::= " " " (double quote)

comment ::= "/*" any-character* " */ " | eolComment

eolComment ::= " // " any-character-up-to-end-of-line

Notice the nonstandard extension for single character constants

----
Back to [[ Online_Documentation#Code_API_Overview Online Documentation ]]

[[Category: Advanced/en]]

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]