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

Expecco API/en

2015-02-03T09:55:34Z

Jv: Make Groovy code in section "Defining a New Class in the System Under Test using Groovy" compilable.

== 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 etc.) or inside a Java Virtual Machine (Groovy).

For an 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.

<DIV ID="Smalltalk_Elementary_Blocks"> </DIV>
<DIV ID="JavaScript_Elementary_Blocks"> </DIV>
== JavaScript and Smalltalk Elementary Blocks ==

The 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].

JavaScript and Smalltalk only differ slightly in their syntax; semantically they are very similar:
{| Border
! JavaScript
! Smalltalk
!
|-
| this
| self
| the current activity
|-
| 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
|-
| functionName(...)
| self functionName...
| implicit this/self receiver
|-
| accessor
| self accessor
| slot access - implicit this/self send
|-
| stat1 ; stat2
| stat1 . stat2
| statement terminator / separator (in ST: required to terminate every statement in JS: required to separate)
|-
| if (cond) {   ifStats } else {     elseStats }
| cond ifTrue:[   ifStats ] ifFalse:[   elseStats ]
| conditional execution
|-
| while (cond) {   stats }
| [ cond ] whileTrue:[   stats ]
| while-loop. Notice the extra brackets in Smalltalk
|-
| function () { stats }
| [ stats ]
| an anonymous (inner) function (called "block" in ST)
|-
| function (a1, a2,...) { stats }
| [:a1 :a2 ...| stats ]
| in ST: blocks are a reference to an anonymous function
|-
| var v1, v2, ... ;
| | v1 v2 ... |
| local variables inside a function (or block)
|-
| return expr;
| ^ expr
| return a value. In ST: a return from within a block returns the enclosing top-level function In JS: a return returns from the inner function
|}

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, "a + b * 5" in JavaScript means "a + (b * 5)", whereas in Smalltalk, it is evaluated as "(a + b) * 5". For this, as a guideline (and actually a strict convention), all Smalltalk expression should be parenthesized to make the intention clear, whenever it conflicts with the intuitive (standard mathematical) precedence.

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. Thus for example, the Smalltalk name "at:put:" will be replaced to "at_put" in JavaScript.

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

Also, for non-argument accessor functions (getters), the empty argument list can be omitted in JavaScript; therefore, "foo" and "this.foo", "foo()" and "this.foo()" are all equivalent.

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

and, to demonstrate the multi-argument translation rule,
the Smalltalk code:
 
<CODE><PRE> self environmentAt:'foo' put:1234</PRE></CODE>
is written in JavaScript as:
<CODE><PRE> this.environmentAt_put("foo", 1234)</PRE></CODE>

=== Syntax ===
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.

{| Border
! JavaScript
! Smalltalk
! Notes
|-
| this
| self
| the current activity
|-
| null
| nil
| a null reference (UndefinedObject)
|-
| ;
| .
| Statement Terminator/Separator
|-
| "..."
| '...'
| a String constant (JavaScript allows single quotes too)
|-
|
| #'...'
| a Symbol constant (not available in JavaScript)
|-
| [ el1 , el2 , ... ]
| #( el1 el2 ... )
| an Array constant (elements must be constants)
|-
| [ expr1 , expr2 , ... ]
| { expr1 . expr2 . ... }
| a computed Array (notice the expression terminators in ST)
|-
|
| #[ el1 el2 ... ]
| a ByteArray constant (not available in JavaScript)
|-
|
| ( num / den )
| a Fraction constant (not available in JavaScript)
|-
| rcvr.f ()
| rcvr f
| function call
|-
| rcvr.f (arg)
| rcvr f: arg
| with 1 arg
|-
| rcvr.a_b (arg1, arg2)
| rcvr a: arg1 b: arg2
| with 2 args notice the different names of the function "a_b" vs."a:b:"
|-
| return;
| ^ self
| without return value (in ST: from outer function; in JS: from current function)
|-
| return expr;
| ^ expr
| with return value (in ST: from outer function; in JS: from current function)
|-
| return from execute;
| ^ self
| return outer from 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)
|}

=== Syntactic Sugar ===

Some syntactic constructs of the JavaScript language are implemented as library functions in Smalltalk. Among otherse, most noteworthy are conditional execution (if-the-else) and loops.
 The JavaScript syntax is mapped to corresponding Smalltalk library functions as follows:
{| Border
! JavaScript
! Smalltalk
! Notes
|
|-
|if (expr) { .. }
| (expr) ifTrue:[ ... ]
|
|-
|if (! expr) { .. }
| (expr) ifFalse:[ ... ]
|
|-
| if (expr) { .. } else { ... }
| (expr) ifTrue:[ ... ] ifFalse:[...]
|
|-
| while (expr) { .. }
| [expr] whileTrue:[ ... ]
| Notice the square brackets
|-
| for (expr1;expr2;expr3) { .. }
| expr; [expr2] whileTrue:[ ... expr3 ]
|
|-
| 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
| Array and Dictionary indexed read Notice that in expecco, JavaScript uses 1-based indexing
|-
| arr[ idx ] = expr
| arr at: idx put: expr
| Array and Dictionary indexed write
|}

=== Operators ===
{| Border
! JavaScript
! Smalltalk
! Notes
|-
| %
| \
| modulu operator
|-
| <<
| bitShift:
| left-shift; negative shift count is right-shift
|-
| >>
| rightShift:
| right-shift; negative shift count is left-shift
|}

=== 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:
<CODE><PRE>
execute() {
...
function f(arg1, arg2) {
return(arg1 + arg2);
}
...
}
</PRE></CODE>
A inner function f is created with two arguments (arg1, arg2), which returns the sum of both. The function is called like this:
<CODE><PRE>
f(3,5)
</PRE></CODE>
Inner functions can be used for example to filter specific elements from collections.

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:
<CODE><PRE>
execute() {
var f;
...
f = function (arg1, arg2) {
return(arg1 + arg2);
}
...
}
</PRE></CODE>
(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:
<CODE><PRE>
execute
...
function myFunction() {
...
return from execute;
}
...
</PRE></CODE>
(notice that the execute function is not supposed to return a value)

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

In Smalltalk, inner functions are called "block", and are defined as:
<CODE><PRE>
f := [:arg1 :arg2 | arg1 + arg2 ].
</PRE></CODE>
This block can be called by sending at a "value:value:" message (one "value:" for each argument):
<CODE><PRE>
f value:3 value:5
</PRE></CODE>
Blocks without argument are defined as:
<CODE><PRE>
f := [ Transcript showCR:'blabla: Euler was great' ].
</PRE></CODE>
and invoked with a simple "value" message.

Smalltalk blocks and JavaScript inner functions can be used interchangable - i.e. it is possible to pass a JS inner function to a collection method such as "collect:" or "select:". 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.

==== 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 select (where(x => ...)) is written in Smalltalk as:
<CODE><PRE>
|names namesStartingWithA|

names := #( 'Alice' 'Ann' 'Bob' 'Mallory' ).
namesStartingWithA := names select:[:n | n startsWith:'A'].
</PRE></CODE>
or in JavaSript as:
<CODE><PRE>
var names, namesStartingWithA;

names = [ "Alice" , "Ann" , "Bob" , "Mallory" ];
namesStartingWithA = names.select( function(n) { n.startsWith("A"); } );
</PRE></CODE>

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

names := #( 'Alice' 'Ann' 'Bob' 'Mallory' ).
firstNameContainingAnO:= names detect:[:n | n includesString:'o'].
</PRE></CODE>
or in JavaSript as:
<CODE><PRE>
var names, firstNameContainingAnO;

names = [ "Alice" , "Ann" , "Bob" , "Mallory" ];
firstNameContainingAnO = names.detect( function(n) { n.includesString("o"); } );
</PRE></CODE>
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 introductionary 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 represenations. 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, if there was a remainder.
Although very very rarely required in practice,
values can be converted explicitly, via one of the "asXXX" messages, if required:
* asFloat()
* asInteger()
* asFraction()
* asFixedPoint(scale)

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

===== Integer =====

This represents arbitrary precision integral numbers. Conversion and memory allocation is completely automatic. Thus, you can write:
x = 100.factorial();
to get the huge number:
933262154439441526816992388562667004907159682643816214685929638952175999932299156089
41463976156518286253697920827223758251185210916864000000000000000000000000

Small integer values (<32bit or <64bit, depending in the underlying hardware's native wordlength) are stored more efficiently than large integers - however, the conversion and representation as used by the system is completely 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 "add_32:", "add_32u", "mul_32" etc. Use a 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 (only in Smalltalk: 2rxxx).

[[http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#INTEGER More Info]]
[[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.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#FLOAT More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Float Class Documentation]]

===== Fraction =====

Fractions are arbitrary-precision rational numbers. You will get them when dividing two integers and the result is not integral. For example:
1 / 3
returns a fraction result with a numerator of 1 and a denominator of 3 (as opposed to the // 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.

Fractions automatically reduce themself - therefore, when adding ''(1/3) + (2/6)'', you will get ''(2/3)''.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#FRACTION More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Fraction Class Documentation]]

===== FixedPoint=====

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. However, when printed, they round in their last digit (however, the exact information is always kept for further processing). FixedPoint numbers are perfect to represent money and other fractional data, which must be represented with a fixed number of post-decimal digits.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#FIXEDPOINT More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,FixedPoint Class Documentation]]

===== Number =====

The Number type is an abstract union type which includes all of the above types. Thus, a variable declared as being of "Number" 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.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/numeric.html#NUMBER More Info]]

==== String Types ====

Strings can come in two flavours, depending on how many bits are required to encode the character's codePoint. In general, UNICODE is used internally as the encoding. However, converters are available to translate into other encodings, such as JIS or ISO8859-x.

===== 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 can be accessed by an integral index starting with 1 in both Smalltalk and JavaScript.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#STRING More Info]]
[[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 value is in the range 0x0100 .. 0xFFFF. In fact, there is even a Unicode32String class, which supports the full four-byte unicode character set. But in practice, 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).
 [[http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#CHARACTER More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Character Class Documentation]]

==== Collection Types ====

An introductionary overview on the collection classes is found in the
 [[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]].

===== 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. 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 is constant O(1). Searching for an element in an Array (using the ''includes:'' or ''indexOf:'' method), time complexity is O(N), because the search is linear through all elements of the array.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#ARRAY More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Array Class Documentation]]

===== ByteArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
Can only store very small byte-valued unsigned integers (0..255), and allocates 1 byte per element.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#BYTEARRAY More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,ByteArray Class Documentation]]

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

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

===== FloatArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
Can only store short IEEE floats (32bit) and allocates 4 bytes per element
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#FLOATARRAY More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,FloatArray Class Documentation]]

===== DoubleArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
Can only store IEEE doubles (64bit) and allocates 8 bytes per element.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#FLOATARRAY More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,DoubleArray Class Documentation]]

===== HalfFloatArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
Can only store IEEE half floats (16bit) and allocates 2 bytes per element.
 Notice that half floats have a very low precision and are seldom used (exceptions are game programs or 3D graphics accelerators, to preserve memory by using this very compact format for depth information)

===== IntegerArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
Can only store small 32bit unsigned integer values (0..FFFFFFFF) and allocates 4 bytes per element.
 [[http://live.exept.de/ClassDoc/classDocOf:,IntegerArray Class Documentation]]

===== SignedIntegerArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
Can only store small 32bit signed integer values (-800000000..7FFFFFFF), allocating 4 bytes per element.
 [[http://live.exept.de/ClassDoc/classDocOf:,SignedIntegerArray Class Documentation]]

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

===== SignedLongIntegerArray =====
Ordered, fixed size, indexed by an integral index starting with 1.
Can only store small 64bit signed integer values (-80000000000000000..7FFFFFFFFFFFFFFF), allocating 8 bytes per element.
 [[http://live.exept.de/ClassDoc/classDocOf:,SignedLongIntegerArray Class Documentation]]

===== OrderedCollection =====
Ordered, variable size, indexed by an integral index starting with 1.
Can store any type of object. OrderedCollections are specifically tuned for adding/removing elements
at either end. Access time to elements via index has a complexity of O(1).
When searching for an element in an OrderedCollection (using the ''includes'': or ''indexOf:'' method), time complexity is O(n), because a linear search is done.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#ORDCOLL More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,OrderedCollection Class Documentation]]

===== SortedCollection =====
Sorts itself, variable size, indexed by an integral index starting with 1.
Can store any type of object. By default, sorting is by ascending order. 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 "[:a :b | a < b]").
Access by numeric index is O(1). Insertion and remove is O(1) for the first and last element, O(n) for others, because the elements are moved inside a linear container. When searching for an element in a SortedCollection (using the ''includes:'' or ''indexOf:'' method), time complexity is O(log n), because a binary search can be done. 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 asSortedCollection(), instead of adding individual elements one-by-one.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#SORTCOLL More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,SortedCollection Class Documentation]]

===== Set =====
Unordered, variable size, keeps a single reference only, per equal element.
Can store any type of object. When searching for an element in a Set (using the ''includes:'' method), time complexity approaches O(1), because the search can be done based on a hashing algorithm in asymptotic constant time.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#SET More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Set Class Documentation]]

===== Bag =====
Unordered, variable size, keeps a count, per equal element. Adding, removing and insertion check are all asymptotical O(1).
Can store any type of object.
 [[http://live.exept.de/ClassDoc/classDocOf:,Bag Class Documentation]]

===== Dictionary =====
Unordered, variable size, implements arbitrary key-value mappings.
Can store any type of object.
When accessing or searching an element in a Dictionary (using the ''at:'' or ''includesKey:'' method), time complexity asymptotically approaches O(1), because the key search can be done based on a hashing algorithm. Notice, that the same value may be stored multiple times in a dictionary (i.e. stored under multiple keys); therefore, asking for the presence of a particular '''value''' in the dictionary (the reverse query) still has O(N) time complexity.

If you need 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".
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#DICTIONARY More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Dictionary Class Documentation]]

===== OrderedDictionary =====
Ordered, variable size, implements arbitrary key-value mappings.
Can store any type of object.
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). Creation of an OrderedDictionary is somewhat slower than for Dictionary or OrderedCollection, but access by either numeric or hashkey is fast O(1).
 [[http://live.exept.de/ClassDoc/classDocOf:,OrderedDictionary Class Documentation]]

===== 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.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/collections.html#QUEUE More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Queue Class Documentation]]

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

===== BTree, AATree, BinaryTree =====
Combining the functionality of Dictionaries and SortedCollection, these keep their elements in a sorted order, indexed by a key-object.
In contrast to Dictionaries, which use hashing, these use a tree-like representation and guarantee both asymptotic O(log N) worstcase and average runtime. (Dictionaries have a much better average runtime of O(C), but also a worstcase 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. [[http://live.exept.de/ClassDoc/classDocOf:,BinaryTree 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, read streams deliver the next element via a "''next''()" operation, write streams 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 introductionary 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 or linewise access to any stream of the underlying operating system. Concrete subclasses are Socket, Filestream, Console Streams, PTYStream etc.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/streams.html#FILESTREAM More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,ExternalStream Class Documentation]]

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

===== CharacterWriteStream =====
A special stream usable for mixed single- and multibyte characters (i.e. Unicode).
 [[http://live.exept.de/ClassDoc/classDocOf:,CharacterWriteStream Class Documentation]]

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

There are a number of useful companion classes which deal with host addresses:
 [[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]].

==== Other useful Types ====

===== Date =====
Represents a calendar date.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#DATE More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Date Class Documentation]]

===== Time =====
Represents a time-of-day in second resolution.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#TIME More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Time Class Documentation]]

===== Timestamp (Date and Time) =====
Represents a timestamp in millisecond resolution. Due to the internal representation (Unix format), only timestamps back to 1.1.1970 can be represented.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#TIMESTAMP More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,Timestamp Class Documentation]]

===== TimeDuration =====
Represents an amount of time, to represent time intervals in millisecond resolution. When reading, a unit-specifier character is allowed to specify milliseconds (ms), seconds (s), minutes (m), hours (h) or days (d). For example, "1h 20s" specifies 1 hour and 20 seconds.
 [[http://live.exept.de/doc/online/english/overview/basicClasses/misc.html#TIMEDURATION More Info]]
[[http://live.exept.de/ClassDoc/classDocOf:,TimeDuration Class Documentation]]

===== Delay =====
Utility providing delay functions. Most useful are (in Smalltalk) <code>"Delay waitForSeconds: n"</code> and <code>"Delay waitUntil: timestamp"</code>,
or (in JavaScript) <code>"Delay.waitForSeconds(n)"</code> and <code>"Delay.waitUntil(timestamp)"</code>.
[[http://live.exept.de/ClassDoc/classDocOf:,Delay 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.
 [[http://live.exept.de/ClassDoc/classDocOf:,Filename Class Documentation]]

=== Standard Objects for JavaScript ===

In order for a "well known" environment to be provided to those who know JS, 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.
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). Same as "<code>Float e</code>" in Smalltalk.

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

*'''LN2''' Natural logarithm of 2 (approximately 0.693). Same as "Float ln2" in Smalltalk.

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

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

*'''PI''' Pi (approximately 3.14159). Same as "Float pi" in Smalltalk.

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

*'''SQRT2''' Square root of 2 (approximately 1.414). Same as "Float sqrt2" in Smalltalk.

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

*'''max''' (''number1 , number2,...'') Returns the largest of 0 to 5 arguments

*'''min''' (''number1, number2,...'') Returns the smallest of 0 to 5 arguments

===== Miscellaneous =====

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

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

*'''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

===== Trigonometric =====

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

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

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

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

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

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

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

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

*'''MAX_VALUE''' The largest representable number. The returned number is 0x7FFFFFFFFFFFFFFF, to mimicri a 64 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 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 =====

*'''asFloat''' () Returns a floating-point version of the receiver object. For example: "1.asFloat()" yields the floating point number: "1.0".

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

*'''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: "1.4.ceiling()" yields the integer number: "2", whereas "1.ceiling()" returns "1". See also: floor() and rounded().

*'''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: "1.4.floor()" yields the integer number: "1", whereas "1.floor()" returns "1". See also: ceiling() and rounded().

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

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

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

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

*'''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 (/dev/rand). In addition, alternative generators are available as "RandomParkMiller" and "RandomTT800". For most applications, the default generator named Random should provide a reasonable random sequence.

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

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

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

*'''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:

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

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

*'''getFullYear''' Returns the year

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

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

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

==== 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) to be used with strings. Use the browser or take a look at the online documentation for the full protocol.

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

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

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

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

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

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

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

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

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

*'''split''' (''separator'') Splits the string into a collection of substrings using the separator

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

*'''pop''' Removes and returns the last element of the collection

*'''push''' (''value'') Adds an element to the end of the collection

*'''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.

*'''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.

*'''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.

*'''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.

*'''shift''' Removes and returns the first element of the collection

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

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

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

*'''unshift''' (''arg'') Adds an element to the beginning of the collection
 

==== Transcript ====

The global variable "Transcript" 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:

*'''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.

and from the inherited write stream interface:

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

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

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

 

=== 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 aquired 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 "''this''" (Smalltalk: "''self''"). 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). Stops execution.

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

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

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

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

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

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

*'''activitySuccess''' () Finishes the current activity with success. Actually not needed, because simply returning from an action's execute method is semantically equivalent.

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

*'''pass''' () Finishes the current testCase with success. Notice: this aborts the current activity and all of the callers up to the test case level.

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

===== 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'') (1.8.1) Adds an 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'') (1.8.1) Same as ''alert()'' (for Smalltalk 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...)

 

===== 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)

*'''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 above environment)

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

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

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

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

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

*'''resources''' () All resources which have been aquired 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 aquired 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 aquired.

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

===== 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 choosen as target of such operations:

* '''environment''' () the environment of the compound in which the current elementary action is executing (as a step)

* '''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 present while the expecco application is running (i.e. the current session). (it is not made persistent)

None of the following can be made persistent directly. However, every test suite, test plan and compound block provide a description of initial values and how to compute them in their environment description, which is edited using the [[ Environment Editor ]].
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.

 

==== Executor Functions ====

*'''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 ====

*'''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 ====

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

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

*'''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.

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

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

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

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

*'''elementWithFunctionalId''' (''aUUID'') Retrieve an element by its version id

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

 

==== Testplan Functions ====

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

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

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

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

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

==== Step Functions ====

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

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

==== Pin Functions ====

The input and output pins can be referenced in elementary code 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), which is a new feature in v2.1, the collection of pins is referred to by the name, and pins are accessed via an index (1..). See more about how to handle variable pins in the section below.

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

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

*'''hasValue''' () Returns true if the pin has received a value (important for the trigger conditions ANDConnected and OR)

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

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

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

*'''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.

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

*'''waitForValue''' () The pin has to be a mailbox pin. The execution will be interrupted until the pin receives a value.

*'''waitForValueWithTimeout''' (''seconds'') 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 (1/3) or a floating-point number (0.3).

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

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

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

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

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

Starting with expecco v2.0, steps can have a variable number of input pins (after placement of the step, pull the pin-handle, 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 regular pins, where pinName refers to a single pin.

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

*'''pinName.at''' (''idx'') returns the i'th actual pin of the schema pin named "pinName". Notice this retrieves the pin; to get to the value or query if t has a value, call ''value''() / ''hasValue''() on the returned pin.

*'''pinName.hasValueAt''' (''idx'') true if the i'th variable pin is connected and has received a value

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

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

*'''pinName.valueAt''' (''idx'') to get the i'th pin's value; raises an error if no value was given or pin is not connected

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

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

Starting with expecco v2.1, steps can have a variable number of output pins too (after placement of the step, pull the pin-handle, 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.numberOfVariablePins''' () returns the number of actual pins present in the step for the (variable) schema pin named "pinName".

*'''pinName.at''' (''idx'') returns the i'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.

*'''pinName.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.
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.

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

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

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

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

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

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

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

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

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

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

==== Enum Type Functions ====

*'''values''' () returns an array of enum-value names (Symbolic)

*'''integerValueOf''' (''elementName'') returns the associated integer value. (new in expecco 2.8)

==== Compound Type Functions ====

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

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

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

==== Primary Type Functions ====

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

==== Range Type Functions ====

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

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

*'''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.

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

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

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

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

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

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

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

*'''isBlockdescription''' true, if it is a block description (in the tree)

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

*'''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'''.

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

*'''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.codehaus.org "Groovy: A dynamic language for the Java platform"] and especially the [http://groovy.codehaus.org/Documentation 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 system under test (SUT). By using Groovy blocks, expecco's basic black-box test functionality can be easiliy extended by many 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 interacts back to expecco.

The machinery to interact with a JVM (and therefore to execute Groovy code blocks) requires the JavaBridge plugin, which is not part of the basic expecco package. Groovy itself is avalable for free as a jar class library, which is loaded with or into the target application. The JavaBridge 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 JavaBridge 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 must be special derived classes, are hard to realize without Groovy.

=== 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 anonymus 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 JWM 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).

=== 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 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 "groovy", and it is connected, that pin's value is used as Groovy shell handle
* otherwise, if the environment contains a variable named "GROOVY", that variable's value is used
* otherwise, a Groovy shell is instantiated and used, on the JVM which is given by:
** if the action has a pin named "java", and it is connected, that pin's value is used as java-bridge handle
** otherwise, if the environment contains a variable named "JAVA", that variable's value is used
** finally, otherwise a local JVM connection is used (a shared singleton connection).

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.

=== Calling Existing Code in the System Under Test via a Groovy Action===

A Groovy block's code looks very similar to a regular JavaScript block's code. However, it is executed on the SUT, and can therefore instantiate Java objects and call static and member functions.

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

<CODE><PRE>
def execute() {
MyTestClass.foo("hello world");
}
</PRE></CODE>

if the class is located in another package (or especially: in one of your own),
use explicit package prefixes:
<CODE><PRE>
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);
}
</PRE></CODE>
or an import declaration:

<CODE><PRE>
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);
}
</PRE></CODE>
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 ===
You can define your own classes in a Groovy block:
<CODE><PRE>
class MyClass extends Object {
Object someState;

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

// end of local definitions

def execute() {
outputPin.value( new MyClass() );
}
</PRE></CODE>
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).

=== 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:
<CODE><PRE>
// 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
}
</PRE></CODE>

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 #getNextEvent():

<CODE><PRE>
// a JavaScript Elementary Block

execute() {
var theListener;
var event;

theListener = inPin.value();
event = theListener.getNextEvent();
outpin.value ( event );
}
</PRE></CODE>
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 realevent object (remember: the event object is an object inside the remote Java machine). However, 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();.

=== 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 ====
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
| Float
|-
| Fraction
| float, double (danger alert: precision may be lost)
| Float
|-
| Boolean
| Boolean
| Boolean
|-
| Array of any above
| ArrayList of any above
| Array of any above
|-
| arbitrary Smalltalk Object (!)
| opaque reference to alien object (!)
| original Smalltalk Object (identity preserving) (!)
|-
|
| arbitrary Java Object -> opaque reference to alien Java Object
| original Java Object (identity preserving)
|}

(!) 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 Smallalk Classes, No Smalltalk Objects ====
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 "eval()" and "perform()" 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 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. This is possible via the Smalltalk "doesNotUnderstand:" mechanism, which intercepts any call, sends a message to the real object (via the JavaBridge), 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 the performance penalty, due to the interprocess communication and marshalling overhead).

==== 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.

==== 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 ====

Unless explicitely prevented by the "mayStillDoExpeccoCalls()" function ([[#Special_Functions |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 "execute()" 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 JavaVM,
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, def default action after Groovy action execution is to release the observer.

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.

If any of them is called after the step has finished, they will be ignored and behave like a no-operation, unless the observer is still around.
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.

==== Current Activity (Groovy) ====
The current activity instance is accessed as "''this''" (like in an elementary JavaScript block). 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). 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.

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

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

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

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

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

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

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

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

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

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

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

==== 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 an 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 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 (Groovy) ====

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

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

==== Special Functions ====

*'''mayStillDoExpeccoCalls''' (''boolean'') Make sure that the functions described here will still be callable (by Java callback functions from other threads) even after the step has finished execution. In other words, do NOT release 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.
 

==== 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 ===

The expecco "Transcript", "Stderr" and "Stdout" are also accessable 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.
 

== VisualBasic Script 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 MSWindows 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 easiliy 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 | VisualBasic plugin documentation]] for more detail.

== Examples ==

=== 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)
<CODE><PRE>
execute() {
var inValue;

inValue = in.value; // Reading input pin value
out.value( inValue.sqrt() ); // Writing to output pin
}
</PRE></CODE>
alternative:
<CODE><PRE>
execute() {
var inValue;

inValue = in.value; // Reading input pin value
out.value( Math.sqrt(inValue) ); // Writing to output pin
}
</PRE></CODE>

===== Smalltalk =====
(runs inside expecco, when executed)
<CODE><PRE>
execute
|inValue|

inValue := in value. "/ Reading input pin value
out value: inValue sqrt. "/ Writing to output pin
</PRE></CODE>

===== Groovy=====
(runs inside the JVM, which may be the system under test or another machine running Java)
<CODE><PRE>
def execute {
Object inValue;

inValue = inPin.value(); // Reading input pin value
outPin.value(Math.sqrt(inValue)); // Writing to output pin
}
</PRE></CODE>
(Notice: "in" is a reserved keyword in Groovy and cannot be used as pin name)

=== Random-Fail Block ===

A block, which randomly fails (to demonstrate exception handling), could be implemented like:

===== JavaScript =====
<CODE><PRE>
execute() {
var dice;

dice = Random.nextIntegerBetween_and_(1,6);
if (dice <= 2) {
fail();
}
}
</PRE></CODE>

===== Smalltalk =====
<CODE><PRE>
execute
|dice|

dice := Random nextIntegerBetween:1 and:6.
(dice <= 2) ifTrue:[
self fail.
].
</PRE></CODE>

===== Groovy =====

<CODE><PRE>
execute() {
Random rand = new Random();
int dice = rand.nextInt(5)+1;

if (dice <= 2) {
fail();
}
}
</PRE></CODE>

=== 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].

Here are 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 =====
<CODE><PRE>
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);
}
</PRE></CODE>

===== Smalltalk =====
<CODE><PRE>
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.
</PRE></CODE>

=== Sending Messages to the Transcript ===

===== JavaScript =====
<CODE><PRE>
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();
}
}
</PRE></CODE>

===== Smalltalk =====
<CODE><PRE>
execute
Transcript showCR:'---------------------'.
1 to:10 do:[:y |
1 to:10 do:[:x |
Transcript show:(x * y); show:' '.
].
Transcript cr.
].
</PRE></CODE>

===== 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 Transcript 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.

<CODE><PRE>
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();
}
}
</PRE></CODE>

=== Reading/Writing Pin Values ===

Assuming that the block has two pins, named "in1" and "in2" and two output pins, named "out1" and "out2",
the following blocks write concatenated strings to both outputs:

===== JavaScript =====
<CODE><PRE>
execute() {
out1.value( in1.value() + in2.value() );
out2.value( in2.value() + in1.value() );
}
</PRE></CODE>

===== Smalltalk =====
<CODE><PRE>
execute
out1 value:(in1 value , in2 value).
out2 value:(in2 value , in1 value).

</PRE></CODE>

===== Groovy =====
<CODE><PRE>
def execute() {
out1.value( in1.value() + in2.value() );
out2.value( in2.value() + in1.value() );
}
</PRE></CODE>

=== 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 =====
<CODE><PRE>
execute() {
if ( environmentAt("IncDec") == "inc" ) {
environmentAt_put("Counter", environmentAt("Counter") + 1);
} else {
environmentAt_put("Counter", environmentAt("Counter") - 1);
}
}
</PRE></CODE>

===== Smalltalk =====
<CODE><PRE>
execute
(self environmentAt:'IncDec') = 'inc' ) ifTrue:[
self environmentAt:'Counter' put:(self environmentAt:'Counter') + 1).
] ifFalse:[
self environmentAt:'Counter' put:(self environmentAt:'Counter') - 1).
]
</PRE></CODE>

===== Groovy =====
<CODE><PRE>
def execute() {
if ( environmentAt("IncDec") == "inc" ) {
environmentAt_put("Counter", environmentAt("Counter") + 1);
} else {
environmentAt_put("Counter", environmentAt("Counter") - 1);
}
}
</PRE></CODE>

=== 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 =====
<CODE><PRE>
execute() {
var answer;

answer = Dialog.requestDirectory("Please select an output folder:");
if ( answer.notEmptyOrNil() ) {
out.value( answer );
}
}
</PRE></CODE>

===== Smalltalk =====
<CODE><PRE>
execute
|answer|

answer := Dialog requestDirectory: 'Please select an output folder:'.
answer notEmptyOrNil ifTrue:[
out value: answer
]
</PRE></CODE>

=== 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 =====
<CODE><PRE>
execute
|answer|

Smalltalk loadPackage:'myPackage'. "/ checks if already loaded, to only load the first time called
MyApplication open.
</PRE></CODE>

For this, download the free [http://www.smalltalk-x.de Smalltalk/X development IDE ].

== Appendix ==

=== Smalltalk Language Syntax (BNF) ===

See also: [http://rosettacode.org/wiki/Category:Smalltalk Smalltalk Short Description ], [http://live.exept.de/doc/online/english/getstart/tut_2.html Smalltalk Basics]

<code><pre>
;; notice: an elementary Smalltalk Block's execute method is a unary method (no argument).

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 ( keywordSymbol binaryExpression )+

binaryExpression ::= unaryExpression
| unaryExpression ( binopSymbol unaryExpression )+

unaryExpression ::= primary
| primary ( unarySymbol )+

primary ::= identifier
| literalConstant
| 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 (2-31)

baseDigits := "0"-"9" | "A"-"Z" | "a"-"z"

floatConstant ::= [ "-" ] [ digits+ ] "." [ digits+ ] [ ("e" | "E" | "d" | "D") [ "-"] digits+ ]

arrayConstant ::= "#(" literalConstant* ")"

byteArrayConstant ::= "#[" integerConstant(0..255)* "]"

stringConstant ::= " ' " character* " ' "

characterConstant ::= "$" character

braceArray ::= "{" [ expression | expression ( "." expression )+ ] "}"

block ::= "[" [ blockArgList ] body "]”

blockArgList ::= (identifier":" )*

comment ::= " " " any-character* " " " | eolComment

eolComment ::= " "/ " any-character-up-to-end-of-line

symbol ::= identifier

binopSymbol ::= ( "+" | "-" | "*" | "/" | "\" | "," | "@" | "%" | "&" | "=" | "<" | ">" | "~" )+

keywordSymbol ::= identifier":"
</pre></code>

=== JavaScript Language Syntax (BNF) ===

-- incomplete w.r.t. expression syntax -- to be added
<CODE><PRE>
;; notice: an elementary JavaScript Block's execute function must be a unary function (no argument).

method ::= functionSpec functionBody

functionSpec ::= 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)*

term ::= factor ( ("*" | "/" | "%" ) factor)*

factor ::= "typeof" "(" expression ")"
| "!" factor
| "-" factor
| "++" factor
| "--" factor
| primary "--"
| primary "++"

primary ::= identifier
| literalConstant
| "(" expression ")"
| block
| "this"
| "super"
| "new" classIdentifier [ "(" constant ")" ]
| functionDefinition

functionDefinition ::= "function" [functionName] "(" [argList] ")" functionBody

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)*] "]"

stringConstant ::= " ' " character* " ' " | " " " character* " " "

characterConstant ::= "$" character

comment ::= "/*" any-character* " */ " | eolComment

eolComment ::= " // " any-character-up-to-end-of-line
</PRE></CODE>
<hr>
Back to [[ Online_Documentation#Code_API_Overview Online Documentation ]]

Java Debugger/en

2014-11-07T14:19:46Z

Jv:

== Introduction ==

The ''Java Debugger plugin'' provides basic Java debugging facility. It allows for debugging of Groovy blocks and any other Java code run in remote JVM directly within expecco.

The plugin provides a way to place [[#Breakpoints|breakpoints]] into a Java or Groovy code. When breakpoint hits (particular location in the code is reached), the program is stopped and [[#Debugger|a visual debugger]] appear. The debugger then can be used to inspect the state of the execution and/or single-step through the code.

== Debugger ==
[[Datei:expecco_JDebugger_001.png|right|thumb|JDebugger plugin: debugger window]]

The overall layout of Java debugger window is similar to debuggers for Smalltalk and JavaScript blocks. It consists of 5 panes:

1 ''Execution Stack'' - organized top-to-bottom, i.e., the currently executing method is the first entry in the list.

2 ''Source Code View'' - shows the source code of the currently selected method (in execution stack pane). Source for particular method may or may not be available. For details refer to section [[Managing Sources]]

3 ''this object inspector'' - an embedded inspector of '''this''' objects, i.e., on the receiver of the method.

4 ''Method parameters and locals inspector'' - an embedded inspector showing all method parameters and local variables which are visible at current scope.

5 ''Thread List'' - list showing all threads in the remote JVM. The ''Execution Stack'' pane shows execution stack of selected thread.

Following debugging operations are available:

* ''Continue'' - resumes execution until remote JVM terminates or another breakpoint is reached.
* ''Abort'' - aborts execution of currently executing expecco Groovy block. If the selected thread does not execute a Groovy block abortion
is not allowed.
* ''Next'' - aka ''Step-over''. Single-step to next line in currently selected method. Does not enter into called methods.
* ''Next'' - aka ''Step-into''. Single-step to next line in currently selected method or into a called method.
* ''Out'' - aka ''Step-out''. Run until currently selected method returns and stop's at the method's caller.

== Breakpoints ==

''Java Debugger'' plugin supports two kinds of breakpoints:

# ''Line Breakpoints'' - a traditional breakpoint set on particular line in particular method.
# ''Exception Breakpoints'' - a breakpoint that suspends execution when an exception of specified type is thrown.

=== Line Breakpoints ===

A line breakpoint could be placed to a [[ElementaryBlock_Element/en#Groovy_Blocks|Groovy block]] or to any other Java code. When a line breakpoint is hit whole JVM is suspended, i.e., all running Java threads are suspended.

To put a breakpoint in a Groovy block, just click in Groovy block editor left to the line number. The line breakpoint is indicated by a little red circle icon. To remove a breakpoint, just click on the breakpoint icon again.

To put a breakpoint in any other Java code, open a Java browser window, navigate
to desired class and method and click left the line number.

=== Exception Breakpoints ===

An exception breakpoint hits when an exception of given type (or it's subtype) is thrown, i.e., at the point just before Java '''throw''' statement is executed. This is useful when an exception is thrown and possibly caught and re-thrown again to find out the original cause and debug there.

Exception breakpoints could be configured to trigger in two cases:

* For ''caught exceptions'' - the breakpoint will hit (program will be suspended) if an exception is thrown and would be caught by some handler deeper in the execution stack. Note, that any '''finally''' or '''synchronized''' block creates
an implicit exception handler for type [http://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html java.lang.Throwable].

* For ''uncaught exception'' - the breakpoin will hit only if an exception is thrown but it is not handled by any handler, i.e., it is unhandled.

'''Warning''': The JVM cannot always reliably tell whether a given exception is actually caught or uncaught. For details, refer to [http://docs.oracle.com/javase/7/docs/jdk/api/jpda/jdi/com/sun/jdi/event/ExceptionEvent.html#catchLocation() JDI documentation]

== Object Inspector ==

[[Datei:expecco_JDebugger_002.png|right|thumb|JDebugger plugin: Java object inspector]]

TBW...

== Managing Sources ==

''Java Debugger plugin'' uses [[Java Browser/en]] fro accessing
source code. The source code for particular class / method is looked
up in Java Browser's ''default workspace''. This means that if the default workspace does not contain a source code for the class, Java debugger will not show source code. However, it is still possible to
inspect parameters and other local variables and even single-step.

If the sources does not match the sources which the Java code
has been compiled from, Java debugger may show invalid source code
or line numbers may not match. There is no way to validate the sources
matches the code loaded in remote JVM.

For more information about default workspace and how to add classes and
sources to it, please refer [[Java Browser/en|Java Browser plugin documentation]]

== Limitations ==

The current version of JDebugger has some limitations:

* A line breakpoint cannot be placed to a nested classes, i.e., to inner classes and to anonymous classes. Note, that UI event handlers, such as button click handlers, are usually implemented using anonymous classes.
* A breakpoint cannot be placed on a class which is loaded more than once in remote JVM.

These limitations will be addressed in a future versions.

Java Debugger/en

2014-10-09T11:03:20Z

Jv: /* Breakpoints */

== Introduction ==

The ''Java Debugger plugin'' provides basic Java debugging facility. It allows for debugging of Groovy blocks and any other Java code run in remote JVM directly within expecco.

The plugin provides a way to place [[#Breakpoints|breakpoints]] into a Java or Groovy code. When breakpoint hits (particular location in the code is reached), the program is stopped and [[#Debugger|a visual debugger]] appear. The debugger then can be used to inspect the state of the execution and/or single-step through the code.

== Debugger ==
[[Datei:expecco_JDebugger_001.png|right|thumb|JDebugger plugin: debugger window]]

The overall layout of Java debugger window is similar to debuggers for Smalltalk and JavaScript blocks. It consists of 5 panes:

1 ''Execution Stack'' - organized top-to-bottom, i.e., the currently executing method is the first entry in the list.

2 ''Source Code View'' - shows the source code of the currently selected method (in execution stack pane). Source for particular method may or may not be available. For details refer to section [[Managing Sources]]

3 ''this object inspector'' - an embedded inspector of '''this''' objects, i.e., on the receiver of the method.

4 ''Method parameters and locals inspector'' - an embedded inspector showing all method parameters and local variables which are visible at current scope.

5 ''Thread List'' - list showing all threads in the remote JVM. The ''Execution Stack'' pane shows execution stack of selected thread.

Following debugging operations are available:

* ''Continue'' - resumes execution until remote JVM terminates or another breakpoint is reached.
* ''Abort'' - aborts execution of currently executing expecco Groovy block. If the selected thread does not execute a Groovy block abortion
is not allowed.
* ''Next'' - aka ''Step-over''. Single-step to next line in currently selected method. Does not enter into called methods.
* ''Next'' - aka ''Step-into''. Single-step to next line in currently selected method or into a called method.
* ''Out'' - aka ''Step-out''. Run until currently selected method returns and stop's at the method's caller.

== Breakpoints ==

''Java Debugger'' plugin supports two kinds of breakpoints:

# ''Line Breakpoints'' - a traditional breakpoint set on particular line in particular method.
# ''Exception Breakpoints'' - a breakpoint that suspends execution when an exception of specified type is thrown.

=== Line Breakpoints ===

A line breakpoint could be placed to a [[ElementaryBlock_Element/en#Groovy_Blocks|Groovy block]] or to any other Java code. When a line breakpoint is hit whole JVM is suspended, i.e., all running Java threads are suspended.

To put a breakpoint in a Groovy block, just click in Groovy block editor left to the line number. The line breakpoint is indicated by a little red circle icon. To remove a breakpoint, just click on the breakpoint icon again.

To put a breakpoint in any other Java code, open a Java browser window, navigate
to desired class and method and click left the line number.

=== Exception Breakpoints ===

An exception breakpoint hits when an exception of given type (or it's subtype) is thrown, i.e., at the point just before Java '''throw''' statement is executed. This is useful when an exception is thrown and possibly caught and re-thrown again to find out the original cause and debug there.

Exception breakpoints could be configured to trigger in two cases:

* For ''caught exceptions'' - the breakpoint will hit (program will be suspended) if an exception is thrown and would be caught by some handler deeper in the execution stack. Note, that any '''finally''' or '''synchronized''' block creates
an implicit exception handler for type [http://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html java.lang.Throwable].

* For ''uncaught exception'' - the breakpoin will hit only if an exception is thrown but it is not handled by any handler, i.e., it is unhandled.

'''Warning''': The JVM cannot always reliably tell whether a given exception is actually caught or uncaught. For details, refer to [http://docs.oracle.com/javase/7/docs/jdk/api/jpda/jdi/com/sun/jdi/event/ExceptionEvent.html#catchLocation() JDI documentation]

== Object Inspector ==

[[Datei:expecco_JDebugger_002.png|right|thumb|JDebugger plugin: Java object inspector]]

== Managing Sources ==

''Java Debugger plugin'' uses [[Java Browser/en]] fro accessing
source code. The source code for particular class / method is looked
up in Java Browser's ''default workspace''. This means that if the default workspace does not contain a source code for the class, Java debugger will not show source code. However, it is still possible to
inspect parameters and other local variables and even single-step.

If the sources does not match the sources which the Java code
has been compiled from, Java debugger may show invalid source code
or line numbers may not match. There is no way to validate the sources
matches the code loaded in remote JVM.

For more information about default workspace and how to add classes and
sources to it, please refer [[Java Browser/en|Java Browser plugin documentation]]

Datei:Expecco JDebugger 002.png

2014-10-08T15:04:03Z

Jv: Java object inspector

Java object inspector

Java Debugger/en

2014-10-08T15:03:37Z

Jv:

Java Debugger/en

2014-10-08T14:51:33Z

Jv:

Java Debugger/en

2014-10-08T14:50:15Z

Jv:

Java Debugger/en

2014-10-08T14:45:11Z

Jv: /* Breakpoints */

The ''Java Debugger plugin'' provides basic Java debugging facility. It allows for debugging of Groovy blocks and any other Java code run in remote JVM directly within expecco.

== Breakpoints ==

''Java Debugger'' plugin supports two kinds of breakpoints:

# ''Line Breakpoints'' - a traditional breakpoint set on particular line in particular method.
# ''Exception Breakpoints'' - a breakpoint that suspends execution when an exception of specified type is thrown. This is useful to find out where a particular exception is thrown.

== Debugger ==
[[Datei:expecco_JDebugger_001.png|right|thumb|JDebugger plugin: debugger window]]

The overall layout of Java debugger window is similar to debuggers for Smalltalk and JavaScript blocks. It consists of 5 panes:

1 ''Execution Stack'' - organized top-to-bottom, i.e., the currently executing method is the first entry in the list.

2 ''Source Code View'' - shows the source code of the currently selected method (in execution stack pane). Source for particular method may or may not be available. For details refer to section [[Managing Sources]]

3 ''this object inspector'' - an embedded inspector of '''this''' objects, i.e., on the receiver of the method.

4 ''Method parameters and locals inspector'' - an embedded inspector showing all method parameters and local variables which are visible at current scope.

5 ''Thread List'' - list showing all threads in the remote JVM. The ''Execution Stack'' pane shows execution stack of selected thread.

Following debugging operations are available:

* ''Continue'' - resumes execution until remote JVM terminates or another breakpoint is reached.
* ''Abort'' - aborts execution of currently executing expecco Groovy block. If the selected thread does not execute a Groovy block abortion
is not allowed.
* ''Next'' - aka ''Step-over''. Single-step to next line in currently selected method. Does not enter into called methods.
* ''Next'' - aka ''Step-into''. Single-step to next line in currently selected method or into a called method.
* ''Out'' - aka ''Step-out''. Run until currently selected method returns and stop's at the method's caller.

== Object Inspector ==

== Managing Sources ==

''Java Debugger plugin'' uses [[Java Browser/en]] fro accessing
source code. The source code for particular class / method is looked
up in Java Browser's ''default workspace''. This means that if the default workspace does not contain a source code for the class, Java debugger will not show source code. However, it is still possible to
inspect parameters and other local variables and even single-step.

If the sources does not match the sources which the Java code
has been compiled from, Java debugger may show invalid source code
or line numbers may not match. There is no way to validate the sources
matches the code loaded in remote JVM.

For more information about default workspace and how to add classes and
sources to it, please refer [[Java Browser/en|Java Browser plugin documentation]]

Java Browser/en

2014-10-08T11:40:25Z

Jv:

== Introduction ==

The '''Java Browser''' provides a simple interface to browse Java code. This is useful for test developers that write tests which uses [[ElementaryBlock_Element/en#Groovy_Blocks|Groovy blocks]] to connect to 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 Java Browser select ''Extras'' ► ''Plugins'' ► ''Java Browser'' ► ''Open...'' and then select a [[#Workspace|workspace]]. To create a new workspace, just 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 class structure without actual method's 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, just select an empty directory. To add Java code to the workspace, open workspace settings (in Java Browser window, select ''Workspace'' ► ''Settings''). In a settings dialog you may add .jar files or directories containing .class files and attach sources to then. Of course, you may use workspace settings dialog any time later add or remove .jar files or .class file directories.

Java Debugger/en

2014-10-08T11:39:13Z

Jv: /* Managing Sources */

The ''Java Debugger plugin'' provides basic Java debugging facility. It allows for debugging of Groovy blocks and any other Java code run in remote JVM directly within expecco.

== Breakpoints ==

== Debugger ==
[[Datei:expecco_JDebugger_001.png|right|thumb|JDebugger plugin: debugger window]]

The overall layout of Java debugger window is similar to debuggers for Smalltalk and JavaScript blocks. It consists of 5 panes:

1 ''Execution Stack'' - organized top-to-bottom, i.e., the currently executing method is the first entry in the list.

2 ''Source Code View'' - shows the source code of the currently selected method (in execution stack pane). Source for particular method may or may not be available. For details refer to section [[Managing Sources]]

3 ''this object inspector'' - an embedded inspector of '''this''' objects, i.e., on the receiver of the method.

4 ''Method parameters and locals inspector'' - an embedded inspector showing all method parameters and local variables which are visible at current scope.

5 ''Thread List'' - list showing all threads in the remote JVM. The ''Execution Stack'' pane shows execution stack of selected thread.

Following debugging operations are available:

* ''Continue'' - resumes execution until remote JVM terminates or another breakpoint is reached.
* ''Abort'' - aborts execution of currently executing expecco Groovy block. If the selected thread does not execute a Groovy block abortion
is not allowed.
* ''Next'' - aka ''Step-over''. Single-step to next line in currently selected method. Does not enter into called methods.
* ''Next'' - aka ''Step-into''. Single-step to next line in currently selected method or into a called method.
* ''Out'' - aka ''Step-out''. Run until currently selected method returns and stop's at the method's caller.

== Object Inspector ==

== Managing Sources ==

''Java Debugger plugin'' uses [[Java Browser/en]] fro accessing
source code. The source code for particular class / method is looked
up in Java Browser's ''default workspace''. This means that if the default workspace does not contain a source code for the class, Java debugger will not show source code. However, it is still possible to
inspect parameters and other local variables and even single-step.

If the sources does not match the sources which the Java code
has been compiled from, Java debugger may show invalid source code
or line numbers may not match. There is no way to validate the sources
matches the code loaded in remote JVM.

For more information about default workspace and how to add classes and
sources to it, please refer [[Java Browser/en|Java Browser plugin documentation]]

Java Debugger/en

2014-10-08T11:07:50Z

Jv: /* Debugger */

The ''Java Debugger plugin'' provides basic Java debugging facility. It allows for debugging of Groovy blocks and any other Java code run in remote JVM directly within expecco.

== Breakpoints ==

== Debugger ==
[[Datei:expecco_JDebugger_001.png|right|thumb|JDebugger plugin: debugger window]]

The overall layout of Java debugger window is similar to debuggers for Smalltalk and JavaScript blocks. It consists of 5 panes:

1 ''Execution Stack'' - organized top-to-bottom, i.e., the currently executing method is the first entry in the list.

2 ''Source Code View'' - shows the source code of the currently selected method (in execution stack pane). Source for particular method may or may not be available. For details refer to section [[Managing Sources]]

3 ''this object inspector'' - an embedded inspector of '''this''' objects, i.e., on the receiver of the method.

4 ''Method parameters and locals inspector'' - an embedded inspector showing all method parameters and local variables which are visible at current scope.

5 ''Thread List'' - list showing all threads in the remote JVM. The ''Execution Stack'' pane shows execution stack of selected thread.

Following debugging operations are available:

* ''Continue'' - resumes execution until remote JVM terminates or another breakpoint is reached.
* ''Abort'' - aborts execution of currently executing expecco Groovy block. If the selected thread does not execute a Groovy block abortion
is not allowed.
* ''Next'' - aka ''Step-over''. Single-step to next line in currently selected method. Does not enter into called methods.
* ''Next'' - aka ''Step-into''. Single-step to next line in currently selected method or into a called method.
* ''Out'' - aka ''Step-out''. Run until currently selected method returns and stop's at the method's caller.

== Object Inspector ==

== Managing Sources ==

Java Debugger/en

2014-10-08T10:59:01Z

Jv: Die Seite wurde neu angelegt: „The ''Java Debugger plugin'' provides basic Java debugging facility. It allows for debugging of Groovy blocks and any other Java code run in remote JVM directl…“

The ''Java Debugger plugin'' provides basic Java debugging facility. It allows for debugging of Groovy blocks and any other Java code run in remote JVM directly within expecco.

== Breakpoints ==

== Debugger ==
[[Datei:expecco_JDebugger_001.png|right|thumb|JDebugger plugin: debugger window]]

The overall layout of Java debugger window is similar to debuggers for Smalltalk and JavaScript blocks. It consists of 5 panes:

1 ''Execution Stack'' - organized top-to-bottom, i.e., the currently executing method is the first entry in the list.

2 ''Source Code View'' - shows the source code of the currently selected method (in execution stack pane). Source for particular method may or may not be available. For details refer to section [[Managing Sources]]

3 ''this object inspector'' - an embedded inspector of '''this''' objects, i.e., on the receiver of the method.

4 ''Method parameters and locals inspector'' - an embedded inspector showing all method parameters and local variables which are visible at current scope.

5 ''Thread List'' - list showing all threads in the remote JVM. The ''Execution Stack'' pane shows execution stack of selected thread.

== Object Inspector ==

== Managing Sources ==

Datei:Expecco JDebugger 001.png

2014-10-08T10:09:02Z

Jv: JDebugger plugin - debugger window

JDebugger plugin - debugger window

Themensammlung

2014-10-08T09:47:34Z

Jv: /* Code Execution */

= Expecco =

== General ==

* [[ expecco Overview | Overview]] -- Empty!
* [[ expecco Overview/en | Overview/en ]] -- empty!
* [[ Release Notes expecco]]
* [[ Release Notes expecco/en ]]
* [[ Installation ]] - initial installation, license files, patches
* [[ Installation/en ]] - initial installation, license files, patches
* [[ Configuration & Setup ]] - jre/jdk setup, pathes
* [[ Configuration & Setup/en ]] - jre/jdk setup, pathes
* [[ Personal Settings ]] - editor settings
* [[ Personal Settings/en ]] - editor settings
* [[ Report Generation ]]
* [[ Report Generation/en ]]
* [[ Concepts]] - concepts; testplan, testcase, activities, verdicts
* [[ Concepts/en]] - concepts; testplan, testcase, activities, verdicts
* [[ Command Line Options ]]
* [[ Command Line Options/en ]]
* [[ Glossary ]]
* [[ Glossary/en ]]

== expecco UI ==

* [[ Menu ]]
* [[ Menu/en ]]
* [[ Toolbar ]]
* [[ Toolbar/en ]]
* [[ Navigation Tree ]]
* [[ Navigation Tree/en ]]
* [[ Settings ]]
* [[ Settings/en ]]
* [[ Testsuite Browser ]]
* [[ Testsuite Browser/en ]]

== Editors ==

Achtung - Namen wurden in expecco geändert:
Alle Namen wie 'XXXDescriptionEditor' und 'XXXEditor' werden nun zu 'XXX_Editor' (immer Unterstrich, niemals Description)

* [[ Scheme Editor ]] ab
* [[ Scheme Editor/en ]]
* [[ Documentation Editor ]] sv
* [[ Documentation Editor/en ]]
* [[ History Editor ]] sv
* [[ History Editor/en ]]
* [[ BlockFunctionalityTestEditor ]] ca
* [[ BlockFunctionalityTestEditor/en ]]
* [[ BlockFunctionalityRunner ]] ca
* [[ BlockFunctionalityRunner/en ]]
* [[ BlockSkill Editor ]] ab
* [[ BlockSkill Editor/en ]]

* [[ ElementaryBlock Editor-Code Editor ]] cg
* [[ ElementaryBlock Editor-Code Editor/en ]]

* [[ KeywordBlock Editor-KeywordActionList Editor ]] ab
* [[ KeywordBlock Editor-KeywordActionList Editor/en ]]

* [[ CompoundBlock Editor-CompoundWorksheet Editor ]] ab
* [[ CompoundBlock Editor-CompoundWorksheet Editor/en ]]
* [[ CompoundBlock Editor-Environment Editor ]] ca
* [[ CompoundBlock Editor-Environment Editor/en ]]

* [[ TestDataGeneratorBlock Editor-TestData Editor ]] cg
* [[ TestDataGeneratorBlock Editor-TestData Editor/en ]]

* [[ TableDrivenBlock Editor-TableDrivenActionList Editor ]]
* [[ TableDrivenBlock Editor-TableDrivenActionList Editor/en ]]

* [[ Testplan Editor-TestplanEnvironment Editor ]] ca
* [[ Testplan Editor-TestplanEnvironment Editor/en ]]
* [[ Testplan Editor-TestplanListView Editor ]] ca
* [[ Testplan Editor-TestplanListView Editor/en ]]
* [[ Testplan Editor-ReportParameter Editor ]] ab
* [[ Testplan Editor-ReportParameter Editor/en ]]

* [[ Testsuite Editor-Environment Editor ]] ca
* [[ Testsuite Editor-Environment Editor/en ]]
* [[ Testsuite Editor-ExecutionSettings Editor ]] sv
* [[ Testsuite Editor-ExecutionSettings Editor/en ]]
* [[ Testsuite Editor-ReportParameter Editor ]] sv
* [[ Testsuite Editor-ReportParameter Editor/en ]]
* [[ Testsuite Editor-Metadata Editor ]] sv
* [[ Testsuite Editor-Metadata Editor/en ]]
* [[ Testsuite Editor-StatisticData Editor ]] sv
* [[ Testsuite Editor-StatisticData Editor/en ]]

* [[ TestsuiteHistory Editor ]] sv
* [[ TestsuiteHistory Editor/en ]]

* [[ Datatype Editor ]] cg
* [[ Datatype Editor/en ]]

* [[ Inventory Editor ]] ab
* [[ Inventory Editor/en ]]

* [[ ReportParameter Editor]]
* [[ ReportParameter Editor/en]]

* [[ Resource Editor ]] ab
* [[ Resource Editor/en ]]

* [[ Skill Editor ]] ab -- Achtung: nur in Deutsch
* [[ Skill Editor/en ]] -- Attention:only in German

* [[ CategoryContainer Editor ]] sv
* [[ CategoryContainer Editor/en ]]

* [[ Documentation Editor ]] sv
* [[ Documentation Editor/en ]]

* [[ FileAttachment Editor ]] cg
* [[ FileAttachment Editor/en ]]

* [[ URLAttachment Editor ]] cg
* [[ URLAttachment Editor/en ]]

* [[ ReportTemplateAttachment Editor ]] ab
* [[ ReportTemplateAttachment Editor/en ]]

* [[ GUI Editor-GUICode Editor ]] cg
* [[ GUI Editor-GUICode Editor/en ]]

==Tree-Elements==

* [[ Tree Elements ]] ab
* [[ Tree Elements/en ]]

* [[ Datatype Element ]] cg
* [[ Datatype Element/en ]]
* [[ Testplan Element ]] ca
* [[ Testplan Element/en ]]
* [[ ElementaryBlock Element ]] cg
* [[ ElementaryBlock Element/en ]]
* [[ CompoundBlock Element ]] ab
* [[ CompoundBlock Element/en ]]
* [[ Inventory Element ]] ab -- Achtung: nur in Deutsch
* [[ Inventory Element/en ]] -- Attention: only in German
* [[ Skill Element ]] ab -- Achtung: nur in Deutsch
* [[ Skill Element/en ]] -- Attention: only in German
* [[ Resource Element ]] ab -- Achtung: nur in Deutsch
* [[ Resource Element/en ]] -- Attention: only in German
* [[ Attachment Element ]] cg
* [[ Attachment Element/en ]]
* [[ ReportTemplate Element ]] ab
* [[ ReportTemplate Element/en ]]
* [[ KeywordBlock Element ]] ab
* [[ KeywordBlock Element/en ]]
* [[ TestDataGeneratorBlock Element ]] cg
* [[ TestDataGeneratorBlock Element/en ]]
* [[ VirtualBlock Element ]] sv
* [[ VirtualBlock Element/en ]]
* [[ UnimplementedBlock Element ]] sv
* [[ UnimplementedBlock Element/en ]]
* [[ GUIBlock Element ]] cg
* [[ GUIBlock Element/en ]]
* [[ Block Element ]] sv
* [[ Block Element/en ]]
* [[ Folder Element ]] sv
* [[ Folder Element/en ]]

==Diagram-Elements==

Achtung: DiagramElements-XXXPin gehen nun alle nach DiagramElements-Pin#typeofPin. Also z.B. DiagramElements-Pin#Enable_Output_pin.
entsprechende hash-tags müssen in DiagramElements-Pin erhalten bleiben.

* [[ DiagramElements-Pin ]]
* [[ DiagramElements-Pin/en ]]

* [[ DiagramElements-Pin#Enable Input Pin ]]
* [[ DiagramElements-Pin#Cancel Input Pin ]]
* [[ DiagramElements-Pin#Iterate Input Pin ]]
* [[ DiagramElements-Pin#Timelimit Input Pin ]]
* [[ DiagramElements-Pin#Performer Input Pin ]]
* [[ DiagramElements-Pin#Input Pin ]]
* [[ DiagramElements-Pin#Exception Output Pin ]]
* [[ DiagramElements-Pin#Enable Output Pin ]]
* [[ DiagramElements-Pin#ExecutionTime Output Pin ]]
* [[ DiagramElements-Pin#Output Pin ]]

* [[ DiagramElements-Step ]]
* [[ DiagramElements-Step/en ]]
* [[ DiagramElements-AttachmentStep ]]
* [[ DiagramElements-AttachmentStep/en ]]
* [[ DiagramElements-Connection ]]
* [[ DiagramElements-Connection/en ]]
* [[ DiagramElements-PinDescription ]]
* [[ DiagramElements-PinDescription/en ]]
* [[ DiagramElements-Annotation ]] -- Achtung: nur auf Deutsch
* [[ DiagramElements-Annotation/en ]] -- Attention: only in German
* [[ DiagramElements-Probe ]]
* [[ DiagramElements-Probe/en ]]

== Plugins and Extensions ==

=== UI Testing ===

* [[ Selenium Web Test Plugin ]] -- Web Page Tests and Interaction
* [[ Selenium Web Test Plugin/en ]]
* [[ SeleniumLibrary Reference ]] -- Library reference

* [[ AndroidLibrary Reference ]] -- Anroid UI Test and Interaction

=== Code Execution ===

* [[ Java Browser ]] -- allows for Java classes to be browsed in the SUT
* [[ Java Browser/en ]]
* [[ Java Debugger ]] -- allows to debug Groovy blocks and other code executed by Java Bridge in (remote) JVM
* [[ Java Debugger/en ]]
* [[ SmallSense ]] -- together with [[ Java Browser/en ]] provides basic completion support for Groovy code.
* [[ SmallSense/en ]]

* [[ Groovy Code Execution Plugin/en ]] -- allows for Groovy code to be executed on the SUT
* [[ VBScript | VisualBasic Script Plugin/en ]]

=== Manual Test Support Plugins ===

* [[ Manual Test Plugin ]] -- guides users through manual tests
* [[ Manual Test Import Plugin ]] -- imports test specifications written in Word or Excel

=== Misc Plugins ===

* [[ GembirdPowerControlPlugin Reference ]] -- control a power plug

=== QM Interface Plugins ===

* [[ PolarionPlugin Reference ]] - automate execution from & interact with Polarion
* [[ ExpeccoNET Plugin Reference ]] - automate execution from & interact with expeccoNET
* [[ HP Quality Center Plugin Reference ]] - automate execution from and interact with HP Quality Center

* [[ WSDL Service Import Plugin ]] -- import service actions from a WSDL service description

== Concepts, Hints, Tips and Tricks ==

* [[ Expecco API ]]
* [[ Expecco API/en ]]
* [[ Executor]]
* [[ Executor#Activity]]

* [[ Generating Test Data ]]
* [[ Parametrizing Tests ]]
* [[ Organizing Libraries ]]
* [[ Reimporting a Library]]
* [[ User Defined Menu Items ]]
* [[ Uses of Tags ]]

== Tutorials ==

* [[Testing Java Applications using Groovy blocks]]
* [[Testing Java Applications using Groovy blocks/en]]
= ExpeccoNet =

== ExpeccoNET General ==

* [[ expeccoNET Overview | Overview]]
* [[ expeccoNET Overview/en | Overview/en ]]
* [[ expeccoNET Release Notes | Release Notes]]
* [[ expeccoNET Release Notes/en | Release Notes/en ]]
* [[ expeccoNET Installation | Installation ]] - initial installation, license files, patches
* [[ expeccoNET Installation/en | Installation/en ]] - initial installation, license files, patches
* [[ expeccoNET Configuration & Setup | Configuration & Setup ]] - setting up users, roles and projects
* [[ expeccoNET Configuration & Setup/en | Configuration & Setup/en ]] - setting up users, roles and projects
* [[ expeccoNET Personal Settings | Personal Settings ]] - editor settings
* [[ expeccoNET Personal Settings/en | Personal Settings/en ]] - editor settings
* [[ expeccoNET Concepts |Concepts ]] - concepts; testsuite, testdefinition, testschedule, testrun, testequipment
* [[ expeccoNET Concepts/en | Concepts/en ]] - concepts; testsuite, testdefinition, testschedule, testrun, testequipment
* [[ expeccoNET Glossary | Glossary ]]
* [[ expeccoNET Glossary/en | Glossary/en ]]

== expeccoNET UI ==

* [[ expeccoNET Master Menu | Master Menu]]
* [[ expeccoNET Master Menu/en | Master Menu/en ]]
* [[ expeccoNET Requirements UI | Requirements UI ]]
* [[ expeccoNET Requirements UI/en | Requirements UI/en ]]
* [[ expeccoNET Defects UI | Defects UI]]
* [[ expeccoNET Defects UI/en | Defects UI/en ]]
* [[ expeccoNET Actions UI | Actions UI ]]
* [[ expeccoNET Actions UI/en |Actions UI/en ]]
* [[ expeccoNET Tests UI | Tests UI ]]
* [[ expeccoNET Tests UI/en | Tests UI/en ]]
* [[ expeccoNET Projects UI | Projects UI ]]
* [[ expeccoNET Projects UI/en | Projects UI/en ]]
* [[ expeccoNET Organization UI | Organization UI ]]
* [[ expeccoNET Organization UI/en | Organization UI/en ]]
* [[ expeccoNET Settings UI | Settings UI ]]
* [[ expeccoNET Settings UI/en | Settings UI/en ]]

== expeccoNET Plugins and Extensions ==

* [[ expeccoNET HP Quality Center Synchronization Plugin | HP Quality Center Synchronization Plugin]]
* [[ expeccoNET HP Quality Center Synchronization Plugin/en | HP Quality Center Synchronization Plugin/en ]]

= License Server =

== License Server General ==

* [[ License Server Overview | Overview]] -- Achtung: nur in Deutsch
* [[ License Server Overview/en | Overview/en ]] -- Attention: only in German
* [[ License Server Release Notes | Release Notes]]
* [[ License Server Release Notes/en | Release Notes/en ]] -- Attention: only in German
* [[ License Server Installation | Installation]] - initial installation, license files, updates -- Achtung: nur in Deutsch
* [[ License Server Installation/en | Installation/en ]] - initial installation, license files, updates -- Attention: only in German
* [[ License Server Configuration & Setup | Configuration & Setup ]] - setting up ports and users -- Achtung: nur in Deutsch
* [[ License Server Configuration & Setup/en | Configuration & Setup/en ]] - setting up ports and users -- Attention: only in German
* [[ License Server Glossary | Glossary]] -- Achtung: nur in Englisch
* [[ License Server Glossary/en | Glossary/en]] -- Achtung: nur in English

== License Server UI ==

* [[ License Server License Menu | License Menu ]]
* [[ License Server License Menu/en | License Menu/en]]

Testing Java Applications using Groovy blocks/en

2014-10-03T11:53:29Z

Jv: /* TODO */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests I ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Debugging tests II ==

Let's write yet another test that tries to transfer a negative amount. The API documentation does not specify the behaviour in this case explicitly.
The would look like the very first test except the amount would be -500 rather than 500 and the final balances would be the other way around.

Actually such a test would fail. As you may see, the code throws a ```TransactionException``` with rather unspecific message ''Internal error occired during transaction''. The message is bit worrying as, if negative value is now allowed, the error message should say so. It could be that something else went wrong.

[[Datei:expecco_BankAccounts_017.png]]

To find out, we may again use Java debugger plugin and place an ''exception breakpoint'', a special kind of breakpoint that stops program execution
when an exception of specific type is thrown. To do so, go to ''Plugins'' ► ''Java Debugger'' ► ''Breakpoint List''. This opens a little window displaying
all Java breakpoints, including ''line breakpoints'' we have used earlier.
Use context menu (right-click in the list) to add an exception breakpoint:

[[Datei:expecco_BankAccounts_018.png]]

A dialog will appear where you can specify exception class name - '''exept.expecco.projects.examples.bankaccount.TransactionException''' in this case. Be aware, it '''has''' to be a fully qualified Java class name.
Also, you have to tick both ''Caught'' and ''Uncaught'' checkboxes, as the Java bridge code catches all exceptions.

[[Datei:expecco_BankAccounts_020.png]]

Now run the test again. A debugger should appear, stopping at line 65 in
'''Transaction.java'''. The code here simply catches all exceptions and re-throw a '''TransactionException'''. So still it's not clear what is the real cause. To find out, let's check what is the value of the original exception, stored in variable '''e''' (just click or double-click to ''e'' in bottom left part of the debugger window which shows local variables).

It's a '''java.security.InvalidParameterException'''. Let's just put another exception breakpoint, now for '''java.security.InvalidParameterException''' and run the test again. This should reveal the origin of the problem.

[[Datei:expecco_BankAccounts_021.png]]

If you run it again, you may see that the exception is thrown in '''Transaction#check()''' if the amount specified is less than zero.

== Wrap-up ==

The ''Java browser plugin'', ''Java Debugger plugin'' and ''SmallSense plugin'' can make test development using Groovy block easier:

* ''Java browser plugin'' provides a way to browse Java code right from the expecco environment, without need of external, third-party IDE.
* ''SmallSense plugin'' provides a simple completion support to Groovy block editor, making editing easier.
* ''Java Debugger plugin'' provides in-expecco debugging facilities to debug Java code running system under test, making test debugging easier.

These plugins are not necessary to use Groovy blocks, however, working with
complex Java code might tricky when it comes to test debugging. While it is possible to use third-party Java IDEs and debuggers, the added value of these
plugins is tight integration with expecco.

For more information, refer to:

* [[Java Browser/en]]
* [[Java Debugger/en]]
* [[SmallSense/en]]

== Download ==

* Eclipse Project with "BankAccount" code - [[Medium:bankaccount-eclipse.zip|bankaccount-eclipse.zip]]
* Expecco test suite with tests from this tutorial - [[Medium:bankaccount.ets|bankaccount.ets]]

== TODO ==

* cleanup ''You'' / ''we''
* Upload standalone .ets and .zip with Eclipse project Java doc somewhere
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents), once above get sorted.

Testing Java Applications using Groovy blocks/en

2014-10-03T11:52:26Z

Jv: /* Rubbish to remove */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests I ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Debugging tests II ==

Let's write yet another test that tries to transfer a negative amount. The API documentation does not specify the behaviour in this case explicitly.
The would look like the very first test except the amount would be -500 rather than 500 and the final balances would be the other way around.

Actually such a test would fail. As you may see, the code throws a ```TransactionException``` with rather unspecific message ''Internal error occired during transaction''. The message is bit worrying as, if negative value is now allowed, the error message should say so. It could be that something else went wrong.

[[Datei:expecco_BankAccounts_017.png]]

To find out, we may again use Java debugger plugin and place an ''exception breakpoint'', a special kind of breakpoint that stops program execution
when an exception of specific type is thrown. To do so, go to ''Plugins'' ► ''Java Debugger'' ► ''Breakpoint List''. This opens a little window displaying
all Java breakpoints, including ''line breakpoints'' we have used earlier.
Use context menu (right-click in the list) to add an exception breakpoint:

[[Datei:expecco_BankAccounts_018.png]]

A dialog will appear where you can specify exception class name - '''exept.expecco.projects.examples.bankaccount.TransactionException''' in this case. Be aware, it '''has''' to be a fully qualified Java class name.
Also, you have to tick both ''Caught'' and ''Uncaught'' checkboxes, as the Java bridge code catches all exceptions.

[[Datei:expecco_BankAccounts_020.png]]

Now run the test again. A debugger should appear, stopping at line 65 in
'''Transaction.java'''. The code here simply catches all exceptions and re-throw a '''TransactionException'''. So still it's not clear what is the real cause. To find out, let's check what is the value of the original exception, stored in variable '''e''' (just click or double-click to ''e'' in bottom left part of the debugger window which shows local variables).

It's a '''java.security.InvalidParameterException'''. Let's just put another exception breakpoint, now for '''java.security.InvalidParameterException''' and run the test again. This should reveal the origin of the problem.

[[Datei:expecco_BankAccounts_021.png]]

If you run it again, you may see that the exception is thrown in '''Transaction#check()''' if the amount specified is less than zero.

== Wrap-up ==

The ''Java browser plugin'', ''Java Debugger plugin'' and ''SmallSense plugin'' can make test development using Groovy block easier:

* ''Java browser plugin'' provides a way to browse Java code right from the expecco environment, without need of external, third-party IDE.
* ''SmallSense plugin'' provides a simple completion support to Groovy block editor, making editing easier.
* ''Java Debugger plugin'' provides in-expecco debugging facilities to debug Java code running system under test, making test debugging easier.

These plugins are not necessary to use Groovy blocks, however, working with
complex Java code might tricky when it comes to test debugging. While it is possible to use third-party Java IDEs and debuggers, the added value of these
plugins is tight integration with expecco.

For more information, refer to:

* [[Java Browser/en]]
* [[Java Debugger/en]]
* [[SmallSense/en]]

== Download ==

* Eclipse Project with "BankAccount" code - [[Medium:bankaccount-eclipse.zip|bankaccount-eclipse.zip]]
* Expecco test suite with tests from this tutorial - [[Medium:bankaccount.ets|bankaccount.ets]]

== TODO ==

* cleanup ''You'' / ''we''
* write wrap-up section
* Upload standalone .ets and .zip with Eclipse project Java doc somewhere
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents), once above get sorted.

Testing Java Applications using Groovy blocks/en

2014-10-03T11:47:32Z

Jv: /* Wrap-up */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests I ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Debugging tests II ==

Let's write yet another test that tries to transfer a negative amount. The API documentation does not specify the behaviour in this case explicitly.
The would look like the very first test except the amount would be -500 rather than 500 and the final balances would be the other way around.

Actually such a test would fail. As you may see, the code throws a ```TransactionException``` with rather unspecific message ''Internal error occired during transaction''. The message is bit worrying as, if negative value is now allowed, the error message should say so. It could be that something else went wrong.

[[Datei:expecco_BankAccounts_017.png]]

To find out, we may again use Java debugger plugin and place an ''exception breakpoint'', a special kind of breakpoint that stops program execution
when an exception of specific type is thrown. To do so, go to ''Plugins'' ► ''Java Debugger'' ► ''Breakpoint List''. This opens a little window displaying
all Java breakpoints, including ''line breakpoints'' we have used earlier.
Use context menu (right-click in the list) to add an exception breakpoint:

[[Datei:expecco_BankAccounts_018.png]]

A dialog will appear where you can specify exception class name - '''exept.expecco.projects.examples.bankaccount.TransactionException''' in this case. Be aware, it '''has''' to be a fully qualified Java class name.
Also, you have to tick both ''Caught'' and ''Uncaught'' checkboxes, as the Java bridge code catches all exceptions.

[[Datei:expecco_BankAccounts_020.png]]

Now run the test again. A debugger should appear, stopping at line 65 in
'''Transaction.java'''. The code here simply catches all exceptions and re-throw a '''TransactionException'''. So still it's not clear what is the real cause. To find out, let's check what is the value of the original exception, stored in variable '''e''' (just click or double-click to ''e'' in bottom left part of the debugger window which shows local variables).

It's a '''java.security.InvalidParameterException'''. Let's just put another exception breakpoint, now for '''java.security.InvalidParameterException''' and run the test again. This should reveal the origin of the problem.

[[Datei:expecco_BankAccounts_021.png]]

If you run it again, you may see that the exception is thrown in '''Transaction#check()''' if the amount specified is less than zero.

== Wrap-up ==

The ''Java browser plugin'', ''Java Debugger plugin'' and ''SmallSense plugin'' can make test development using Groovy block easier:

* ''Java browser plugin'' provides a way to browse Java code right from the expecco environment, without need of external, third-party IDE.
* ''SmallSense plugin'' provides a simple completion support to Groovy block editor, making editing easier.
* ''Java Debugger plugin'' provides in-expecco debugging facilities to debug Java code running system under test, making test debugging easier.

These plugins are not necessary to use Groovy blocks, however, working with
complex Java code might tricky when it comes to test debugging. While it is possible to use third-party Java IDEs and debuggers, the added value of these
plugins is tight integration with expecco.

For more information, refer to:

* [[Java Browser/en]]
* [[Java Debugger/en]]
* [[SmallSense/en]]

== Download ==

* Eclipse Project with "BankAccount" code - [[Medium:bankaccount-eclipse.zip|bankaccount-eclipse.zip]]
* Expecco test suite with tests from this tutorial - [[Medium:bankaccount.ets|bankaccount.ets]]

== TODO ==

* cleanup ''You'' / ''we''
* write wrap-up section
* Upload standalone .ets and .zip with Eclipse project Java doc somewhere
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents), once above get sorted.

== Rubbish to remove ==

<pre>
java -agentlib:jdwp=transportt_socket,server=y,suspend=n,address=3003 \
-cp bin \
-jar "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/agents/JavaBridge.jar"\
-port 5005 -asServer -localOnly \
-extDir "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/ext"
</pre>

Testing Java Applications using Groovy blocks/en

2014-10-03T11:24:49Z

Jv: /* TODO */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests I ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Debugging tests II ==

Let's write yet another test that tries to transfer a negative amount. The API documentation does not specify the behaviour in this case explicitly.
The would look like the very first test except the amount would be -500 rather than 500 and the final balances would be the other way around.

Actually such a test would fail. As you may see, the code throws a ```TransactionException``` with rather unspecific message ''Internal error occired during transaction''. The message is bit worrying as, if negative value is now allowed, the error message should say so. It could be that something else went wrong.

[[Datei:expecco_BankAccounts_017.png]]

To find out, we may again use Java debugger plugin and place an ''exception breakpoint'', a special kind of breakpoint that stops program execution
when an exception of specific type is thrown. To do so, go to ''Plugins'' ► ''Java Debugger'' ► ''Breakpoint List''. This opens a little window displaying
all Java breakpoints, including ''line breakpoints'' we have used earlier.
Use context menu (right-click in the list) to add an exception breakpoint:

[[Datei:expecco_BankAccounts_018.png]]

A dialog will appear where you can specify exception class name - '''exept.expecco.projects.examples.bankaccount.TransactionException''' in this case. Be aware, it '''has''' to be a fully qualified Java class name.
Also, you have to tick both ''Caught'' and ''Uncaught'' checkboxes, as the Java bridge code catches all exceptions.

[[Datei:expecco_BankAccounts_020.png]]

Now run the test again. A debugger should appear, stopping at line 65 in
'''Transaction.java'''. The code here simply catches all exceptions and re-throw a '''TransactionException'''. So still it's not clear what is the real cause. To find out, let's check what is the value of the original exception, stored in variable '''e''' (just click or double-click to ''e'' in bottom left part of the debugger window which shows local variables).

It's a '''java.security.InvalidParameterException'''. Let's just put another exception breakpoint, now for '''java.security.InvalidParameterException''' and run the test again. This should reveal the origin of the problem.

[[Datei:expecco_BankAccounts_021.png]]

If you run it again, you may see that the exception is thrown in '''Transaction#check()''' if the amount specified is less than zero.

== Wrap-up ==

TBW

== Download ==

* Eclipse Project with "BankAccount" code - [[Medium:bankaccount-eclipse.zip|bankaccount-eclipse.zip]]
* Expecco test suite with tests from this tutorial - [[Medium:bankaccount.ets|bankaccount.ets]]

== TODO ==

* cleanup ''You'' / ''we''
* write wrap-up section
* Upload standalone .ets and .zip with Eclipse project Java doc somewhere
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents), once above get sorted.

== Rubbish to remove ==

<pre>
java -agentlib:jdwp=transportt_socket,server=y,suspend=n,address=3003 \
-cp bin \
-jar "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/agents/JavaBridge.jar"\
-port 5005 -asServer -localOnly \
-extDir "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/ext"
</pre>

Testing Java Applications using Groovy blocks/en

2014-10-03T11:20:20Z

Jv: /* Wrap-up */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests I ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Debugging tests II ==

Let's write yet another test that tries to transfer a negative amount. The API documentation does not specify the behaviour in this case explicitly.
The would look like the very first test except the amount would be -500 rather than 500 and the final balances would be the other way around.

Actually such a test would fail. As you may see, the code throws a ```TransactionException``` with rather unspecific message ''Internal error occired during transaction''. The message is bit worrying as, if negative value is now allowed, the error message should say so. It could be that something else went wrong.

[[Datei:expecco_BankAccounts_017.png]]

To find out, we may again use Java debugger plugin and place an ''exception breakpoint'', a special kind of breakpoint that stops program execution
when an exception of specific type is thrown. To do so, go to ''Plugins'' ► ''Java Debugger'' ► ''Breakpoint List''. This opens a little window displaying
all Java breakpoints, including ''line breakpoints'' we have used earlier.
Use context menu (right-click in the list) to add an exception breakpoint:

[[Datei:expecco_BankAccounts_018.png]]

A dialog will appear where you can specify exception class name - '''exept.expecco.projects.examples.bankaccount.TransactionException''' in this case. Be aware, it '''has''' to be a fully qualified Java class name.
Also, you have to tick both ''Caught'' and ''Uncaught'' checkboxes, as the Java bridge code catches all exceptions.

[[Datei:expecco_BankAccounts_020.png]]

Now run the test again. A debugger should appear, stopping at line 65 in
'''Transaction.java'''. The code here simply catches all exceptions and re-throw a '''TransactionException'''. So still it's not clear what is the real cause. To find out, let's check what is the value of the original exception, stored in variable '''e''' (just click or double-click to ''e'' in bottom left part of the debugger window which shows local variables).

It's a '''java.security.InvalidParameterException'''. Let's just put another exception breakpoint, now for '''java.security.InvalidParameterException''' and run the test again. This should reveal the origin of the problem.

[[Datei:expecco_BankAccounts_021.png]]

If you run it again, you may see that the exception is thrown in '''Transaction#check()''' if the amount specified is less than zero.

== Wrap-up ==

TBW

== Download ==

* Eclipse Project with "BankAccount" code - [[Medium:bankaccount-eclipse.zip|bankaccount-eclipse.zip]]
* Expecco test suite with tests from this tutorial - [[Medium:bankaccount.ets|bankaccount.ets]]

== TODO ==

* cleanup ''You'' / ''we''
* write wrap-up section
* Make standalone .ets and .zip with Eclipse project, commit it and make it ready for download.
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents)

== Rubbish to remove ==

<pre>
java -agentlib:jdwp=transportt_socket,server=y,suspend=n,address=3003 \
-cp bin \
-jar "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/agents/JavaBridge.jar"\
-port 5005 -asServer -localOnly \
-extDir "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/ext"
</pre>

Testing Java Applications using Groovy blocks/en

2014-10-02T15:23:56Z

Jv: /* TODO */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests I ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Debugging tests II ==

Let's write yet another test that tries to transfer a negative amount. The API documentation does not specify the behaviour in this case explicitly.
The would look like the very first test except the amount would be -500 rather than 500 and the final balances would be the other way around.

Actually such a test would fail. As you may see, the code throws a ```TransactionException``` with rather unspecific message ''Internal error occired during transaction''. The message is bit worrying as, if negative value is now allowed, the error message should say so. It could be that something else went wrong.

[[Datei:expecco_BankAccounts_017.png]]

To find out, we may again use Java debugger plugin and place an ''exception breakpoint'', a special kind of breakpoint that stops program execution
when an exception of specific type is thrown. To do so, go to ''Plugins'' ► ''Java Debugger'' ► ''Breakpoint List''. This opens a little window displaying
all Java breakpoints, including ''line breakpoints'' we have used earlier.
Use context menu (right-click in the list) to add an exception breakpoint:

[[Datei:expecco_BankAccounts_018.png]]

A dialog will appear where you can specify exception class name - '''exept.expecco.projects.examples.bankaccount.TransactionException''' in this case. Be aware, it '''has''' to be a fully qualified Java class name.
Also, you have to tick both ''Caught'' and ''Uncaught'' checkboxes, as the Java bridge code catches all exceptions.

[[Datei:expecco_BankAccounts_020.png]]

Now run the test again. A debugger should appear, stopping at line 65 in
'''Transaction.java'''. The code here simply catches all exceptions and re-throw a '''TransactionException'''. So still it's not clear what is the real cause. To find out, let's check what is the value of the original exception, stored in variable '''e''' (just click or double-click to ''e'' in bottom left part of the debugger window which shows local variables).

It's a '''java.security.InvalidParameterException'''. Let's just put another exception breakpoint, now for '''java.security.InvalidParameterException''' and run the test again. This should reveal the origin of the problem.

[[Datei:expecco_BankAccounts_021.png]]

If you run it again, you may see that the exception is thrown in '''Transaction#check()''' if the amount specified is less than zero.

== Wrap-up ==

TBW

== TODO ==

* cleanup ''You'' / ''we''
* write wrap-up section
* Make standalone .ets and .zip with Eclipse project, commit it and make it ready for download.
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents)

== Rubbish to remove ==

<pre>
java -agentlib:jdwp=transportt_socket,server=y,suspend=n,address=3003 \
-cp bin \
-jar "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/agents/JavaBridge.jar"\
-port 5005 -asServer -localOnly \
-extDir "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/ext"
</pre>

Testing Java Applications using Groovy blocks/en

2014-10-02T15:23:14Z

Jv: /* Debugging tests II */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests I ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Debugging tests II ==

Let's write yet another test that tries to transfer a negative amount. The API documentation does not specify the behaviour in this case explicitly.
The would look like the very first test except the amount would be -500 rather than 500 and the final balances would be the other way around.

Actually such a test would fail. As you may see, the code throws a ```TransactionException``` with rather unspecific message ''Internal error occired during transaction''. The message is bit worrying as, if negative value is now allowed, the error message should say so. It could be that something else went wrong.

[[Datei:expecco_BankAccounts_017.png]]

To find out, we may again use Java debugger plugin and place an ''exception breakpoint'', a special kind of breakpoint that stops program execution
when an exception of specific type is thrown. To do so, go to ''Plugins'' ► ''Java Debugger'' ► ''Breakpoint List''. This opens a little window displaying
all Java breakpoints, including ''line breakpoints'' we have used earlier.
Use context menu (right-click in the list) to add an exception breakpoint:

[[Datei:expecco_BankAccounts_018.png]]

A dialog will appear where you can specify exception class name - '''exept.expecco.projects.examples.bankaccount.TransactionException''' in this case. Be aware, it '''has''' to be a fully qualified Java class name.
Also, you have to tick both ''Caught'' and ''Uncaught'' checkboxes, as the Java bridge code catches all exceptions.

[[Datei:expecco_BankAccounts_020.png]]

Now run the test again. A debugger should appear, stopping at line 65 in
'''Transaction.java'''. The code here simply catches all exceptions and re-throw a '''TransactionException'''. So still it's not clear what is the real cause. To find out, let's check what is the value of the original exception, stored in variable '''e''' (just click or double-click to ''e'' in bottom left part of the debugger window which shows local variables).

It's a '''java.security.InvalidParameterException'''. Let's just put another exception breakpoint, now for '''java.security.InvalidParameterException''' and run the test again. This should reveal the origin of the problem.

[[Datei:expecco_BankAccounts_021.png]]

If you run it again, you may see that the exception is thrown in '''Transaction#check()''' if the amount specified is less than zero.

== Wrap-up ==

TBW

== TODO ==

* write a section on exceptions
* write wrap-up section
* Make standalone .ets and .zip with Eclipse project, commit it and make it ready for download.
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents)

== Rubbish to remove ==

<pre>
java -agentlib:jdwp=transportt_socket,server=y,suspend=n,address=3003 \
-cp bin \
-jar "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/agents/JavaBridge.jar"\
-port 5005 -asServer -localOnly \
-extDir "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/ext"
</pre>

Datei:Expecco BankAccounts 021.png

2014-10-02T15:20:35Z

Jv:

Datei:Expecco BankAccounts 020.png

2014-10-02T15:11:15Z

Jv:

Datei:Expecco BankAccounts 018.png

2014-10-02T15:05:24Z

Jv:

Datei:Expecco BankAccounts 017.png

2014-10-02T15:02:17Z

Jv:

Testing Java Applications using Groovy blocks/en

2014-10-02T14:41:00Z

Jv: /* Implementing the first test */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests I ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Debugging tests II ==

== Wrap-up ==

TBW

== TODO ==

* write a section on exceptions
* write wrap-up section
* Make standalone .ets and .zip with Eclipse project, commit it and make it ready for download.
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents)

== Rubbish to remove ==

<pre>
java -agentlib:jdwp=transportt_socket,server=y,suspend=n,address=3003 \
-cp bin \
-jar "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/agents/JavaBridge.jar"\
-port 5005 -asServer -localOnly \
-extDir "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/ext"
</pre>

Testing Java Applications using Groovy blocks/en

2014-10-02T14:23:54Z

Jv: /* Debugging tests */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Extras'' ► ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests I ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Debugging tests II ==

== Wrap-up ==

TBW

== TODO ==

* write a section on exceptions
* write wrap-up section
* Make standalone .ets and .zip with Eclipse project, commit it and make it ready for download.
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents)

== Rubbish to remove ==

<pre>
java -agentlib:jdwp=transportt_socket,server=y,suspend=n,address=3003 \
-cp bin \
-jar "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/agents/JavaBridge.jar"\
-port 5005 -asServer -localOnly \
-extDir "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/ext"
</pre>

Testing Java Applications using Groovy blocks/en

2014-10-01T12:14:15Z

Jv: /* To remove */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Extras'' ► ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== Wrap-up ==

TBW

== TODO ==

* write a section on exceptions
* write wrap-up section
* Make standalone .ets and .zip with Eclipse project, commit it and make it ready for download.
* Upload Java doc somewhere
* Fix crossrefs (to javadoc and other documents)

== Rubbish to remove ==

<pre>
java -agentlib:jdwp=transportt_socket,server=y,suspend=n,address=3003 \
-cp bin \
-jar "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/agents/JavaBridge.jar"\
-port 5005 -asServer -localOnly \
-extDir "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/ext"
</pre>

Testing Java Applications using Groovy blocks/en

2014-10-01T12:11:23Z

Jv: /* Debugging tests */

This example demonstrates how to use [[Java Browser/en]], [[Java Debugger/en]] and [[SmallSense/en]] plugins for Java application test development. It shows
how to use Groovy blocks to

== The Bank Account Example ==

Through this tutorial, we'll use a simple "Bank Account" as system under test.
"Bank Account" is a very simple Java library that models banks and accounts
and allow transation among accounts.

The code of the "Bank Account" application is not correct at place bu purpose.
You may download a full Eclipse project containing the example code at
[http://www.example.com somewhere].

== Setting up expecco ==

For the sake of brevity, in this tutorial we'll use simple local JVM managed by
expecco to run "Bank Account"s code.
As for any Java application, we have to set up a classpath properly so the JVM
can find application code.

Let's define an expecco environment variable named '''CLASSPATH_BANKACCOUNT''' defining where the "Bank Account" code is actually located:

[[Datei:expecco_BankAccounts_001.png]]

Then let's define a "SetUp" block that actually adds the directory to JVM class path. A simple JavaScript block would do it:

<code>
execute
JAVA::Java singletonInstance
addToClassPath: (self environmentAt: 'CLASSPATH_BANKACCOUNT')
</code>

This block has to be run before any other Java code using "Bank Account" classes is run. Putting it as test plan's pre-execution block [[!ref!]] might be
a good way to ensure it.

== Designing a test ==

Once the class path is set up, we start designing an implementing tests. Let's start with a simple tests that create a two bank accounts and then make transfer from one account to the other. Then tests would check if the final balance on accounts is what one would expect.

The very simple test would be then:

* create account ''A1'' with initial balance 1000.
* create account ''A2'' with initial balance 1000.
* transfer 500 from account ''A2'' to account ''A1''.
* check that final balance of ''A1'' is 1500
* check that final balance of ''A2'' is 500.
* check that no exception was thrown.

We will encapsulate first three steps in to a special block, let's call it
''Create 2 accounts & make a transaction'', which will take initial balances
and amount to transfer from input pins and report final balances to output pins. In addition, it will report an eventual exception via exception output
pin.

By separating this logic to a separate block we can easily create more
tests with different value to test different scenarios like: to check that an exception is raised when there are not enough funds on a charged account.

So, in expecco, the very simple testcase outlined above would look like:

[[Datei:expecco_BankAccounts_002.png]]

== Implementing the first test ==

In order to implement the test as outlined above, we have to implement a block that actually call the Java API.

[[Java Browser/en]] plugin for expecco provides a simple browser to load and browse Java code directly from expecco environment.
To open a Java Browser on "Bank Account" code, select ''Extras'' ► ''Plugins'' ► ''Java Browser'' ► ''Open...'' from expecco menu and define a new Java browser workspace. A Java browser workspace is a folder where Java Browser stores all the Java code
and sources. You can define as many workspaces as you like and
switch between them. If you don't have a workspace for "Bank Account" yet, just enter an empty directory and new workspace will be created.
Initially the workspace is empty, so to actually see the code of "Bank Account", we have add it's code and sources to the workspace. To do so,
just click to ''Open Settings'' button in Java Browser window or select ''Workspace'' ► ''Settings'' from window menu. In Settings dialog,
click to ''Add Library'' button and add ''Bank Account'' code. One added and confirmed (by pressing ''OK'' button), you may browse through the
code, check what classes and methods are available and so on.

[[Datei:expecco_BankAccounts_005.png]]

Let's implement the ''Create 2 accounts & make a transaction'' block now. Just create a new Groovy block and write a little code that calls "Bank Account" Java API.

To make writing code a little bit easier, [[SmallSense/en]] plugin together with [[Java Browser/en]]
plugin provides a simple completion support for Groovy. The completion engine takes information about available classes
and methods from the Java workspace. In other words, if you have no Java browser workspace opened, the completion won't
suggest any classes nor methods.

To trigger the completion, just press ''Ctrl-Space'':

[[Datei:expecco_BankAccounts_006.png]]

The code of the block may be the following:

<pre>
import exept.expecco.projects.examples.bankaccount.Bank;
import exept.expecco.projects.examples.bankaccount.Account;
// end of definitions -- do not remove this line unless imports above is
empty

def execute() {
Bank b = new Bank( "Some bank" );

Account account1 = new Account( "Owner 1" );
b.addAccount( account1 );
account1.setBalance( initialBalance1.value() );

Account account2 = new Account( "Owner 2" );
b.addAccount( account2 );
account2.setBalance( initialBalance2.value() );

try {
account1.credit(account2, amount.value() );
exception.value( null );
} catch ( TransactionException e ) {
exception.value( e );
}

balance1.value( account1.getBalance() );
balance2.value( account2.getBalance() );
}
</pre>

Now we have all bits together to implement and run the simple test. It passes.

[[Datei:expecco_BankAccounts_010.png]]

== Debugging tests ==

One test passed. but let's create another one. Similar, but with different,
extrem values. Let's try to transfer an awful lot of money so the balance of
credited account would exceed the maximum allowed balance. According to a specification [!ref!] the transation should not proceed and an '''TransactionException''' should be thrown. The test may look as following:

[[Datei:expecco_BankAccounts_011.png]]

If you try to run it you will see it fails. Now it's time to figure out why and this is the point where [[Java Debugger/en]] plugin is useful. Basically,
Java Debugger plugin allows you to debug code running in remote JVM - placing
breakpoints, single-stepping through the code, inspecting values of variables
and objects.

Back to our failing test. The code of a Groovy block likely correct. The actual transfer is done in method '''BankAccount#credit()''' [!ref!]. Let's
put a breakpoint here and then single-step through the code until we reach the point where the actual computation is done.

To place a breakpoint, simply open a Java Browser, select class '''Account''' and method '''credit()''' and then put a breakpoint at the beginning of the method (by clicking in the editor, left to the line number):

[[Datei:expecco_BankAccounts_012.png]]

Now run the test again. A Java Debugger window should appear:

[[Datei:expecco_BankAccounts_014.png]]

The debugger shows a Java execution stack on the top, source code of the
selected method in the middle and an inspector for '''this''' and for local variables in the bottom part.
Let's single step a little bit further, into method '''Transaction#perform()''' to line 55. Use button ''Next'' to step-over to next line and ''Send'' to step-into called methods.

You may use the bottom inspector to inspect the value of '''amount''' or local variables. If you double-click to an object value as, say, '''source''' field of the transation object, a new inspector on that object is opened:

[[Datei:expecco_BankAccounts_015.png]]

The code around line 55 in '''Transaction.java''' reads as:

<pre>
54 // Check if destination account would exeeded MAX_BALANCE after crediting.
55 if ((oldDestinationBalance + amount) > Account.MAX_BALANCE) {
56 throw new TransactionException("Maximuma ccount balance exceeded +" + source.getId());
57 }
58
59 long newSourceBalance = oldSourceBalance - amount;
</pre>

It checks if the new balance on destination account would exceed the maximum and of so, just throw an exception as documented.
By inspecting values of '''amount''' and '''oldDestinationBalance''' you may see
that the values are what one would expect, so if you press '''Next''' button,
the execution should enter the if body and throw an exception. If you actually do it, you'll see that the condition is satisfied and the execution proceeds to line 59.

This is clearly a bug in the application code ([http://www.around.com/ariane.html classical integer overflow] in this case). So the test developer may just submit a bug to development team a be done with it.

== To remove ==

<pre>
java -agentlib:jdwp=transportt_socket,server=y,suspend=n,address=3003 \
-cp bin \
-jar "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/agents/JavaBridge.jar"\
-port 5005 -asServer -localOnly \
-extDir "/home/jv/Private/Projects/SmalltalkX/sources/branches/jv1/build/exept/technologyBridge/javaBridge/javaBridge_Server_Client/ext"
</pre>

Testing Java Applications using Groovy blocks/en

2014-10-01T12:09:21Z

Jv: /* Debugging tests */

Datei:Expecco BankAccounts 015.png

2014-10-01T11:54:46Z

Jv:

Datei:Expecco BankAccounts 014.png

2014-10-01T11:34:00Z

Jv:

Datei:Expecco BankAccounts 012.png

2014-10-01T11:28:38Z

Jv:

Datei:Expecco BankAccounts 011.png

2014-10-01T10:39:33Z

Jv:

Testing Java Applications using Groovy blocks/en

2014-10-01T10:21:30Z

Jv:

Testing Java Applications using Groovy blocks/en

2014-10-01T10:20:44Z

Jv: /* Implementing the first test */

Datei:Expecco BankAccounts 010.png

2014-10-01T10:20:27Z

Jv:

Testing Java Applications using Groovy blocks/en

2014-10-01T10:19:48Z

Jv: /* Calling the Java API */

Testing Java Applications using Groovy blocks/en

2014-10-01T10:03:21Z

Jv: /* Calling the Java API */

Testing Java Applications using Groovy blocks/en

2014-10-01T09:41:53Z

Jv: /* Designing a test */

Datei:Expecco BankAccounts 002.png

2014-10-01T09:32:33Z

Jv: Jv lud eine neue Version von „Datei:Expecco BankAccounts 002.png“ hoch

Datei:Expecco BankAccounts 002.png

2014-10-01T09:32:07Z

Jv: Jv lud eine neue Version von „Datei:Expecco BankAccounts 002.png“ hoch

Datei:Expecco BankAccounts 002.png

2014-10-01T09:31:54Z

Jv: Jv lud eine neue Version von „Datei:Expecco BankAccounts 002.png“ hoch

Datei:Expecco BankAccounts 002.png

2014-10-01T09:31:30Z

Jv: Jv lud eine neue Version von „Datei:Expecco BankAccounts 002.png“ hoch

Testing Java Applications using Groovy blocks/en

2014-10-01T09:31:00Z

Jv: /* Designing a test */

Datei:Expecco BankAccounts 006.png

2014-09-30T15:46:17Z

Jv:

Testing Java Applications using Groovy blocks/en

2014-09-30T15:46:01Z

Jv:

Datei:Expecco BankAccounts 005.png

2014-09-30T15:18:53Z

Jv:

Datei:Expecco BankAccounts 002.png

2014-09-30T15:18:32Z

Jv:

Testing Java Applications using Groovy blocks/en

2014-09-30T15:18:08Z

Jv: